Node SDK
Official TypeScript SDK for TimeCampus — programmatic access to time entries, projects, tasks, approvals, expenses, meetings, and more.
Install
bun add @timecampus/sdk
# or
npm install @timecampus/sdk
Quick start
import { TimecampusSDK } from '@timecampus/sdk';
const sdk = new TimecampusSDK();
// Sign in
await sdk.auth.signIn({ username: '[email protected]', password: 'secret' });
// Fetch workspaces and issue workspace token
const workspaces = await sdk.auth.fetchWorkspaces();
await sdk.auth.issueWorkspaceToken(workspaces[0].id, workspaces[0].organizationId);
// Use the SDK
const timeEntries = await sdk.timecampus.timeEntries.list();
const projects = await sdk.timecampus.projects.list();
Configuration
The SDK defaults to production endpoints. Override via environment variables or constructor args:
interface TimecampusSDKConfig {
workspaceEndpoint?: string; // default: prod workspace gateway
globalEndpoint?: string; // default: prod global gateway
oidcIssuer?: string; // derived from globalEndpoint if omitted
clientId?: string; // OAuth2 client ID
clientSecret?: string; // OAuth2 client secret
redirectUri?: string; // redirect URI for auth code flow
apiKey?: string; // API key authentication
accessToken?: string; // pre-existing access token
refreshToken?: string; // pre-existing refresh token
workspaceToken?: string; // pre-existing workspace token
timeout?: number; // ms (default: 30000)
autoRefresh?: boolean; // auto-refresh tokens (default: true)
onTokenRefresh?: (tokens: TokenPair) => void | Promise<void>;
}
Environment variable resolution order (highest to lowest):
- Constructor argument
- Product-prefixed env var (
TIMECAMPUS_WORKSPACE_ENDPOINT,TIMECAMPUS_GLOBAL_ENDPOINT) - Generic env var (
BURDENOFF_WORKSPACE_ENDPOINT,BURDENOFF_GLOBAL_ENDPOINT) - Production defaults
Authentication
Email / password
const auth = await sdk.auth.signIn({ username: '[email protected]', password: 'secret' });
OAuth2 device code
const { userCode, verificationUri, promise } = await sdk.auth.loginWithDeviceCode();
console.log(`Open ${verificationUri} and enter: ${userCode}`);
const tokens = await promise;
Client credentials (M2M)
const result = await sdk.auth.authenticateApp(clientId, clientSecret);
Workspace token
await sdk.auth.issueWorkspaceToken(workspaceId, organizationId);
Modules
The SDK is a thin shell over @burdenoff/sdk-libs. Each domain is mounted as a nested namespace.
| Namespace | Description |
|---|---|
sdk.auth | Sign in/up, OAuth flows, token management |
sdk.timecampus | TimeCampus domain — timeEntries, projects, tasks, approvals, expenses, meetings, pomodoro, appUsage, focusScores, workPatterns, geofences, locations, channels, clientPortals, resourcePlans, configurations, uiSessions |
sdk.sandbox | Ephemeral, TTL-bound sandbox environments |
sdk.billing | Subscriptions, invoices, plans, addons, credits, refunds |
sdk.channels | Channel-based pub/sub |
sdk.conversations | Conversation CRUD + settings |
sdk.devportal | Apps, OAuth, API keys, webhooks, delegations |
sdk.export | Export jobs, templates, downloads |
sdk.files | Browse, upload, share files |
sdk.groups | Group management |
sdk.health | Gateway/service health probes |
sdk.integrations | Third-party integrations + connections |
sdk.notifications | Notification center + preferences |
sdk.organizations | Organizations + invites |
sdk.products | Products, shortcuts, content pages, feature flags |
sdk.rbac | Permissions, role assignment |
sdk.scheduler | Scheduled jobs + executions |
sdk.security | Vaults, secrets |
sdk.store | Marketplace — search, cart, orders, installs, publisher |
sdk.support | Tickets + knowledge base |
sdk.tags | Tag CRUD + tagging |
sdk.tours | Onboarding tours + progress |
sdk.workspaces | Workspace CRUD + members + projects + invites |
Error handling
import { TimecampusError, AuthenticationError, NetworkError } from '@timecampus/sdk';
try {
await sdk.auth.signIn({ username: 'invalid', password: 'invalid' });
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Auth failed:', error.message);
} else if (error instanceof NetworkError) {
console.error('Network error:', error.message);
}
}
Development
git clone https://github.com/algoshred/timecampus-sdk-node.git
cd timecampus-sdk-node
bun install
bun run dev # Watch mode
bun run build # Production build
bun run test # Run tests
bun run sanity # All checks (format, lint, type-check, test, build)
Source
Published as @timecampus/sdk on npm; source at github.com/algoshred/timecampus-sdk-node.