Timesheet TypeScript SDK

The official TypeScript SDK for the Timesheet API, providing a comprehensive solution for time tracking, project management, and team collaboration.

Features

• ✅ Type-Safe - Full TypeScript support with comprehensive types
• ✅ Modern Architecture - Promise-based with async/await support
• ✅ Authentication - Built-in API Key and OAuth2 support
• ✅ Error Handling - Typed exceptions for better error management
• ✅ Pagination - Automatic pagination with async iterators
• ✅ Retry Logic - Configurable retry with exponential backoff
• ✅ Lightweight - Minimal dependencies
• ✅ Tree-Shakeable - Import only what you need
• ✅ Well Documented - Extensive JSDoc and examples

Installation

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

Quick Start

import { TimesheetClient } from '@timesheet/sdk';

// Initialize with API key
const client = new TimesheetClient({
  apiKey: 'your-api-key'
});

// Create a project
const project = await client.projects.create({
  title: 'My Project',
  description: 'Created with TypeScript SDK'
});

// Start a timer
const timer = await client.timer.start({
  projectId: project.id,
  startDateTime: new Date().toISOString()
});

// List recent tasks
const tasks = await client.tasks.list({
  limit: 10,
  sort: 'created',
  order: 'desc'
});

console.log(`Found ${tasks.params.count} tasks`);

Authentication

API Key Authentication

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

OAuth2 Authentication

const client = new TimesheetClient({
  oauth2Token: 'your-access-token'
});

// With automatic token refresh
const client = new TimesheetClient({
  oauth2: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    refreshToken: 'your-refresh-token'
  }
});

Resources

All API resources are available through the client:

client.tasks         // Task management
client.projects      // Project management
client.tags          // Tag management
client.teams         // Team management
client.organizations // Organization settings
client.timer         // Real-time time tracking
client.rates         // Billing rates
client.expenses      // Expense tracking
client.notes         // Note attachments
client.pauses        // Break time tracking
client.documents     // Document generation
client.webhooks      // Event notifications
client.automations   // Time tracking automation
client.todos         // Task management
client.profile       // User profile
client.settings      // User settings

Examples

Task Management

// Create a task
const task = await client.tasks.create({
  projectId: 'project-id',
  description: 'Implement new feature',
  startDateTime: new Date(Date.now() - 3600000).toISOString(), // 1 hour ago
  endDateTime: new Date().toISOString(),
  tagIds: ['tag-1', 'tag-2'],
  billable: true
});

// Update task
await client.tasks.update(task.id, {
  description: 'Implement new feature - completed'
});

// Search tasks
const results = await client.tasks.searchAdvanced({
  projectIds: ['project-id'],
  search: 'feature',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Project Management

// Create a project
const project = await client.projects.create({
  title: 'New Website',
  teamId: 'team-id',
  color: 3,
  taskDefaultBillable: true
});

// List projects with filters
const projects = await client.projects.list({
  status: 'active',
  limit: 20
});

Timer Operations

// Start a timer
const timer = await client.timer.start({
  projectId: 'project-id',
  startDateTime: new Date().toISOString()
});

// Pause the timer
await client.timer.pause({
  startDateTime: new Date().toISOString()
});

// Resume the timer
await client.timer.resume({
  endDateTime: new Date().toISOString()
});

// Stop and create task
const stoppedTimer = await client.timer.stop({
  endDateTime: new Date().toISOString()
});

Pagination

// Manual pagination
const firstPage = await client.tasks.list({ limit: 50 });
console.log(`Page ${firstPage.params.page} of ${firstPage.totalPages}`);
console.log(`Total items: ${firstPage.params.count}`);

// Get next page
if (firstPage.hasNextPage) {
  const nextPage = await firstPage.nextPage();
}

// Auto-pagination with async iterator
const allTasks = await client.tasks.list({ projectId: 'project-id' });
for await (const task of allTasks) {
  console.log(task.description);
}

// Collect all results across all pages
const allTasksArray = await client.tasks.list({ 
  projectId: 'project-id' 
}).then(page => page.toArray());

Error Handling

import { 
  TimesheetApiError,
  TimesheetAuthError,
  TimesheetRateLimitError
} from '@timesheet/sdk';

try {
  const task = await client.tasks.get('task-id');
} catch (error) {
  if (error instanceof TimesheetAuthError) {
    console.error('Authentication failed');
  } else if (error instanceof TimesheetRateLimitError) {
    console.error(`Rate limited. Retry after: ${error.retryAfter}s`);
  } else if (error instanceof TimesheetApiError) {
    console.error(`API error: ${error.statusCode} - ${error.message}`);
  }
}

TypeScript Support

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

import type { 
  Task,
  Project,
  TaskCreateRequest,
  TaskListQueryParams,
  NavigablePage
} from '@timesheet/sdk';

// All methods are fully typed
const task: Task = await client.tasks.get('task-id');
const projects: NavigablePage<Project> = await client.projects.list();

// Type-safe parameters
const params: TaskCreateRequest = {
  projectId: 'project-id',
  description: 'Task description',
  billable: true,
  startDateTime: new Date().toISOString()
};

Documentation

• API Documentation
• TypeScript API Reference
• Examples

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development

# Clone the repository
git clone https://github.com/timesheetIO/timesheet-typescript.git
cd timesheet-typescript

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Generate documentation
npm run docs

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues

License

This SDK is distributed under the Apache License 2.0.

Changelog

See CHANGELOG.md for a list of changes.

Made with ❤️ by the timesheet.io team