@odecloud/sdk

@odecloud/sdk

Official Node.js/TypeScript SDK for the OdeCloud API.

Installation

npm install @odecloud/sdk
# or
yarn add @odecloud/sdk
# or
pnpm add @odecloud/sdk

Quick Start

import { OdeCloud } from '@odecloud/sdk';

const client = new OdeCloud({
  apiKey: 'your-api-key',
});

// Get your profile
const profile = await client.profile.get();
console.log(`Hello, ${profile.firstName}!`);

// List your projects
const projects = await client.projects.list();
console.log(`You have ${projects.data.length} projects`);

// Create a time entry
const entry = await client.timeEntries.create({
  projectId: 'project-123',
  date: '2024-01-15',
  duration: 3600, // 1 hour in seconds
  description: 'Working on feature X',
  billable: true,
});

Configuration

import { OdeCloud } from '@odecloud/sdk';

const client = new OdeCloud({
  // Required: Your API key
  apiKey: 'your-api-key',

  // Optional: Custom base URL (default: https://server.odecloud.app/api/v1/public)
  baseUrl: 'https://server.odecloud.app/api/v1/public',

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,

  // Optional: Max retries for failed requests (default: 3)
  maxRetries: 3,
});

API Reference

Time Entries

// List time entries with filters
const entries = await client.timeEntries.list({
  projectId: 'project-123',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  billable: true,
  page: 1,
  pageSize: 50,
});

// Auto-paginate through all entries
for await (const entry of client.timeEntries.listAutoPaginate({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
})) {
  console.log(entry.description);
}

// Get a single entry
const entry = await client.timeEntries.get('entry-123');

// Create a time entry
const newEntry = await client.timeEntries.create({
  projectId: 'project-123',
  taskId: 'task-456',  // optional
  date: '2024-01-15',
  duration: 7200,      // 2 hours in seconds
  description: 'Implemented new feature',
  billable: true,
});

// Update a time entry
const updated = await client.timeEntries.update('entry-123', {
  description: 'Updated description',
  duration: 3600,
});

// Delete a time entry
await client.timeEntries.delete('entry-123');

// Get summary for a date range
const summary = await client.timeEntries.summary({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  projectId: 'project-123',  // optional
});

console.log(`Total: ${summary.totalDuration} seconds`);
console.log(`Billable: ${summary.billableDuration} seconds`);

// Timer functionality
const timer = await client.timeEntries.startTimer({
  projectId: 'project-123',
  date: '2024-01-15',
  description: 'Starting work',
});

// Later, stop the timer
const completed = await client.timeEntries.stopTimer(timer.id);

Projects

// List projects
const projects = await client.projects.list({
  status: 'active',
  page: 1,
  pageSize: 50,
});

// Auto-paginate through all projects
for await (const project of client.projects.listAutoPaginate()) {
  console.log(project.name);
}

// Get project details (includes tasks and members)
const project = await client.projects.get('project-123');

// List tasks for a project
const tasks = await client.projects.listTasks('project-123');

// Get a specific task
const task = await client.projects.getTask('project-123', 'task-456');

Profile

// Get your profile
const profile = await client.profile.get();

console.log(profile.email);
console.log(profile.firstName);
console.log(profile.lastName);
console.log(profile.tagline);

// Update your profile
const updated = await client.profile.update({
  firstName: 'John',
  lastName: 'Doe',
  tagline: 'Senior Developer',
  aboutMe: 'I love building things.',
  timezone: 'America/New_York',
  socialLinks: {
    linkedin: 'https://linkedin.com/in/johndoe',
    github: 'https://github.com/johndoe',
  },
});

Error Handling

The SDK throws specific error types for different scenarios:

import {
  OdeCloud,
  OdeCloudError,
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
} from '@odecloud/sdk';

try {
  const entry = await client.timeEntries.get('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key (401)
    console.error('Please check your API key');
  } else if (error instanceof ForbiddenError) {
    // Insufficient permissions (403)
    console.error('You do not have permission for this action');
  } else if (error instanceof NotFoundError) {
    // Resource not found (404)
    console.error('Time entry not found');
  } else if (error instanceof ValidationError) {
    // Invalid request data (422)
    console.error('Invalid data:', error.response);
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded (429)
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ServerError) {
    // Server error (5xx)
    console.error('Server error, please try again later');
  } else if (error instanceof OdeCloudError) {
    // Generic API error
    console.error(`API error: ${error.message}`);
  }
}

Pagination

The SDK provides auto-pagination for list endpoints:

// Manual pagination
let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await client.timeEntries.list({ page, pageSize: 100 });

  for (const entry of response.data) {
    console.log(entry.description);
  }

  hasMore = response.hasNextPage;
  page++;
}

// Auto-pagination (recommended)
for await (const entry of client.timeEntries.listAutoPaginate()) {
  console.log(entry.description);
}

// Collect all items into an array
import { collectAll } from '@odecloud/sdk';

const allEntries = await collectAll(
  client.timeEntries.listAutoPaginate()
);

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import {
  OdeCloud,
  TimeEntry,
  TimeEntryCreate,
  Project,
  Profile,
  PaginatedResponse,
} from '@odecloud/sdk';

// Types are automatically inferred
const entries: PaginatedResponse<TimeEntry> = await client.timeEntries.list();

const createData: TimeEntryCreate = {
  projectId: 'project-123',
  date: '2024-01-15',
  duration: 3600,
};

const entry: TimeEntry = await client.timeEntries.create(createData);

Requirements

• Node.js 18+ (for native fetch support)
• TypeScript 4.7+ (if using TypeScript)

API Scopes

Your API key must have the appropriate scopes:

Scope	Description
time:read	Read time entries
time:write	Create, update, delete time entries
projects:read	Read projects and tasks
profile:read	Read your profile
profile:write	Update your profile

Publishing to npm

Prerequisites

• Create an npm account at https://www.npmjs.com/signup
• Log in to npm:

  npm login
  

• If using a scoped package (@odecloud/sdk), create an organization at https://www.npmjs.com/org/create

Build and Publish

# Navigate to the SDK directory
cd odecloud-node

# Install dependencies
npm install

# Build the package
npm run build

# Publish to npm
npm publish --access public

Scoped Package Setup

For the @odecloud scope, ensure:

• The organization odecloud exists on npm
• You're a member of the organization with publish access
• The package.json has "publishConfig": { "access": "public" }

Version Management

Update the version before each release:

# Patch version (1.0.0 -> 1.0.1)
npm version patch

# Minor version (1.0.0 -> 1.1.0)
npm version minor

# Major version (1.0.0 -> 2.0.0)
npm version major

Or manually edit package.json:

{
  "version": "1.0.1"
}

Pre-publish Checklist

# Run tests (if configured)
npm test

# Build and verify
npm run build

# Check what will be published
npm pack --dry-run

# Publish
npm publish --access public

GitHub Actions (Optional)

Add .github/workflows/publish.yml for automated publishing:

name: Publish to npm

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Publish
        run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

npm Token for CI

• Generate a token at https://www.npmjs.com/settings/~/tokens
• Select "Automation" token type
• Add as NPM_TOKEN secret in your GitHub repository settings

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (rebuild on changes)
npm run build -- --watch

# Clean dist folder
rm -rf dist

License

MIT