usertasksDocs
Sign in

CLI, SDK and config

TypeScript SDK

A typed client for the REST API, generated from the OpenAPI document, with retries, pagination, events and OAuth helpers.

@usertasks/sdk is a typed TypeScript client for /api/v1. Its types are generated from the server's OpenAPI 3.1 document, which ships with the package as @usertasks/sdk/openapi.json. It is ESM-only and runs on Node.js 20+ or any runtime with fetch.

bash
npm install @usertasks/sdk
ts
import { apiKeyAuth, createClient, isUsertasksApiError } from '@usertasks/sdk'

const client = createClient({
  baseUrl: 'https://tasks.example.com',
  auth: apiKeyAuth(process.env.USERTASKS_API_KEY!),
})

// Typed by path and method; the { success, data } envelope is unwrapped.
const { workflows } = await client.GET('/workflows', { query: { limit: 10 } })

const run = await client.POST('/workflows/start', {
  body: { workflow_id: workflows[0].id, variables: { amount: 1200 }, async: true },
})

// Every page of a list endpoint
for await (const user of client.paginate('/users')) console.log(user.email)

try {
  await client.DELETE('/roles/{id}', { path: { id: 'system-role-id' } })
} catch (error) {
  if (isUsertasksApiError(error)) console.error(error.status, error.code, error.message, error.details)
}

Events

ts
for await (const event of client.events.stream({ category: 'workflow', severity: 'warn' })) {
  console.log(event.type, event.message)   // reconnects with Last-Event-ID, no gaps
}

client.events.list() pages with a cursor and client.events.iterate() walks every page.

Behaviour

  • Errors — a failed request throws UsertasksApiError (status, code, details, requestId); a network failure throws UsertasksNetworkError.
  • Retries — idempotent requests are retried on 429, 5xx and network errors with backoff that honours Retry-After.
  • Untyped calls — client.request(method, path, options) calls any endpoint.
  • OAuth — oauthAuth() refreshes tokens automatically (never twice at once, and with a lock if your token store provides one). Helpers cover PKCE (generateCodeVerifier, codeChallengeS256), discovery, code exchange, refresh, revocation and dynamic client registration.
  • Operation metadata — OPERATIONS lists each operation's method, path, permission and CLI command.