@koderlabs/tasks-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,180 @@
-# Proprietary Software
+# @koderlabs/tasks-sdk
 
-KoderLabs proprietary. All rights reserved.
+> Runtime: any JS — browser, Node, React Native, edge workers.
+> Platform-agnostic core for the **InstantTasks SDK suite**.
 
-See the bundled `LICENSE` for terms. No grant of any rights, express or
-implied, is conferred by access to or possession of this package. A
-separate signed written licence from KoderLabs is required for any use.
+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.
 
-Licensing inquiries: jawaidgadiwala@gmail.com
+## Install
+
+```bash
+npm install @koderlabs/tasks-sdk
+# or
+pnpm add @koderlabs/tasks-sdk
+# or
+yarn add @koderlabs/tasks-sdk
+```
+
+## Quick start
+
+```ts
+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
+
+```ts
+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`](./LICENSE) for terms. Use of this package
+requires a separate signed written agreement with KoderLabs; access alone
+confers no rights.
+
+Licensing inquiries: **jawaidgadiwala@gmail.com**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koderlabs/tasks-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "InstantTasks SDK — platform-agnostic event + span client.",
   "keywords": [
     "instanttasks",
@@ -40,7 +40,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@koderlabs/tasks-sdk-types": "0.1.0"
+    "@koderlabs/tasks-sdk-types": "0.1.2"
   },
   "devDependencies": {
     "tsup": "^8.3.0",
@@ -51,7 +51,7 @@
     "node": ">=20"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "scripts": {
     "build": "tsup",