Overview

• Every operation reads. This plugin covers DeskTime’s read actions, so nothing here can change an account. All seven operations are read and none is irreversible. DeskTime also has create-project, start-project and stop-project, which do change an account; they are not part of this plugin.
• Every call needs a key. ping is served openly by DeskTime, but the Corsair runtime resolves the account key before any endpoint runs, so a call without one raises AuthMissingError like the rest.
• Keys are per tenant. Each tenant saves the key of its own DeskTime account, through a connect link or with corsair.withTenant(id).desktime.keys.set_api_key(key). desktime({ key }) at registration is sent for every tenant and takes priority over their saved keys, so every tenant would read that one account’s employees. Pass it only when the whole app reads a single DeskTime account.
• The API returns mixed field casing. groupId and onlineTime are camelCase while work_starts and notes are snake_case, and this plugin keeps the names exactly as sent.
• arrived, left, work_starts and work_ends are timestamps or the boolean false. The help-center examples only show the timestamp form, so a schema that assumes a string rejects every response for an employee who has not clocked in yet.
• A bad date or period is ignored, not rejected. DeskTime answers with today’s data instead of an error, so this plugin validates both before sending. Dates must be real calendar days, not just the right shape.
• employees.list nests two levels deep. The response is keyed by date, then by employee id, so a week request returns seven buckets. period accepts day, week or month. This plugin also exposes a flattened buckets array, newest first, with the date kept on each entry.
• employee.apps groups by productivity class. The raw keys are -1 unrated, 0 neutral and 1 productive; a labelled apps_by_productivity map is returned alongside them.
• Rate limits. DeskTime sends x-ratelimit-limit: 600 and no Retry-After. A 429 is retried after the header if present, otherwise after one minute. A 401 or 403 is never retried, because only a person can fix a key.
• No webhooks. DeskTime sends none, so the plugin declares no webhook surface.

• 7 typed API operations

​

Setup

npm install corsair @corsair-dev/desktime better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/desktime better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/desktime better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/desktime better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { desktime } from '@corsair-dev/desktime';

export const corsair = createCorsair({
	plugins: [
		desktime(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

desktime()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'desktime',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.desktime.api.employees.list({ date: '2026-11-02' });

const tenant = corsair.withTenant('acme');
await tenant.desktime.api.employee.apps({ id: 789760 });

​

What’s next