@craftedxp/sdk-node 0.2.0

package/CONSUMING.md

@@ -0,0 +1,119 @@
+# Consuming @craftedxp/sdk-node
+
+Three install paths, fastest → production. Pick one.
+
+## TL;DR
+
+```bash
+# In YOUR Node.js / TypeScript project
+npm install /path/to/craftedxp-sdk-node-0.2.0.tgz   # or git+ssh, or (eventually) @craftedxp/sdk-node
+```
+
+```ts
+import { PlatformClient } from '@craftedxp/sdk-node'
+
+const client = new PlatformClient({ apiKey: process.env.VOICE_AGENT_SK! })
+const me = await client.me.get()
+```
+
+Node 18+. No peer deps, no native modules, no `pod install`. Pure JS.
+
+---
+
+## Path 1 — Local tarball (fastest)
+
+In the SDK repo:
+
+```bash
+cd voice-assistant/sdk/node
+npm install
+npm pack                  # emits craftedxp-sdk-node-0.2.0.tgz
+```
+
+In your app:
+
+```bash
+npm install /abs/path/to/voice-assistant/sdk/node/craftedxp-sdk-node-0.2.0.tgz
+```
+
+`npm pack` runs the `prepare` hook, which rebuilds `dist/`, so the tarball ships `dist/index.js` (CJS) + `dist/index.mjs` (ESM) + `dist/index.d.ts` + sourcemaps — and nothing else.
+
+When the SDK changes, re-run `npm pack` and re-install.
+
+---
+
+## Path 2 — Git dependency
+
+Works once you've subtree-split the SDK into its own repo:
+
+```bash
+# one-time, in the main repo
+git subtree split --prefix=sdk/node -b sdk-node
+git push git@github.com:your-org/sdk-node.git sdk-node:main
+```
+
+Then in your app:
+
+```jsonc
+{
+  "dependencies": {
+    "@craftedxp/sdk-node": "git+ssh://git@github.com:your-org/sdk-node.git#v0.1.0",
+  },
+}
+```
+
+npm clones + runs `prepare`, which rebuilds `dist/`. Tag releases (`git tag v0.1.0`) so your pins are stable.
+
+---
+
+## Path 3 — npm registry (production)
+
+```bash
+cd voice-assistant/sdk/node
+npm login
+npm publish --access public
+```
+
+Consumer side:
+
+```bash
+npm install @craftedxp/sdk-node
+```
+
+For private distribution, see GitHub Packages / Verdaccio / npm Enterprise — same pattern as the sibling React Native SDK.
+
+---
+
+## Runtime requirements
+
+- **Node ≥ 18** — needed for native `fetch`, `FormData`, `Blob`, `AbortController`. These were stabilised in 18.x; older Nodes would need polyfills we don't want to carry.
+- **Bundler-friendly** — emits proper `"exports"` with conditional CJS + ESM + types. Works in Next.js (server), Fastify, Express, plain scripts, tests (Vitest / Jest), Cloud Functions, Cloud Run.
+
+---
+
+## Environment
+
+Set your API key via environment variable — never hard-code an `sk_` value:
+
+```bash
+# .env
+VOICE_AGENT_SK=sk_your_key_here
+VOICE_AGENT_BASE_URL=http://localhost:8080     # for local dev
+```
+
+```ts
+const client = new PlatformClient({
+  apiKey: process.env.VOICE_AGENT_SK!,
+  baseUrl: process.env.VOICE_AGENT_BASE_URL,
+})
+```
+
+---
+
+## Troubleshooting
+
+- **`TypeError: fetch is not a function`** — Node version is below 18. Upgrade, or pass a `fetch` implementation explicitly via `new PlatformClient({ fetch: ... })`.
+- **`PlatformError: unauthorized` on every call** — API key missing or wrong. `client.me.get()` is the cleanest validation.
+- **`PlatformError: rate_limited`** — you hit the per-org rate limit (10/min for `POST /v1/calls`, 60/min for `POST /v1/call-tokens`, 100/min everywhere else). The SDK auto-retries with backoff up to `maxRetries` (default 2); raise it or space out calls if you're doing bulk operations.
+- **`PlatformError: payment_required`** — org ran out of credit. `client.credits.getBalance()` + top up via the dashboard.
+- **File uploads timing out** — `uploadFile` already sets a 5-minute timeout; if you're uploading huge PDFs, override via... well, uploads above a few MB are better split into smaller documents anyway. Let me know if that's a real pinch point and we'll plumb a `timeoutMs` override on the upload method.

package/DEVELOPING.md

@@ -0,0 +1,82 @@
+# Developing `@craftedxp/sdk-node`
+
+Pure JS, zero-dep, runs in Node 18+. Fast iteration — no native compilation, no platform quirks.
+
+## TL;DR
+
+```bash
+cd voice-assistant/sdk/node
+npm install
+npm run dev          # tsup --watch → rebuilds dist/ on save
+```
+
+Point a consumer at the local build:
+
+```bash
+# In the consumer project:
+npm install /abs/path/to/voice-assistant/sdk/node       # file: dep
+# or
+yalc add @craftedxp/sdk-node
+```
+
+After each rebuild the consumer picks up changes on next `require` (server restart or nodemon). For Next.js API routes, the dev server auto-reloads.
+
+## Local testing against the platform
+
+```bash
+# Terminal 1 — run the platform server
+cd voice-assistant/server && npm run dev
+
+# Terminal 2 — run the SDK in watch mode
+cd voice-assistant/sdk/node && npm run dev
+
+# Terminal 3 — a scratch consumer
+cd /tmp && mkdir sdk-smoke && cd sdk-smoke
+npm init -y
+npm install /path/to/voice-assistant/sdk/node
+cat > smoke.mjs <<'EOF'
+import { PlatformClient } from '@craftedxp/sdk-node'
+const client = new PlatformClient({
+  apiKey: process.env.VOICE_AGENT_SK,
+  baseUrl: 'http://localhost:8080',
+})
+console.log(await client.me.get())
+console.log((await client.agents.list()).map(a => ({ id: a.agentId, name: a.name })))
+EOF
+VOICE_AGENT_SK=sk_... node smoke.mjs
+```
+
+## Adding a new resource
+
+Say we add `/v1/phone-numbers` server-side. The SDK pattern:
+
+1. Add types to `src/types.ts` (`PhoneNumber`, `PhoneNumberCreateInput`, etc.)
+2. Create `src/resources/phoneNumbers.ts` following the shape of existing resources (factory taking `HttpClient`, returning `{ create, list, get, delete, ... }`)
+3. Wire it onto `PlatformClient` in `src/PlatformClient.ts`
+4. Re-export the resource type from `src/index.ts`
+5. Add a section to `README.md` under "API surface"
+6. `npm run build` + `npm run typecheck`
+
+Each resource is ~30–80 lines. The HTTP + error handling is centralised in `src/http.ts` — resources never call `fetch` directly.
+
+## Style
+
+- **No top-level state.** Resources are factories keyed on the HTTP client, never module-scoped singletons. Consumers that instantiate multiple clients (e.g. in a test harness spanning multiple orgs) need isolation.
+- **Dates as `number` (ms).** Matches the server's Firestore Timestamp serialisation. Consumers who want Date objects can wrap.
+- **No mutation of inputs.** Every resource method JSON-serialises inputs via `JSON.stringify` — pass whatever you want, we don't touch it.
+- **Errors always `PlatformError`.** Network errors get wrapped with `code: 'unknown'` + `status: 0`, but the class is consistent so `catch (err)` / `instanceof` works across all failures.
+
+## Before releasing
+
+```bash
+npm run build         # emits dist/
+npm run typecheck
+npm pack --dry-run    # verify tarball contents — should be dist/ + docs + package.json
+```
+
+Then bump `version` in `package.json`, commit, tag, publish.
+
+## Related
+
+- [CONSUMING.md](./CONSUMING.md) — external install paths
+- `../web/DEVELOPING.md` + `../react-native/DEVELOPING.md` — sibling SDKs

package/README.md

@@ -0,0 +1,151 @@
+# @craftedxp/sdk-node
+
+Node.js / TypeScript SDK for the voice agent platform. Use it from your **backend** to mint short-lived call tokens, manage agents, query calls, and upload knowledge-base docs.
+
+> Pairs with `@craftedxp/voice-rn` (the React Native client SDK). Your app calls `fetchToken` → your backend uses this SDK → the platform mints a `ct_` token → returned to the app. The `sk_` API key only ever lives on your backend.
+
+Zero runtime dependencies. Node 18+.
+
+## Install
+
+```bash
+npm install @craftedxp/sdk-node
+```
+
+## Quick start — minting a call token
+
+The most common use:
+
+```ts
+import { PlatformClient } from '@craftedxp/sdk-node'
+
+const client = new PlatformClient({
+  apiKey: process.env.VOICE_AGENT_SK!, // never ship this to a client
+  baseUrl: 'https://api.your-server.com', // or http://localhost:8080 for dev
+})
+
+// In your "/voice-token" route handler — called by the RN SDK's fetchToken:
+async function mintForCall({ agentId, userId, context, metadata }) {
+  const { token } = await client.callTokens.mint({
+    agentId,
+    ttlSeconds: 600, // 10 min default; up to 3600 (60 min)
+    contactId: userId, // optional → cross-call memory
+    context, // optional arbitrary JSON, lowered into agent's system prompt
+    metadata, // optional opaque keys round-tripped on call.ended webhook (≤1 KB)
+  })
+  return { token } // hand to the RN SDK
+}
+```
+
+The full call-token surface:
+
+```ts
+client.callTokens.mint({ agentId, ttlSeconds, context, metadata, contactId, vars, allowedOrigins })
+client.callTokens.list({ includeRevoked, includeExpired, limit })
+client.callTokens.revoke(tokenId)
+```
+
+## Other resources
+
+```ts
+client.me.get()                                              // the org behind the sk_
+
+client.agents.create({ name, systemPrompt, ... })            // CRUD on agents
+client.agents.list({ limit, cursor })
+client.agents.get(agentId)
+client.agents.update(agentId, patch)
+client.agents.delete(agentId)
+client.agents.webhooks(agentId).create({ url, secret, events })
+client.agents.webhooks(agentId).list()
+// ...
+
+client.calls.list({ agentId, status, limit, cursor })        // call records
+client.calls.listAll({ agentId })                            // async iterator across pages
+client.calls.get(callId)
+
+client.knowledgeBases.create({ name })                       // KB CRUD + uploads
+client.knowledgeBases.list()
+client.knowledgeBases.uploadFile(kbId, filePath)
+client.knowledgeBases.delete(kbId)
+
+client.credits.getBalance()                                  // billing
+client.credits.getLedger({ limit, cursor })
+
+client.webhooks.deliveries({ agentId, callId, webhookId })   // org-wide delivery log
+```
+
+## Webhook signature verification
+
+```ts
+import express from 'express'
+import { verifyWebhookSignature } from '@craftedxp/sdk-node'
+
+const app = express()
+
+app.post(
+  '/webhooks/voice-agent',
+  // Raw body — we need the exact bytes to recompute the HMAC.
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const sig = req.header('X-Platform-Signature-256') ?? ''
+    if (!verifyWebhookSignature(req.body, sig, process.env.VOICE_AGENT_WEBHOOK_SECRET!)) {
+      return res.status(401).send('invalid signature')
+    }
+    const event = JSON.parse(req.body.toString('utf8'))
+    // ...handle event
+    res.status(200).end()
+  },
+)
+```
+
+The function is timing-safe; copy it into your middleware verbatim. No PlatformClient instance required — `verifyWebhookSignature` is a standalone helper so any framework (Koa, Next.js route handlers, Hono, etc.) can use it.
+
+## Errors
+
+All HTTP errors throw a typed `PlatformError`:
+
+```ts
+import { PlatformError } from '@craftedxp/sdk-node'
+
+try {
+  await client.callTokens.mint({ agentId })
+} catch (err) {
+  if (err instanceof PlatformError) {
+    console.error(err.code, err.status, err.message, err.field, err.docsUrl)
+  }
+  throw err
+}
+```
+
+The HTTP layer auto-retries 429 (honouring `Retry-After`) and 5xx responses with exponential backoff. Default `maxRetries = 2` (3 total attempts); pass `0` to `new PlatformClient({ maxRetries: 0 })` to disable.
+
+## Pagination
+
+Cursor-based. Use the `listAll` async iterator if you want every page without managing the cursor manually:
+
+```ts
+for await (const call of client.calls.listAll({ agentId })) {
+  // process each call across all pages
+}
+```
+
+## What's NOT in this SDK
+
+- Voice / WebSocket / audio streaming. Use `@craftedxp/voice-rn` (React Native) for the call path itself.
+- Browser-side use. This SDK assumes a server-side environment with native `fetch`. The `sk_` API key must never reach a browser.
+- Phone numbers, outbound dialling. Telephony is on the platform roadmap; the SDK will surface it when the server endpoints land.
+
+## Migration from `@voxline/node@0.1.0`
+
+`@voxline/node` was a pre-launch internal name. This package replaces it under the `@craftedxp` org. API surface is unchanged except for the Phase 12 additions (`context` / `metadata` / `contactId` on `callTokens.mint`).
+
+```diff
+- import { PlatformClient } from '@voxline/node'
++ import { PlatformClient } from '@craftedxp/sdk-node'
+
+  const client = new PlatformClient({ apiKey })
+- await client.callTokens.mint({ agentId, vars: { name: 'Arun' } })
++ await client.callTokens.mint({ agentId, context: { name: 'Arun', orders: [/* nested ok */] } })
+```
+
+`vars` is still accepted server-side for backward compatibility.