@statewavedev/sdk 0.8.0 → 0.10.0

package/README.md

@@ -10,6 +10,14 @@ Official TypeScript SDK for [Statewave](https://github.com/smaramwbc/statewave)
 >
 > 📋 **Issues & feature requests:** [statewave/issues](https://github.com/smaramwbc/statewave/issues) (centralized tracker)
 
+> ⚠️ **v0.9.0 is a breaking change.** The entire SDK surface — request params *and* response fields — is now idiomatic **camelCase** (`subjectId`, `maxTokens`, `createdAt`, `receiptId`, …). The wire protocol is unchanged; the client maps to/from the server's snake_case transparently. `payload`, `metadata`, and `provenance` are passed through verbatim — their inner keys are never rewritten. See [CHANGELOG](CHANGELOG.md#090) for the full rename table and migration steps.
+
+> **New to Statewave?** This SDK is a thin client for a running **Statewave
+> server**. If you don't have one yet, the
+> [Getting Started guide](https://github.com/smaramwbc/statewave-docs/blob/main/getting-started.md)
+> brings one up with Docker Compose in about 5 minutes. Every example below
+> assumes a server reachable at `http://localhost:8100`.
+
 ## Install
 
 ```bash
@@ -33,7 +41,7 @@ const swAuth = new StatewaveClient({
 
 // Record an episode
 await sw.createEpisode({
-  subject_id: "user-42",
+  subjectId: "user-42",
   source: "support-chat",
   type: "conversation",
   payload: {
@@ -46,31 +54,31 @@ await sw.createEpisode({
 
 // Compile memories (idempotent)
 const result = await sw.compileMemories("user-42");
-console.log(`Created ${result.memories_created} memories`);
+console.log(`Created ${result.memoriesCreated} memories`);
 
 // Retrieve ranked, token-bounded context
 const ctx = await sw.getContext({
-  subject_id: "user-42",
+  subjectId: "user-42",
   task: "Help with billing",
-  max_tokens: 300,
+  maxTokens: 300,
 });
-console.log(ctx.assembled_context);
+console.log(ctx.assembledContext);
 
 // Batch ingestion (up to 100)
 await sw.createEpisodesBatch([
-  { subject_id: "user-42", source: "crm", type: "note", payload: { text: "Prefers email" } },
-  { subject_id: "user-42", source: "crm", type: "note", payload: { text: "Enterprise plan" } },
+  { subjectId: "user-42", source: "crm", type: "note", payload: { text: "Prefers email" } },
+  { subjectId: "user-42", source: "crm", type: "note", payload: { text: "Enterprise plan" } },
 ]);
 
 // Search memories
 const facts = await sw.searchMemories({
-  subject_id: "user-42",
+  subjectId: "user-42",
   kind: "profile_fact",
 });
 
 // Semantic search (requires embeddings)
 const results = await sw.searchMemories({
-  subject_id: "user-42",
+  subjectId: "user-42",
   query: "billing",
   semantic: true,
 });
@@ -78,7 +86,7 @@ const results = await sw.searchMemories({
 // List all known subjects
 const subjects = await sw.listSubjects();
 for (const s of subjects.subjects) {
-  console.log(`${s.subject_id}: ${s.episode_count} episodes, ${s.memory_count} memories`);
+  console.log(`${s.subjectId}: ${s.episodeCount} episodes, ${s.memoryCount} memories`);
 }
 
 // Get timeline
@@ -89,6 +97,113 @@ console.log(`${timeline.episodes.length} episodes, ${timeline.memories.length} m
 await sw.deleteSubject("user-42");
 ```
 
+## Governance & audit (v0.8)
+
+The SDK surfaces the [state-assembly receipts](https://github.com/smaramwbc/statewave-docs/blob/main/receipts.md) and [sensitivity-labels / policy](https://github.com/smaramwbc/statewave-docs/blob/main/sensitivity-labels.md) layer added in server v0.8.
+
+```typescript
+import { StatewaveClient } from "@statewavedev/sdk";
+
+const sw = new StatewaveClient({
+  baseUrl: "http://localhost:8100",
+  apiKey: "your-key",
+  tenantId: "acme",
+});
+
+// Per-request opt-in for an immutable audit receipt of the assembly.
+// callerId / callerType feed the sensitivity-label policy engine —
+// when the tenant config sets require_caller_identity=true, missing
+// values 401.
+const bundle = await sw.getContext({
+  subjectId: "user-42",
+  task: "What plan is this customer on?",
+  emitReceipt: true,
+  callerId: "agent-7",
+  callerType: "support_agent",
+});
+
+if (bundle.receiptId) {
+  // Receipts are ULID-addressable, tenant-scoped, append-only.
+  const receipt = await sw.getReceipt(bundle.receiptId);
+  // output.contextHash is a SHA-256 of the bytes delivered to the
+  // agent — recompute from bundle.assembledContext to verify integrity.
+  console.log(receipt.output.contextHash);
+  console.log(`${receipt.selectedEntries.length} entries influenced this bundle`);
+}
+
+// List receipts for a subject, cursor-paginated, newest-first.
+const { receipts, nextCursor } = await sw.listReceipts({
+  subjectId: "user-42",
+  limit: 10,
+});
+for (const r of receipts) {
+  console.log(r.receiptId, r.task);
+}
+
+// Set per-memory sensitivity labels (server normalizes — dedup, lowercase, trim).
+// Memories with labels become subject to any active policy bundle for the tenant.
+const updated = await sw.setMemoryLabels({
+  memoryId: "mem-uuid",
+  sensitivityLabels: ["pii", "financial"],
+});
+console.log(updated.sensitivityLabels); // → ["financial", "pii"]
+```
+
+Receipts and the policy engine cooperate: every assembly call records its policy decisions into `receipt.policy.filtersApplied` (one entry per memory the policy fired on) and `receipt.policy.filtersSkipped` (per-rule summary of what didn't fire). In `log_only` mode (the tenant default) the receipt is the full audit trail without filtering; under `enforce` denied memories are dropped before they reach the assembly and the deny is still recorded. See [`receipts.md`](https://github.com/smaramwbc/statewave-docs/blob/main/receipts.md) and [`sensitivity-labels.md`](https://github.com/smaramwbc/statewave-docs/blob/main/sensitivity-labels.md) for the full schemas and policy YAML format.
+
+## Support-agent endpoints
+
+Statewave's support wedge — customer health scoring, SLA tracking, resolution state, and structured escalation briefs — is exposed through ergonomic SDK methods (server v0.6+).
+
+```typescript
+import { StatewaveClient } from "@statewavedev/sdk";
+
+const sw = new StatewaveClient("http://localhost:8100");
+
+// Customer health score (0–100) with the explainable factors behind it.
+const health = await sw.getHealth("customer:globex");
+console.log(`${health.score}/100 — ${health.state}`);
+for (const f of health.factors) {
+  console.log(`  ${f.signal}: ${f.impact >= 0 ? "+" : ""}${f.impact} (${f.detail})`);
+}
+
+// SLA metrics — first-response / resolution times and breach counts.
+// Thresholds are optional; they default server-side to 5 min / 24 h.
+const sla = await sw.getSLA({
+  subjectId: "customer:globex",
+  firstResponseThresholdMinutes: 10,
+  resolutionThresholdHours: 48,
+});
+console.log(`${sla.resolvedSessions}/${sla.totalSessions} resolved, ${sla.resolutionBreachCount} SLA breaches`);
+
+// Track resolution state for a session (upserts by subject + session).
+await sw.createResolution({
+  subjectId: "customer:globex",
+  sessionId: "ticket-8842",
+  status: "resolved",
+  resolutionSummary: "Issued refund for the duplicate charge",
+});
+
+// List resolutions, optionally filtered by status.
+const openItems = await sw.listResolutions({
+  subjectId: "customer:globex",
+  status: "open",
+});
+
+// Generate a handoff context pack for escalation or shift change.
+// `handoffNotes` is a pre-rendered markdown brief for human or LLM use.
+const handoff = await sw.createHandoff({
+  subjectId: "customer:globex",
+  sessionId: "ticket-8842",
+  reason: "escalation",
+  callerId: "agent-7",
+  callerType: "support_agent",
+});
+console.log(handoff.handoffNotes);
+```
+
+`getHealth`, `getSLA`, `createResolution`, `listResolutions`, and `createHandoff` respect the same auth, tenant-scoping, and retry behaviour as the rest of the client. `createHandoff` shares `getContext`'s caller-identity gate — when the tenant config sets `require_caller_identity: true`, both `callerId` and `callerType` are mandatory.
+
 ## Error handling
 
 ```typescript
@@ -122,17 +237,24 @@ See [Privacy & Data Flow](https://github.com/smaramwbc/statewave-docs/blob/main/
 All response types are fully typed:
 
 - `Episode` — raw interaction record
-- `Memory` — compiled memory with provenance
+- `Memory` — compiled memory with provenance + optional `sensitivityLabels`
 - `CompileResult` — compilation response
 - `SearchResult` — search response
-- `ContextBundle` — assembled context with facts, episodes, provenance
+- `ContextBundle` — assembled context with facts, episodes, provenance, optional `receiptId` / `receiptEmitted`
 - `Timeline` — chronological subject history
 - `DeleteResult` — deletion confirmation
 - `BatchCreateResult` — batch ingestion response
 - `SubjectSummary` — subject with episode/memory counts
 - `ListSubjectsResult` — paginated subject listing
-
-Param types: `CreateEpisodeParams`, `SearchMemoriesParams`, `GetContextParams`
+- `Receipt` + `ReceiptSelectedEntry` + `ReceiptPolicy` + `ReceiptOutput` — state-assembly audit artifact (v0.8) and its nested shapes
+- `ReceiptList` — cursor-paginated receipt listing
+- `Health` + `HealthFactor` — customer health score and its explainable factors
+- `SLASummary` + `SessionSLA` — SLA metrics, aggregate and per-session
+- `Handoff` + `ResolutionSummaryItem` — handoff context pack and its prior-resolution items
+- `Resolution` — resolution tracking record
+- `HealthState` / `ResolutionStatus` — string-literal status unions
+
+Param types: `CreateEpisodeParams`, `SearchMemoriesParams`, `GetContextParams`, `ListReceiptsParams`, `SetMemoryLabelsParams`, `GetSLAParams`, `CreateHandoffParams`, `CreateResolutionParams`, `ListResolutionsParams`
 
 ## Running tests
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, DeleteResult, Episode, GetContextParams, ListReceiptsParams, ListSubjectsResult, Memory, Receipt, ReceiptList, SearchMemoriesParams, SearchResult, SetMemoryLabelsParams, Timeline } from "./types.js";
+import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, CreateHandoffParams, CreateResolutionParams, DeleteResult, Episode, GetContextParams, GetSLAParams, Handoff, Health, ListReceiptsParams, ListResolutionsParams, ListSubjectsResult, Memory, Receipt, ReceiptList, Resolution, SLASummary, SearchMemoriesParams, SearchResult, SetMemoryLabelsParams, Timeline } from "./types.js";
 /** Structured error from the Statewave API. */
 export declare class StatewaveAPIError extends Error {
     readonly statusCode: number;
@@ -19,7 +19,7 @@ export declare class StatewaveClient {
     createEpisode(params: CreateEpisodeParams): Promise<Episode>;
     createEpisodesBatch(episodes: CreateEpisodeParams[]): Promise<BatchCreateResult>;
     compileMemories(subjectId: string): Promise<CompileResult>;
-    /** Submit async compilation — returns immediately with a job_id. */
+    /** Submit async compilation — returns immediately with a jobId. */
     compileMemoriesAsync(subjectId: string): Promise<CompileJob>;
     /** Poll the status of an async compile job. */
     getCompileStatus(jobId: string): Promise<CompileJob>;
@@ -31,7 +31,7 @@ export declare class StatewaveClient {
     searchMemories(params: SearchMemoriesParams): Promise<SearchResult>;
     getContext(params: GetContextParams): Promise<ContextBundle>;
     /**
-     * Replace a memory's sensitivity_labels. Server normalizes
+     * Replace a memory's sensitivityLabels. Server normalizes
      * (dedup + lowercase + trim) and caps at 32 entries. Empty array
      * clears all labels — the memory becomes untagged and any policy
      * rule that depends on a label match falls through to default-allow.
@@ -43,10 +43,39 @@ export declare class StatewaveClient {
     getReceipt(receiptId: string): Promise<Receipt>;
     /**
      * List state-assembly receipts for a subject, newest first.
-     * Cursor-paginated — pass back the previous response's `next_cursor`
+     * Cursor-paginated — pass back the previous response's `nextCursor`
      * to fetch the next page.
      */
     listReceipts(params: ListReceiptsParams): Promise<ReceiptList>;
+    /**
+     * Compute the customer health score (0–100) for a subject, with the
+     * explainable factors that drove it. Backs proactive risk triage.
+     */
+    getHealth(subjectId: string): Promise<Health>;
+    /**
+     * Compute SLA metrics for a subject — first-response and resolution
+     * times plus breach flags, aggregated across the subject's sessions.
+     * Both thresholds fall back to the server defaults (5 minutes /
+     * 24 hours) when omitted.
+     */
+    getSLA(params: GetSLAParams): Promise<SLASummary>;
+    /**
+     * Generate a handoff context pack — a structured escalation brief for
+     * shift change or agent transfer. Same caller-identity gate as
+     * `getContext`: when the tenant sets `require_caller_identity: true`,
+     * both `callerId` and `callerType` are mandatory.
+     */
+    createHandoff(params: CreateHandoffParams): Promise<Handoff>;
+    /**
+     * Create or update a resolution record for a support session.
+     * Upserts by `subjectId` + `sessionId`.
+     */
+    createResolution(params: CreateResolutionParams): Promise<Resolution>;
+    /**
+     * List resolution records for a subject, optionally filtered to a
+     * single status.
+     */
+    listResolutions(params: ListResolutionsParams): Promise<Resolution[]>;
     getTimeline(subjectId: string): Promise<Timeline>;
     deleteSubject(subjectId: string): Promise<DeleteResult>;
     listSubjects(params?: {

package/dist/client.js

@@ -1,3 +1,42 @@
+/**
+ * Free-form bags whose contents are user-owned. Their *inner* keys are
+ * never rewritten in either direction so arbitrary caller data (which
+ * may itself contain snake_case or camelCase keys) round-trips
+ * byte-for-byte. The key names themselves are single words, so they are
+ * unchanged by case conversion regardless.
+ */
+const OPAQUE_KEYS = new Set(["payload", "metadata", "provenance"]);
+function snakeKeyToCamel(key) {
+    return key.replace(/_+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+}
+function camelKeyToSnake(key) {
+    return key.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function mapKeys(value, convert) {
+    if (Array.isArray(value)) {
+        return value.map((v) => mapKeys(v, convert));
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            // Opaque bag: keep the verbatim value, don't recurse into it.
+            out[convert(k)] = OPAQUE_KEYS.has(k) ? v : mapKeys(v, convert);
+        }
+        return out;
+    }
+    return value;
+}
+/** Wire (snake_case) → public SDK shape (camelCase). */
+function fromWire(value) {
+    return mapKeys(value, snakeKeyToCamel);
+}
+/** Public SDK shape (camelCase) → wire (snake_case). */
+function toWire(value) {
+    return mapKeys(value, camelKeyToSnake);
+}
 /** Structured error from the Statewave API. */
 export class StatewaveAPIError extends Error {
     statusCode;
@@ -47,7 +86,7 @@ export class StatewaveClient {
     }
     async createEpisode(params) {
         return this.post("/v1/episodes", {
-            subject_id: params.subject_id,
+            subjectId: params.subjectId,
             source: params.source,
             type: params.type,
             payload: params.payload,
@@ -57,7 +96,7 @@ export class StatewaveClient {
     }
     async createEpisodesBatch(episodes) {
         return this.post("/v1/episodes/batch", { episodes: episodes.map(e => ({
-                subject_id: e.subject_id,
+                subjectId: e.subjectId,
                 source: e.source,
                 type: e.type,
                 payload: e.payload,
@@ -66,11 +105,11 @@ export class StatewaveClient {
             })) });
     }
     async compileMemories(subjectId) {
-        return this.post("/v1/memories/compile", { subject_id: subjectId });
+        return this.post("/v1/memories/compile", { subjectId });
     }
-    /** Submit async compilation — returns immediately with a job_id. */
+    /** Submit async compilation — returns immediately with a jobId. */
     async compileMemoriesAsync(subjectId) {
-        return this.post("/v1/memories/compile", { subject_id: subjectId, async: true });
+        return this.post("/v1/memories/compile", { subjectId, async: true });
     }
     /** Poll the status of an async compile job. */
     async getCompileStatus(jobId) {
@@ -84,15 +123,15 @@ export class StatewaveClient {
         const start = Date.now();
         while (Date.now() - start < timeout) {
             await new Promise(r => setTimeout(r, pollInterval));
-            const status = await this.getCompileStatus(job.job_id);
+            const status = await this.getCompileStatus(job.jobId);
             if (status.status === "completed" || status.status === "failed") {
                 return status;
             }
         }
-        throw new Error(`Compile job ${job.job_id} did not complete within ${timeout}ms`);
+        throw new Error(`Compile job ${job.jobId} did not complete within ${timeout}ms`);
     }
     async searchMemories(params) {
-        const qs = new URLSearchParams({ subject_id: params.subject_id });
+        const qs = new URLSearchParams({ subject_id: params.subjectId });
         if (params.kind)
             qs.set("kind", params.kind);
         if (params.query)
@@ -105,34 +144,34 @@ export class StatewaveClient {
     }
     async getContext(params) {
         return this.post("/v1/context", {
-            subject_id: params.subject_id,
+            subjectId: params.subjectId,
             task: params.task,
-            ...(params.max_tokens !== undefined && { max_tokens: params.max_tokens }),
-            ...(params.session_id !== undefined && { session_id: params.session_id }),
-            ...(params.emit_receipt !== undefined && { emit_receipt: params.emit_receipt }),
-            ...(params.query_id !== undefined && { query_id: params.query_id }),
-            ...(params.task_id !== undefined && { task_id: params.task_id }),
-            ...(params.parent_receipt_id !== undefined && {
-                parent_receipt_id: params.parent_receipt_id,
+            ...(params.maxTokens !== undefined && { maxTokens: params.maxTokens }),
+            ...(params.sessionId !== undefined && { sessionId: params.sessionId }),
+            ...(params.emitReceipt !== undefined && { emitReceipt: params.emitReceipt }),
+            ...(params.queryId !== undefined && { queryId: params.queryId }),
+            ...(params.taskId !== undefined && { taskId: params.taskId }),
+            ...(params.parentReceiptId !== undefined && {
+                parentReceiptId: params.parentReceiptId,
             }),
-            ...(params.caller_id !== undefined && { caller_id: params.caller_id }),
-            ...(params.caller_type !== undefined && { caller_type: params.caller_type }),
+            ...(params.callerId !== undefined && { callerId: params.callerId }),
+            ...(params.callerType !== undefined && { callerType: params.callerType }),
         });
     }
     // -- Memory labels (#50) ----------------------------------------------
     /**
-     * Replace a memory's sensitivity_labels. Server normalizes
+     * Replace a memory's sensitivityLabels. Server normalizes
      * (dedup + lowercase + trim) and caps at 32 entries. Empty array
      * clears all labels — the memory becomes untagged and any policy
      * rule that depends on a label match falls through to default-allow.
      */
     async setMemoryLabels(params) {
-        return this.request("PATCH", `/v1/memories/${encodeURIComponent(params.memory_id)}/labels`, { sensitivity_labels: params.sensitivity_labels });
+        return this.request("PATCH", `/v1/memories/${encodeURIComponent(params.memoryId)}/labels`, { sensitivityLabels: params.sensitivityLabels });
     }
     /** Return just the assembled context string, ready to inject into a prompt. */
     async getContextString(params) {
         const bundle = await this.getContext(params);
-        return bundle.assembled_context;
+        return bundle.assembledContext;
     }
     // -- Receipts --------------------------------------------------------
     /** Fetch a single state-assembly receipt by ULID. */
@@ -141,11 +180,11 @@ export class StatewaveClient {
     }
     /**
      * List state-assembly receipts for a subject, newest first.
-     * Cursor-paginated — pass back the previous response's `next_cursor`
+     * Cursor-paginated — pass back the previous response's `nextCursor`
      * to fetch the next page.
      */
     async listReceipts(params) {
-        const qs = new URLSearchParams({ subject_id: params.subject_id });
+        const qs = new URLSearchParams({ subject_id: params.subjectId });
         if (params.since !== undefined)
             qs.set("since", params.since);
         if (params.until !== undefined)
@@ -156,6 +195,78 @@ export class StatewaveClient {
             qs.set("limit", String(params.limit));
         return this.get(`/v1/receipts?${qs}`);
     }
+    // -- Support: health, SLA, handoff, resolutions ----------------------
+    /**
+     * Compute the customer health score (0–100) for a subject, with the
+     * explainable factors that drove it. Backs proactive risk triage.
+     */
+    async getHealth(subjectId) {
+        return this.get(`/v1/subjects/${encodeURIComponent(subjectId)}/health`);
+    }
+    /**
+     * Compute SLA metrics for a subject — first-response and resolution
+     * times plus breach flags, aggregated across the subject's sessions.
+     * Both thresholds fall back to the server defaults (5 minutes /
+     * 24 hours) when omitted.
+     */
+    async getSLA(params) {
+        const qs = new URLSearchParams();
+        if (params.firstResponseThresholdMinutes !== undefined) {
+            qs.set("first_response_threshold_minutes", String(params.firstResponseThresholdMinutes));
+        }
+        if (params.resolutionThresholdHours !== undefined) {
+            qs.set("resolution_threshold_hours", String(params.resolutionThresholdHours));
+        }
+        const query = qs.toString();
+        return this.get(`/v1/subjects/${encodeURIComponent(params.subjectId)}/sla${query ? `?${query}` : ""}`);
+    }
+    /**
+     * Generate a handoff context pack — a structured escalation brief for
+     * shift change or agent transfer. Same caller-identity gate as
+     * `getContext`: when the tenant sets `require_caller_identity: true`,
+     * both `callerId` and `callerType` are mandatory.
+     */
+    async createHandoff(params) {
+        return this.post("/v1/handoff", {
+            subjectId: params.subjectId,
+            sessionId: params.sessionId,
+            ...(params.reason !== undefined && { reason: params.reason }),
+            ...(params.maxTokens !== undefined && { maxTokens: params.maxTokens }),
+            ...(params.emitReceipt !== undefined && { emitReceipt: params.emitReceipt }),
+            ...(params.queryId !== undefined && { queryId: params.queryId }),
+            ...(params.taskId !== undefined && { taskId: params.taskId }),
+            ...(params.parentReceiptId !== undefined && {
+                parentReceiptId: params.parentReceiptId,
+            }),
+            ...(params.callerId !== undefined && { callerId: params.callerId }),
+            ...(params.callerType !== undefined && { callerType: params.callerType }),
+        });
+    }
+    /**
+     * Create or update a resolution record for a support session.
+     * Upserts by `subjectId` + `sessionId`.
+     */
+    async createResolution(params) {
+        return this.post("/v1/resolutions", {
+            subjectId: params.subjectId,
+            sessionId: params.sessionId,
+            ...(params.status !== undefined && { status: params.status }),
+            ...(params.resolutionSummary !== undefined && {
+                resolutionSummary: params.resolutionSummary,
+            }),
+            ...(params.metadata !== undefined && { metadata: params.metadata }),
+        });
+    }
+    /**
+     * List resolution records for a subject, optionally filtered to a
+     * single status.
+     */
+    async listResolutions(params) {
+        const qs = new URLSearchParams({ subject_id: params.subjectId });
+        if (params.status !== undefined)
+            qs.set("status", params.status);
+        return this.get(`/v1/resolutions?${qs}`);
+    }
     async getTimeline(subjectId) {
         return this.get(`/v1/timeline?subject_id=${encodeURIComponent(subjectId)}`);
     }
@@ -180,16 +291,17 @@ export class StatewaveClient {
     }
     async request(method, path, body) {
         let lastError;
+        const wireBody = body === undefined ? undefined : toWire(body);
         for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
             let resp;
             try {
                 const headers = { ...this.defaultHeaders };
-                if (body)
+                if (wireBody !== undefined)
                     headers["Content-Type"] = "application/json";
                 resp = await fetch(`${this.baseUrl}${path}`, {
                     method,
                     headers,
-                    body: body ? JSON.stringify(body) : undefined,
+                    body: wireBody !== undefined ? JSON.stringify(wireBody) : undefined,
                 });
             }
             catch (err) {
@@ -202,7 +314,7 @@ export class StatewaveClient {
                 throw new StatewaveConnectionError(lastError.message);
             }
             if (resp.ok) {
-                return resp.json();
+                return fromWire(await resp.json());
             }
             // Check if retryable status
             if (this.retryConfig.retryOnStatus.includes(resp.status) && attempt < this.retryConfig.maxRetries) {

package/dist/types.d.ts

@@ -1,24 +1,33 @@
-/** Statewave API types — mirrors the backend contract. */
+/**
+ * Statewave API types.
+ *
+ * The public SDK surface is camelCase, idiomatic TypeScript. The
+ * Statewave HTTP API speaks snake_case on the wire; `StatewaveClient`
+ * transparently maps between the two in both directions, so callers
+ * never see a snake_case key. The free-form `payload`, `metadata`, and
+ * `provenance` bags are passed through verbatim — their inner keys are
+ * never rewritten, so arbitrary user data round-trips losslessly.
+ */
 export interface Episode {
     id: string;
-    subject_id: string;
+    subjectId: string;
     source: string;
     type: string;
     payload: Record<string, unknown>;
     metadata: Record<string, unknown>;
     provenance: Record<string, unknown>;
-    created_at: string;
+    createdAt: string;
 }
 export interface Memory {
     id: string;
-    subject_id: string;
+    subjectId: string;
     kind: string;
     content: string;
     summary: string;
     confidence: number;
-    valid_from: string;
-    valid_to: string | null;
-    source_episode_ids: string[];
+    validFrom: string;
+    validTo: string | null;
+    sourceEpisodeIds: string[];
     metadata: Record<string, unknown>;
     status: string;
     /**
@@ -26,31 +35,31 @@ export interface Memory {
      * policy layer (#50). Empty = untagged = policy default-allow.
      * Older servers without the policy layer omit the field.
      */
-    sensitivity_labels?: string[];
-    created_at: string;
-    updated_at: string;
+    sensitivityLabels?: string[];
+    createdAt: string;
+    updatedAt: string;
 }
 export interface CompileResult {
-    subject_id: string;
-    memories_created: number;
+    subjectId: string;
+    memoriesCreated: number;
     memories: Memory[];
 }
 export interface SearchResult {
     memories: Memory[];
 }
 export interface ContextBundle {
-    subject_id: string;
+    subjectId: string;
     task: string;
     facts: Memory[];
     episodes: Episode[];
     procedures: Memory[];
     provenance: Record<string, unknown>;
-    assembled_context: string;
-    token_estimate: number;
+    assembledContext: string;
+    tokenEstimate: number;
     /** ULID of the state-assembly receipt, when one was emitted. */
-    receipt_id?: string | null;
+    receiptId?: string | null;
     /** True iff a receipt was successfully written for this call. */
-    receipt_emitted?: boolean;
+    receiptEmitted?: boolean;
 }
 /**
  * One entry inside a state-assembly receipt. Strict-superset shape —
@@ -61,88 +70,88 @@ export interface ContextBundle {
 export interface ReceiptSelectedEntry {
     type: "memory" | "episode";
     /** Present when type === "memory". */
-    memory_id?: string;
+    memoryId?: string;
     /** Present when type === "memory". */
     kind?: string;
-    valid_from?: string | null;
-    valid_to?: string | null;
-    supersession_status?: "active" | "superseded" | "tombstoned";
-    source_episode_ids?: string[];
-    provenance_hash?: string;
-    fact_key?: string | null;
-    conflict_status?: "none" | "merged" | "overridden" | "unresolved";
+    validFrom?: string | null;
+    validTo?: string | null;
+    supersessionStatus?: "active" | "superseded" | "tombstoned";
+    sourceEpisodeIds?: string[];
+    provenanceHash?: string;
+    factKey?: string | null;
+    conflictStatus?: "none" | "merged" | "overridden" | "unresolved";
     /** Present when type === "episode". */
-    episode_id?: string;
+    episodeId?: string;
     source?: string;
-    event_type?: string;
-    occurred_at?: string | null;
+    eventType?: string;
+    occurredAt?: string | null;
     /** Final position in the assembled bundle. */
     rank: number;
     score?: number | null;
 }
 export interface ReceiptPolicy {
-    policy_bundle_hash: string | null;
-    filters_applied: unknown[];
-    filters_skipped: unknown[];
+    policyBundleHash: string | null;
+    filtersApplied: unknown[];
+    filtersSkipped: unknown[];
     mode: "log_only" | "enforce";
 }
 export interface ReceiptOutput {
-    context_hash: string;
-    context_size_bytes: number;
-    canonicalization_version: number;
-    token_estimate: number;
+    contextHash: string;
+    contextSizeBytes: number;
+    canonicalizationVersion: number;
+    tokenEstimate: number;
 }
 /**
  * Immutable per-retrieval audit artifact for a single context assembly.
  * See `docs/state-assembly-receipts.md` in the server repository.
  */
 export interface Receipt {
-    receipt_id: string;
-    parent_receipt_id: string | null;
+    receiptId: string;
+    parentReceiptId: string | null;
     mode: "retrieval" | string;
-    query_id: string | null;
-    task_id: string | null;
-    tenant_id: string | null;
-    subject_id: string;
+    queryId: string | null;
+    taskId: string | null;
+    tenantId: string | null;
+    subjectId: string;
     task: string;
-    as_of: string;
-    created_at: string;
-    selected_entries: ReceiptSelectedEntry[];
+    asOf: string;
+    createdAt: string;
+    selectedEntries: ReceiptSelectedEntry[];
     policy: ReceiptPolicy;
     output: ReceiptOutput;
     region: string | null;
-    receipt_signature: string | null;
+    receiptSignature: string | null;
 }
 export interface ReceiptList {
     receipts: Receipt[];
     /** Pass back as the `cursor` param to fetch the next page; null when no more. */
-    next_cursor: string | null;
+    nextCursor: string | null;
 }
 export interface ListReceiptsParams {
-    subject_id: string;
+    subjectId: string;
     since?: string;
     until?: string;
     cursor?: string;
     limit?: number;
 }
 export interface Timeline {
-    subject_id: string;
+    subjectId: string;
     episodes: Episode[];
     memories: Memory[];
 }
 export interface DeleteResult {
-    subject_id: string;
-    episodes_deleted: number;
-    memories_deleted: number;
+    subjectId: string;
+    episodesDeleted: number;
+    memoriesDeleted: number;
 }
 export interface BatchCreateResult {
-    episodes_created: number;
+    episodesCreated: number;
     episodes: Episode[];
 }
 export interface SubjectSummary {
-    subject_id: string;
-    episode_count: number;
-    memory_count: number;
+    subjectId: string;
+    episodeCount: number;
+    memoryCount: number;
 }
 export interface ListSubjectsResult {
     subjects: SubjectSummary[];
@@ -150,59 +159,195 @@ export interface ListSubjectsResult {
 }
 /** Status of an async compile job. */
 export interface CompileJob {
-    job_id: string;
+    jobId: string;
     status: "pending" | "running" | "completed" | "failed";
-    subject_id: string;
-    memories_created?: number;
+    subjectId: string;
+    memoriesCreated?: number;
     memories?: Memory[];
     error?: string;
 }
+/** Support health-state bucket. */
+export type HealthState = "healthy" | "watch" | "at_risk";
+/** Resolution lifecycle status. */
+export type ResolutionStatus = "open" | "resolved" | "unresolved";
+/** One explainable factor behind a customer health score. */
+export interface HealthFactor {
+    /** Stable signal identifier, e.g. `sla_resolution_breaches`. */
+    signal: string;
+    /** Signed score contribution — a negative impact drags the score down. */
+    impact: number;
+    /** Human-readable explanation of the factor. */
+    detail: string;
+}
+/** Customer health score (0–100) with the factors that drove it. */
+export interface Health {
+    subjectId: string;
+    score: number;
+    state: HealthState;
+    factors: HealthFactor[];
+}
+/** SLA metrics for a single support session. */
+export interface SessionSLA {
+    sessionId: string;
+    /** `resolved` | `open`. */
+    status: string;
+    firstMessageAt: string | null;
+    firstResponseAt: string | null;
+    resolvedAt: string | null;
+    firstResponseSeconds: number | null;
+    resolutionSeconds: number | null;
+    openDurationSeconds: number | null;
+    firstResponseBreached: boolean;
+    resolutionBreached: boolean;
+}
+/** Aggregate SLA metrics for a subject across all of its sessions. */
+export interface SLASummary {
+    subjectId: string;
+    totalSessions: number;
+    resolvedSessions: number;
+    openSessions: number;
+    avgFirstResponseSeconds: number | null;
+    avgResolutionSeconds: number | null;
+    firstResponseBreachCount: number;
+    resolutionBreachCount: number;
+    sessions: SessionSLA[];
+}
+/** A prior resolution surfaced inside a handoff brief. */
+export interface ResolutionSummaryItem {
+    sessionId: string;
+    status: string;
+    summary: string | null;
+    resolvedAt: string | null;
+}
+/** Structured escalation brief — the handoff context pack. */
+export interface Handoff {
+    subjectId: string;
+    sessionId: string;
+    reason: string;
+    generatedAt: string;
+    customerSummary: string;
+    activeIssue: string;
+    attemptedSteps: string[];
+    keyFacts: string[];
+    resolutionHistory: ResolutionSummaryItem[];
+    recentContext: string[];
+    healthScore: number | null;
+    healthState: HealthState | null;
+    healthFactors: HealthFactor[];
+    /** Pre-rendered markdown brief, ready for human or LLM consumption. */
+    handoffNotes: string;
+    tokenEstimate: number;
+    provenance: Record<string, unknown>;
+    /** ULID of the state-assembly receipt, when one was emitted. */
+    receiptId?: string | null;
+    /** True iff a receipt was successfully written for this call. */
+    receiptEmitted?: boolean;
+}
+/** Resolution tracking record for a support session. */
+export interface Resolution {
+    id: string;
+    subjectId: string;
+    sessionId: string;
+    status: ResolutionStatus;
+    resolutionSummary: string | null;
+    resolvedAt: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
 export interface CreateEpisodeParams {
-    subject_id: string;
+    subjectId: string;
     source: string;
     type: string;
     payload: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     provenance?: Record<string, unknown>;
-    session_id?: string;
+    sessionId?: string;
 }
 export interface SearchMemoriesParams {
-    subject_id: string;
+    subjectId: string;
     kind?: string;
     query?: string;
     semantic?: boolean;
     limit?: number;
 }
 export interface GetContextParams {
-    subject_id: string;
+    subjectId: string;
     task: string;
-    max_tokens?: number;
-    session_id?: string;
+    maxTokens?: number;
+    sessionId?: string;
     /**
      * Opt in to emitting a state-assembly receipt for this call. The
      * tenant config can also force emission on or off independently of
      * this flag. See `docs/state-assembly-receipts.md` in the server
      * repository.
      */
-    emit_receipt?: boolean;
-    query_id?: string;
-    task_id?: string;
-    parent_receipt_id?: string;
+    emitReceipt?: boolean;
+    queryId?: string;
+    taskId?: string;
+    parentReceiptId?: string;
     /**
      * Caller identity consumed by the sensitivity-label policy layer
      * (#50). When the tenant config sets `require_caller_identity:
-     * true`, both `caller_id` and `caller_type` are mandatory.
+     * true`, both `callerId` and `callerType` are mandatory.
      */
-    caller_id?: string;
-    caller_type?: string;
+    callerId?: string;
+    callerType?: string;
 }
 export interface SetMemoryLabelsParams {
-    memory_id: string;
+    memoryId: string;
     /**
      * Replacement label list. Server normalizes (dedup + lowercase +
      * trim) and caps at 32 entries. Empty list clears all labels.
      */
-    sensitivity_labels: string[];
+    sensitivityLabels: string[];
+}
+export interface GetSLAParams {
+    subjectId: string;
+    /** First-response SLA threshold in minutes (server default: 5). */
+    firstResponseThresholdMinutes?: number;
+    /** Resolution SLA threshold in hours (server default: 24). */
+    resolutionThresholdHours?: number;
+}
+export interface CreateHandoffParams {
+    subjectId: string;
+    /** Session being handed off. */
+    sessionId: string;
+    /** Why the handoff is happening (server default: "escalation"). */
+    reason?: string;
+    /** Token budget for the assembled brief. */
+    maxTokens?: number;
+    /**
+     * Opt in to emitting a state-assembly receipt for this call. The
+     * tenant config can also force emission on or off independently of
+     * this flag.
+     */
+    emitReceipt?: boolean;
+    queryId?: string;
+    taskId?: string;
+    parentReceiptId?: string;
+    /**
+     * Caller identity consumed by the sensitivity-label policy layer
+     * (#50). When the tenant config sets `require_caller_identity: true`,
+     * both `callerId` and `callerType` are mandatory.
+     */
+    callerId?: string;
+    callerType?: string;
+}
+export interface CreateResolutionParams {
+    subjectId: string;
+    sessionId: string;
+    /** Lifecycle status (server default: "open"). */
+    status?: ResolutionStatus;
+    /** Short human summary of how the session was resolved. */
+    resolutionSummary?: string;
+    /** Free-form caller-owned bag; inner keys round-trip verbatim. */
+    metadata?: Record<string, unknown>;
+}
+export interface ListResolutionsParams {
+    subjectId: string;
+    /** Filter to a single status. Omit to list every resolution. */
+    status?: ResolutionStatus;
 }
 export interface ClientOptions {
     baseUrl?: string;

package/dist/types.js

@@ -1,2 +1,11 @@
-/** Statewave API types — mirrors the backend contract. */
+/**
+ * Statewave API types.
+ *
+ * The public SDK surface is camelCase, idiomatic TypeScript. The
+ * Statewave HTTP API speaks snake_case on the wire; `StatewaveClient`
+ * transparently maps between the two in both directions, so callers
+ * never see a snake_case key. The free-form `payload`, `metadata`, and
+ * `provenance` bags are passed through verbatim — their inner keys are
+ * never rewritten, so arbitrary user data round-trips losslessly.
+ */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewavedev/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Official TypeScript SDK for Statewave — the open-source memory runtime for AI agents.",
   "type": "module",
   "main": "dist/index.js",