@statewavedev/sdk 0.7.1 → 0.9.0

package/README.md

@@ -10,6 +10,8 @@ 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.
+
 ## Install
 
 ```bash
@@ -33,7 +35,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 +48,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 +80,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 +91,60 @@ 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.
+
 ## Error handling
 
 ```typescript
@@ -122,17 +178,19 @@ 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
+- `Receipt` + `ReceiptSelectedEntry` + `ReceiptPolicy` + `ReceiptOutput` — state-assembly audit artifact (v0.8) and its nested shapes
+- `ReceiptList` — cursor-paginated receipt listing
 
-Param types: `CreateEpisodeParams`, `SearchMemoriesParams`, `GetContextParams`
+Param types: `CreateEpisodeParams`, `SearchMemoriesParams`, `GetContextParams`, `ListReceiptsParams`, `SetMemoryLabelsParams`
 
 ## Running tests
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, DeleteResult, Episode, GetContextParams, ListSubjectsResult, SearchMemoriesParams, SearchResult, Timeline } from "./types.js";
+import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, DeleteResult, Episode, GetContextParams, ListReceiptsParams, ListSubjectsResult, Memory, Receipt, ReceiptList, 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>;
@@ -30,8 +30,23 @@ export declare class StatewaveClient {
     }): Promise<CompileJob>;
     searchMemories(params: SearchMemoriesParams): Promise<SearchResult>;
     getContext(params: GetContextParams): Promise<ContextBundle>;
+    /**
+     * 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.
+     */
+    setMemoryLabels(params: SetMemoryLabelsParams): Promise<Memory>;
     /** Return just the assembled context string, ready to inject into a prompt. */
     getContextString(params: GetContextParams): Promise<string>;
+    /** Fetch a single state-assembly receipt by ULID. */
+    getReceipt(receiptId: string): Promise<Receipt>;
+    /**
+     * List state-assembly receipts for a subject, newest first.
+     * Cursor-paginated — pass back the previous response's `nextCursor`
+     * to fetch the next page.
+     */
+    listReceipts(params: ListReceiptsParams): Promise<ReceiptList>;
     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,15 +144,56 @@ 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.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.callerId !== undefined && { callerId: params.callerId }),
+            ...(params.callerType !== undefined && { callerType: params.callerType }),
         });
     }
+    // -- Memory labels (#50) ----------------------------------------------
+    /**
+     * 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.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. */
+    async getReceipt(receiptId) {
+        return this.get(`/v1/receipts/${encodeURIComponent(receiptId)}`);
+    }
+    /**
+     * List state-assembly receipts for a subject, newest first.
+     * Cursor-paginated — pass back the previous response's `nextCursor`
+     * to fetch the next page.
+     */
+    async listReceipts(params) {
+        const qs = new URLSearchParams({ subject_id: params.subjectId });
+        if (params.since !== undefined)
+            qs.set("since", params.since);
+        if (params.until !== undefined)
+            qs.set("until", params.until);
+        if (params.cursor !== undefined)
+            qs.set("cursor", params.cursor);
+        if (params.limit !== undefined)
+            qs.set("limit", String(params.limit));
+        return this.get(`/v1/receipts?${qs}`);
     }
     async getTimeline(subjectId) {
         return this.get(`/v1/timeline?subject_id=${encodeURIComponent(subjectId)}`);
@@ -139,16 +219,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) {
@@ -161,7 +242,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,65 +1,157 @@
-/** 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;
-    created_at: string;
-    updated_at: string;
+    /**
+     * Per-memory capability tags consumed by the sensitivity-label
+     * policy layer (#50). Empty = untagged = policy default-allow.
+     * Older servers without the policy layer omit the field.
+     */
+    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. */
+    receiptId?: string | null;
+    /** True iff a receipt was successfully written for this call. */
+    receiptEmitted?: boolean;
+}
+/**
+ * One entry inside a state-assembly receipt. Strict-superset shape —
+ * fields not relevant to the entry's `type` are null. See
+ * `docs/state-assembly-receipts.md` in the server repository for the
+ * full schema.
+ */
+export interface ReceiptSelectedEntry {
+    type: "memory" | "episode";
+    /** Present when type === "memory". */
+    memoryId?: string;
+    /** Present when type === "memory". */
+    kind?: string;
+    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". */
+    episodeId?: string;
+    source?: string;
+    eventType?: string;
+    occurredAt?: string | null;
+    /** Final position in the assembled bundle. */
+    rank: number;
+    score?: number | null;
+}
+export interface ReceiptPolicy {
+    policyBundleHash: string | null;
+    filtersApplied: unknown[];
+    filtersSkipped: unknown[];
+    mode: "log_only" | "enforce";
+}
+export interface ReceiptOutput {
+    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 {
+    receiptId: string;
+    parentReceiptId: string | null;
+    mode: "retrieval" | string;
+    queryId: string | null;
+    taskId: string | null;
+    tenantId: string | null;
+    subjectId: string;
+    task: string;
+    asOf: string;
+    createdAt: string;
+    selectedEntries: ReceiptSelectedEntry[];
+    policy: ReceiptPolicy;
+    output: ReceiptOutput;
+    region: 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. */
+    nextCursor: string | null;
+}
+export interface ListReceiptsParams {
+    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[];
@@ -67,33 +159,59 @@ 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;
 }
 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;
+    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.
+     */
+    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 SetMemoryLabelsParams {
+    memoryId: string;
+    /**
+     * Replacement label list. Server normalizes (dedup + lowercase +
+     * trim) and caps at 32 entries. Empty list clears all labels.
+     */
+    sensitivityLabels: string[];
 }
 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.7.1",
+  "version": "0.9.0",
   "description": "Official TypeScript SDK for Statewave — the open-source memory runtime for AI agents.",
   "type": "module",
   "main": "dist/index.js",