import { TimeCampAPI } from 'timecamp-api'; const timecampApi = new TimeCampAPI("your-api-key"); // With custom configuration const timecampApi = new TimeCampAPI("your-api-key", { clientName: 'my-awesome-app', timeout: 15000 }); // Get current user const user = await timecampApi.user.get(); console.log(user); // Invite a user to your account await timecampApi.users.invite({ email: 'newuser@example.com', name: 'John Doe' }); // Get tasks const tasksResponse = await timecampApi.tasks.getActiveUserTasks({ user: 'me', includeFullBreadcrumb: true }); if (tasksResponse.success) { console.log(tasksResponse.data); // Array of non-archived tasks } // Get all tasks including archived ones const allTasksResponse = await timecampApi.tasks.getAll(); if (allTasksResponse.success) { console.log(allTasksResponse.data); // Active + archived tasks } // Get favourite tasks for the task picker widget const favourites = await timecampApi.tasks.getFavorites(); console.log(favourites.data.favourites); // Manage favourites await timecampApi.tasks.addFavorite(77390460); await timecampApi.tasks.removeFavorite(77189336); // Update a task and assign users await timecampApi.tasks.update({ task_id: 12345, name: 'Updated Task Name', user_ids: '100,200,300', // Comma-separated user IDs role: 5 // Role ID to assign }); // Tags and Tag Lists const tagLists = await timecampApi.tags.getTagLists(); const tagListId = await timecampApi.tags.createTagList({ name: 'Project Types' }); const tagId = await timecampApi.tags.createTag({ list: tagListId, name: 'Development' }); // Timer operations const timerStatus = await timecampApi.timer.status(); const startedTimer = await timecampApi.timer.start(); const stoppedTimer = await timecampApi.timer.stop(); // Time entries operations const timeEntries = await timecampApi.timeEntries.get({ date_from: '2024-01-01', date_to: '2024-01-31' }); const newEntry = await timecampApi.timeEntries.create({ date: '2024-01-15', duration: 3600, // 1 hour in seconds description: 'Working on API integration', start_time: '09:00:00', end_time: '10:00:00', tags: [{ tagId: 1 }, { tagId: 4 }] // Optional tags }); // Manage tags on time entries const entryTags = await timecampApi.timeEntries.getTags(entryId); await timecampApi.timeEntries.addTags(entryId, [5, 6]); await timecampApi.timeEntries.removeTags(entryId, [4]); const updatedEntry = await timecampApi.timeEntries.update(entryId, { description: 'Updated description', duration: 7200 // 2 hours }); const deleteResult = await timecampApi.timeEntries.delete(entryId); // Computer Activities (max 7 days, includes application names) const activities = await timecampApi.computerActivities.get({ date_from: '2024-01-01', date_to: '2024-01-07', }); // Each activity includes application_name resolved automatically // Computer activities for specific users const userActivities = await timecampApi.computerActivities.get({ date_from: '2024-01-01', date_to: '2024-01-03', user_ids: '123,456', }); // Billing Rates await timecampApi.billingRates.setTaskRate(12345, { rateTypeId: 1, value: 150 }); await timecampApi.billingRates.setUserRate(100, { rateTypeId: 1, value: 100 }); await timecampApi.billingRates.setTaskUserRate(12345, 100, { rateTypeId: 1, value: 175 }); const taskRates = await timecampApi.billingRates.getTaskRates(12345); // Groups const groups = await timecampApi.groups.getAll(); const newGroup = await timecampApi.groups.create({ name: 'Development Team', parent_id: 123 }); await timecampApi.groups.update({ group_id: newGroup.group_id, name: 'Dev Team' }); // Clients const clients = await timecampApi.clients.getAll(); const client = await timecampApi.clients.create({ organizationName: 'Acme Corp', firstName: 'John', lastName: 'Doe', email: 'john@acme.com', }); await timecampApi.clients.update({ clientId: client.clientId, organizationName: 'Acme Corp Updated' }); // Invoices const invoices = await timecampApi.invoices.getAll(); const invoice = await timecampApi.invoices.create({ clientId: client.clientId, issueDate: '2026-02-10', addDate: '2026-02-10', noteToClient: 'From 2026-01-26 to 2026-02-28', currencyId: 1, invoiceNumber: '1223', entries: [ { invoiceId: -1, invoiceEntryId: -1, description: '2026-01-26 07:53 ', type: 0, duration: 19980, quantity: 5.55, unitCost: 109, taxId: 198, name: '[ORG] Administration - Ewelina Łagos', subTotal: 604.95, ttEntriesIds: [263222996], }, ], });

new TimeCampAPI(apiKey: string, config?: TimeCampAPIConfig)

interface TimeCampUser { user_id: string; email: string; register_time: string; display_name: string; synch_time: string; root_group_id: string; }

interface TasksAPIResponse { success: boolean; data?: TimeCampTask[]; message?: string; error?: string; } interface TimeCampTask { task_id: number; parent_id: number; assigned_by?: number; name: string; external_task_id?: string; external_parent_id?: string; task_key?: string | null; level: number; archived: number; keywords?: string; budgeted?: number; budget_unit: string; root_group_id?: number; billable: number; note?: string; public_hash?: string | null; add_date?: string; modify_time?: string; color?: string; user_access_type: number; users?: { [userId: string]: { user_id: number; role_id: number; }; }; groups?: string[]; roles?: string[]; perms?: { [permId: string]: number; }; canTrackTime?: boolean; [key: string]: any; }

interface TimeCampCreateTaskRequest { name: string; // required parent_id?: number; external_task_id?: string; external_parent_id?: string; budgeted?: number; note?: string; archived?: 0 | 1; billable?: 0 | 1; budget_unit?: 'hours' | 'fee' | ''; user_ids?: string; role?: number; keywords?: string; tags?: string; // deprecated } interface TimeCampCreateTaskResponse { [taskId: string]: { task_id: number; parent_id: number; name: string; external_task_id: string | null; external_parent_id: string | null; level: number; add_date: string; archived: number; color: string; tags: string; budgeted: number; checked_date: string | null; root_group_id: number; billable: number; budget_unit: string; note: string | null; keywords: string; // ... additional fields }; }

// Create a simple task const task = await api.tasks.add({ name: 'Development Task' }); // Create a task with external ID (for integrations) const taskWithExternal = await api.tasks.add({ name: 'Xero Invoice Task', external_task_id: 'xero_g8g89s78ds8', external_parent_id: 'xero_2b5b26tb295bb9' }); // Create a child task with full parameters const childTask = await api.tasks.add({ name: 'Backend Development', parent_id: 123456, // number type budgeted: 1000, budget_unit: 'hours', billable: 1, note: 'Development task for API integration', keywords: 'API, Backend, Development' }); // Access the created task data const taskId = Object.keys(task)[0]; const taskData = task[taskId]; console.log(`Created task: ${taskData.name} (ID: ${taskData.task_id})`);

interface TimeCampUpdateTaskRequest { task_id: number; // required name?: string; parent_id?: number; user_ids?: string; // Comma-separated user IDs role?: number; // Role ID for assigned users // ... all other optional parameters from TimeCampCreateTaskRequest }

// Update task name await api.tasks.update({ task_id: 12345, name: 'Updated Task Name' }); // Assign users to a task await api.tasks.update({ task_id: 12345, user_ids: '100,200,300', // Assign users 100, 200, and 300 role: 5 // Assign them role ID 5 }); // Update multiple properties including user assignment await api.tasks.update({ task_id: 12345, name: 'Development Sprint 1', user_ids: '100,200', role: 5, billable: 1, budgeted: 40, budget_unit: 'hours' });

interface TimeCampUserInviteRequest { email: string; name?: string; group_id?: number; } interface TimeCampUserInviteResponse { statuses: { [email: string]: { status: string; // e.g., "Invite", "Already exists", etc. }; }; user_id: string; // Always included after the user is resolved }

// Invite user with automatic group assignment and set display name const result = await timecampApi.users.invite({ email: 'newuser@example.com', name: 'John Doe' }); // Response: {  // statuses: { 'newuser@example.com': { status: 'Invite' } }, // user_id: '123456' // } // Invite user to a specific group with display name const result2 = await timecampApi.users.invite({ email: 'newuser@example.com', name: 'John Doe', group_id: 12345 }); // Invite user without setting a display name (skips name update) const result3 = await timecampApi.users.invite({ email: 'another@example.com', group_id: 12345 }); // Check the invite status and user ID console.log(result.statuses['newuser@example.com'].status); // "Invite" console.log(result.user_id); // "123456"

// List all templates const templates = await timecampApi.customFields.getAll() // Create and delete a template const created = await timecampApi.customFields.add({ name: 'Customer Priority', resourceType: 'user', fieldType: 'string', required: false, defaultValue: '' }) await timecampApi.customFields.delete(created.data.id) // Users await timecampApi.users.getAll() await timecampApi.users.byId(123).getAllCustomFields() await timecampApi.users.byId(123).getCustomField(66) await timecampApi.users.byId(123).setCustomField(66, 'In Progress') await timecampApi.users.byId(123).updateCustomField(66, 'Done') await timecampApi.users.byId(123).deleteCustomField(66) // Tasks await timecampApi.tasks.byId(456).getAllCustomFields() await timecampApi.tasks.byId(456).getCustomField(66) await timecampApi.tasks.byId(456).setCustomField(66, '5') await timecampApi.tasks.byId(456).deleteCustomField(66) // Time Entries await timecampApi.timeEntries.byId(789).getAllCustomFields()

// Get all tag lists const tagLists = await timecampApi.tags.getTagLists(); // Get tag lists with options const tagLists = await timecampApi.tags.getTagLists({ archived: 0, // Exclude archived tags: 1, // Include tags in response exclude_empty_tag_lists: 1 // Exclude empty tag lists }); // Get specific tag list with all its tags const tagList = await timecampApi.tags.getTagList(8); console.log(tagList.name); // "My tag list" console.log(tagList.tags); // Object with tag IDs as keys // Create a new tag list const tagListId = await timecampApi.tags.createTagList({ name: 'Project Types' }); // Update a tag list await timecampApi.tags.updateTagList(tagListId, { name: 'Updated Tag List Name', archived: 0 }); // Get only the tags from a tag list (without tag list details) const tags = await timecampApi.tags.getTagListTags(8);

// Create a new tag in a tag list const tagId = await timecampApi.tags.createTag({ list: 52, // Tag list ID name: 'Development' }); // Get tag details const tag = await timecampApi.tags.getTag(13); console.log(tag.name); // "Development" console.log(tag.tagListId); // "52" // Update a tag await timecampApi.tags.updateTag(13, { name: 'Backend Development', archived: 0 });

// Create time entry with tags const entry = await timecampApi.timeEntries.create({ date: '2024-01-09', duration: 3600, start_time: '09:00', end_time: '10:00', description: 'Development work', task_id: 12345, tags: [ { tagId: 1 }, { tagId: 4 } ] }); // Get tags for a time entry const entryTags = await timecampApi.timeEntries.getTags(101434259); // Returns: { '101434259': [{ tagListName, tagListId, tagId, name, mandatory }] } // Add tags to an existing time entry await timecampApi.timeEntries.addTags(101434259, [13, 14]); // Returns: ['13'] (IDs of successfully added tags) // Remove tags from time entry await timecampApi.timeEntries.removeTags(101434259, [15]); // Returns: ['15'] (IDs of successfully removed tags)

// Get activities for current user (default: 'me') const activities = await timecampApi.computerActivities.get({ date_from: '2024-01-01', date_to: '2024-01-07', }); // Get activities for specific users const activities = await timecampApi.computerActivities.get({ date_from: '2024-01-01', date_to: '2024-01-03', user_ids: '123,456', }); // Each activity includes the resolved application_name for (const activity of activities) { console.log(`${activity.date} ${activity.start_time} - ${activity.application_name}: ${activity.window_title}`); }

interface TimeCampComputerActivitiesRequest { date_from: string; // YYYY-MM-DD format (required) date_to: string; // YYYY-MM-DD format (required) user_ids?: string; // Comma-separated user IDs or 'me' (default: 'me') } interface TimeCampComputerActivity { user_id: string; application_id: string; end_time: string; time_span: number; window_title_id: string; end_date: string; task_id: string; entry_id: string; updated_at: string; update_date: string; application_name?: string; // Resolved from /application endpoint application_info?: string; // Additional info (e.g. domain) }

// Get all billing rates for a task const taskRates = await timecampApi.billingRates.getTaskRates(12345); // Returns: { '12345': [{ rateId, rateTypeId, value, refType, addDate, refId }] } // Get specific rate type for a task const taskRates = await timecampApi.billingRates.getTaskRates(12345, '1,2'); // Comma-separated rate type IDs // Set or update a task billing rate const rate = await timecampApi.billingRates.setTaskRate(12345, { rateTypeId: 1, value: 150, addDate: '2024-01-09' // Optional });

// Get all billing rates for a user const userRates = await timecampApi.billingRates.getUserRates(100); // Set or update a user billing rate const rate = await timecampApi.billingRates.setUserRate(100, { rateTypeId: 1, value: 100 });

// Get task-user specific rates const taskUserRates = await timecampApi.billingRates.getTaskUserRates(12345, 100); // Set task-user specific rate (overrides task and user rates) const rate = await timecampApi.billingRates.setTaskUserRate(12345, 100, { rateTypeId: 1, value: 175 // Higher rate for this user on this specific task });

// Get all billing rates for a group const groupRates = await timecampApi.billingRates.getGroupRates(50); // Set or update a group billing rate const rate = await timecampApi.billingRates.setGroupRate(50, { rateTypeId: 1, value: 125 });

// Get all rate types const rateTypes = await timecampApi.billingRates.getRateTypes();

interface TimeCampSetRateRequest { rateTypeId: number; // Rate type identifier value: number; // Rate value (e.g., hourly rate) addDate?: string; // Optional date in YYYY-MM-DD format } interface TimeCampBillingRate { rateId: number; rateTypeId: number; value: string; refType: string; // 'task', 'user', 'task_user', or 'group' addDate: string; refId: string; } interface TimeCampRateType { rateTypeId: number; name: string; isCost: boolean; }

// Get all groups const groups = await timecampApi.groups.getAll(); console.log(groups); // [{ group_id: 530222, name: 'People', parent_id: 0 }] // Create a new group under a parent const newGroup = await timecampApi.groups.create({ name: 'Development Team', parent_id: 530222 }); console.log(newGroup.group_id); // 390673 console.log(newGroup.root_group_id); // 530222 // Create a root group (parent_id defaults to 0 if not provided) const rootGroup = await timecampApi.groups.create({ name: 'New Organization' }); // Update a group's name await timecampApi.groups.update({ group_id: 390673, name: 'Backend Development' }); // Move a group to a different parent await timecampApi.groups.update({ group_id: 390673, parent_id: 123456 // New parent group ID }); // Update both name and parent await timecampApi.groups.update({ group_id: 390673, name: 'Backend Team', parent_id: 123456 }); // Delete a group await timecampApi.groups.delete(390673);

interface TimeCampCreateGroupRequest { name: string; // Group name (required) parent_id?: number; // Parent group ID (optional, defaults to 0 for root) } interface TimeCampGroup { group_id: number; name: string; parent_id: number; admin_id?: number; root_group_id?: number; } interface TimeCampUpdateGroupRequest { group_id: number; // Group ID to update (required) name?: string; // New name (optional) parent_id?: number; // New parent ID (optional) }

// List all clients const clients = await timecampApi.clients.getAll(); console.log('Clients:', clients); // Create a client const client = await timecampApi.clients.create({ organizationName: 'Acme Corp', firstName: 'John', lastName: 'Doe', email: 'john@acme.com', }); console.log('Created client:', client); // Update a client const updatedClient = await timecampApi.clients.update({ clientId: client.clientId, organizationName: 'Acme Corp Updated', address: '123 Main St, New York, NY', }); console.log('Updated client:', updatedClient); // Get tasks assigned to a client const clientTasks = await timecampApi.clients.getTasks(client.clientId); // Get tasks for multiple clients at once const multiClientTasks = await timecampApi.clients.getTasks([1412133, 1412134]); // Remove tasks from a client await timecampApi.clients.removeTasks(client.clientId, [101, 102]); // Delete a client (will fail if client has invoices) await timecampApi.clients.delete(client.clientId);

interface TimeCampClient { clientId: number; firstName: string; lastName: string; organizationName: string; address: string; currencyId: number; email: string; rootGroupId: number; addedBy: number; added: string; } interface TimeCampCreateClientRequest { organizationName: string; // required firstName?: string; lastName?: string; address?: string; currencyId?: number; email?: string; } interface TimeCampUpdateClientRequest { clientId: number; // required organizationName?: string; firstName?: string; lastName?: string; address?: string; currencyId?: number; email?: string; }

// List all invoices const invoices = await timecampApi.invoices.getAll(); console.log('Invoices:', invoices); // Create an invoice from time entries const invoice = await timecampApi.invoices.create({ clientId: 1412133, issueDate: '2026-02-10', addDate: '2026-02-10', noteToClient: 'From 2026-01-26 to 2026-02-28', currencyId: 1, invoiceNumber: '1223', entries: [ { invoiceId: -1, invoiceEntryId: -1, description: '2026-01-26 07:53 ', type: 0, duration: 19980, quantity: 5.55, unitCost: 109, taxId: 198, name: '[ORG] Administration - Ewelina Łagos', subTotal: 604.95, ttEntriesIds: [263222996], }, ], }); console.log('Created invoice:', invoice); // Update an existing invoice const updatedInvoice = await timecampApi.invoices.update({ invoiceId: invoice.invoiceId, noteToClient: 'Updated note', status: 1, }); console.log('Updated invoice:', updatedInvoice); // Delete an invoice await timecampApi.invoices.delete(invoice.invoiceId);

interface TimeCampInvoice { invoiceId: number; clientId: number; invoiceNumber: string; description: string; issueDate: string; dueDate: string; editDate: string; status: number; sentDate: string; viewedDate: string; addDate: string; paidDate: string; noteToClient: string; pass: string; poNumber: string; userId: number; currencyId: number; rootGroupId: string; publicHash: string; storedFileId: number | null; quote: boolean; entries: TimeCampInvoiceEntry[]; } interface TimeCampInvoiceEntry { invoiceId: number; invoiceEntryId: number; description: string; type: number; quantity: number; duration: number; unitCost: number; taxId: number; name: string; subTotal?: number; ttEntriesIds?: number[]; } interface TimeCampCreateInvoiceRequest { clientId: number; // required issueDate: string; // required entries: TimeCampCreateInvoiceEntryRequest[]; // required invoiceNumber?: string; description?: string; addDate?: string; dueDate?: string; noteToClient?: string; currencyId?: number; status?: number; userId?: number; rootGroupId?: number; quote?: boolean; // ... additional optional fields }

interface TimerStartRequest { task_id?: number; note?: string; started_at?: string; // ISO 8601 format }

interface TimerStopRequest { stopped_at?: string; // ISO 8601 format }

interface TimerStatus { timer_id?: number; task_id?: number; start_time?: string; running: boolean; duration?: number; } interface TimerEntry { id: number; task_id: number; user_id: number; name: string; note: string; start_time: string; end_time: string | null; duration: number; locked: boolean; billable: boolean; invoiced: boolean; approved: boolean; }

interface TimeCampTimeEntriesRequest { user_id?: string; task_id?: string; date_from?: string; date_to?: string; format?: string; } interface TimeCampTimeEntry { id: number; duration: number; // Duration in seconds user_id: string; user_name: string; task_id: string; task_note?: string; last_modify: string; date: string; start_time: string; end_time: string; locked: string; name: string; addons_external_id: string; billable: number; invoiceId: string; color: string; description: string; tags: TimeCampTag[]; hasEntryLocationHistory: boolean; } interface TimeCampTag { tagListName: string; tagListId: string; tagId: string; name: string; mandatory: string; }

interface TimeCampCreateTimeEntryRequest { date: string; duration: number; // in seconds task_id?: number; description?: string; start_time: string; end_time: string; user_id?: number; billable?: boolean; tags?: Array<{ tagId: number }>; // Optional tags to add on creation } interface TimeCampCreateTimeEntryResponse { success: boolean; id?: string; message: string; }