@koderlabs/tasks-sdk

Runtime: any JS — browser, Node, React Native, edge workers. Platform-agnostic core for the InstantTasks SDK suite.

Core client + transport. Owns init(), the singleton client, span/trace IDs, the integration registration surface, request signing, PII scrubbing, retries + backoff, and the platform abstractions every other package plugs into.

Install

npm install @koderlabs/tasks-sdk
# or
pnpm add @koderlabs/tasks-sdk
# or
yarn add @koderlabs/tasks-sdk

Quick start

import { init } from '@koderlabs/tasks-sdk';

const client = init({
  projectId:  'FE',                            // Project key from InstantTasks
  accessKey:  'sk_live_…',                     // SDK ingest key (Project → SDK Keys)
  endpoint:   'https://tasks.koderlabs.net',   // root only — no /api/v1 suffix
  release:    process.env.APP_VERSION,         // commit SHA or semver
  environment: process.env.NODE_ENV,
  integrations: [],                            // see suite map below
});

init() is idempotent. Calling it again synchronously flushes spans, runs integration teardowns, and replaces the prior client. Safe across HMR and React StrictMode double-mount.

The InstantTasks SDK suite

Pick the packages that match your runtime; ignore the rest.

                  @koderlabs/tasks-sdk            (core — this package)
                  @koderlabs/tasks-sdk-types      (wire shapes)
                          │
       ┌──────────────────┼──────────────────┬────────────────┐
       │ Web (DOM)        │ React Native     │ Server (Node)  │ Tooling
       ├ tasks-sdk-web-errors     ├ tasks-sdk-rn        ├ tasks-sdk-nestjs   ├ tasks-cli
       ├ tasks-sdk-web-network    └ tasks-sdk-rn-native │                   ├ tasks-mcp
       ├ tasks-sdk-web-reporter      (native crashes)   │
       │
   Framework adapters
   ├ @koderlabs/tasks-sdk-react        — Provider, hooks, ErrorBoundary
   ├ @koderlabs/tasks-sdk-nextjs       — next.config plugin + sourcemap upload
   └ @koderlabs/tasks-sdk-vue          — Vue 3 plugin

Pick your stack

| Stack | Install | |---|---| | Vanilla browser | tasks-sdk + tasks-sdk-web-errors + tasks-sdk-web-network (+ -web-reporter for bug modal) | | React | tasks-sdk + tasks-sdk-react + the web-* packages above | | Next.js | tasks-sdk + tasks-sdk-nextjs + the web-* packages above | | Vue 3 | tasks-sdk + tasks-sdk-vue + the web-* packages above | | React Native | tasks-sdk + tasks-sdk-rn (+ -rn-native for native crashes, -rn-reporter for bug modal) | | NestJS | tasks-sdk + tasks-sdk-nestjs | | Other Node | tasks-sdk (use reportError() from getClient() directly) | | Sourcemap/symbol upload | tasks-cli | | MCP agent integration | tasks-mcp (separate npm package) |

InitOptions

| Field | Type | Default | Notes | |---|---|---|---| | projectId | string | required | Project key. Sent as X-Project-Id. CRLF-validated. | | accessKey | string | required | SDK ingest key. Sent as Authorization: Bearer …. CRLF-validated. | | endpoint | string | https://tasks.koderlabs.net | Root only. SDK appends /api/v1/sdk/events. HTTPS-only outside localhost (SSRF guard). | | release | string | — | Commit SHA or semver. Required for source-map symbolication. | | environment | string | — | production, staging, etc. | | user | { id?, email? } | — | Default user attached to events. | | customData | Record<string, Serializable> | — | Default custom data. | | integrations | Integration[] | [] | Plug-in integrations. | | debug | boolean | false | Internal-logger output. Suppressed in NODE_ENV=production regardless. | | dryRun | boolean | false | Build events but don't POST. | | beforeSend | (event) => event \| null | — | Mutate / drop events. May be async. Fail-closed: a throw drops the event and emits beforesend_error. | | scrub | boolean \| (event) => event | true | Built-in PII scrubber (Authorization/Cookie headers, password/token/secret fields, URL query params). Set false to disable; pass a function to override. | | fetch | typeof fetch | globalThis.fetch | Custom fetch impl (e.g. RN TLS-pinned fetch). | | signingSecret | string | — | If set, every request is HMAC-SHA256 signed (X-IT-Timestamp, X-IT-Nonce, X-IT-Signature). Backend verifies when project requires signed events. |

Surface

| Export | Purpose | |---|---| | init(opts) | Create / replace the singleton client. | | getClient() | Read the current client or null. | | Client | Class (rarely used directly). | | newTraceId(), newSpanId() | ID generators for manual spans. | | captureWebVitals(opts) | LCP / CLS / INP / FCP / TTFB capture (browser only). Debounced per metric. | | TransportHttpError, PayloadTooLargeError | Error types thrown by transport. | | Types | InitOptions, Integration, ClientInterface, SpanRecord, ActiveSpan, SpanOptions, WebVitalsOptions + all @koderlabs/tasks-sdk-types re-exports. |

Behaviour

| Concern | Behaviour | |---|---| | Request timeout | 10s via AbortSignal.timeout() (polyfilled for old RN) | | Payload cap | 500 KB serialised. Throws PayloadTooLargeError — no retry. | | Retry | Exp backoff (1s, 2s) for 5xx; never for 4xx. Max 2 retries. | | 429 handling | Honors Retry-After header; sets cooldown window; drops subsequent events until elapsed. Listener event send_rate_limited. | | PII scrubbing | Default on. Runs BEFORE beforeSend so caller sees scrubbed event. | | init() re-call | Tears down prior client synchronously: flush spans, stop interval, run each integration's teardown(). | | beforeSend failure | Drops event, emits beforesend_error (fail-closed). | | Console output | Gated by debug && NODE_ENV!=='production'. Programming errors always log via internalError. | | Span batching | 50-span buffer, 5s flush interval. client.flushSpans() for explicit drain. |

Writing an integration

import type { Integration, ClientInterface } from '@koderlabs/tasks-sdk';

export function myIntegration(): Integration {
  let teardown = () => {};
  return {
    name: 'my-integration',
    setup(client: ClientInterface) {
      // Hook into globals, register listeners, etc.
      teardown = () => { /* undo */ };
    },
    teardown() { teardown(); },
  };
}

init() calls setup() in registration order. On re-init, every prior integration's teardown() runs before the new client boots.

Transport contract

POST {endpoint}/api/v1/sdk/events
Headers:
  Authorization: Bearer {accessKey}
  X-Project-Id:  {projectId}
  Content-Type:  application/json
  [X-IT-Timestamp / X-IT-Nonce / X-IT-Signature if signingSecret set]
Body:    AnyEvent (see @koderlabs/tasks-sdk-types)
Response: { id: string, ticketKey?: string }

Multipart variant /api/v1/sdk/events/multipart for bug reports with screenshots.

Caveats

• endpoint must be the root URL. Do not include /api/v1 — SDK appends.
• Default endpoint https://tasks.koderlabs.net emits a one-time deprecation warning. Set endpoint explicitly; default will throw in next major.
• No offline buffer in v1. Events dropped during net loss are lost (unless 429 with Retry-After — then queued briefly).
• Spans are best-effort: flushed on 5s interval and on client.flushSpans(). Process exits before flush = lost.
• signingSecret only signs JSON bodies. Multipart (bug reports w/ screenshots) is NOT signed — multipart boundaries make the hash unstable.

Versioning

This package and all @koderlabs/tasks-sdk-* siblings move together until v1.0. Always upgrade them as a set (@koderlabs/tasks-sdk + @koderlabs/tasks-sdk-XXX at the same version).

License

KoderLabs proprietary. See LICENSE for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.

Licensing inquiries: [email protected]