@statewavedev/sdk 0.7.0 → 0.8.0

package/README.md

@@ -1,4 +1,4 @@
-# @statewavedev/sdk
+# Statewave TypeScript SDK
 
 [![CI](https://github.com/smaramwbc/statewave-ts/workflows/CI/badge.svg)](https://github.com/smaramwbc/statewave-ts/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@statewavedev/sdk)](https://www.npmjs.com/package/@statewavedev/sdk)
@@ -16,8 +16,6 @@ Official TypeScript SDK for [Statewave](https://github.com/smaramwbc/statewave)
 npm install @statewavedev/sdk
 ```
 
-> Before public launch, this package used the internal name `statewave-ts`. New code should use `@statewavedev/sdk`.
-
 ## Quick start
 
 ```typescript

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;
@@ -30,8 +30,23 @@ export declare class StatewaveClient {
     }): Promise<CompileJob>;
     searchMemories(params: SearchMemoriesParams): Promise<SearchResult>;
     getContext(params: GetContextParams): Promise<ContextBundle>;
+    /**
+     * Replace a memory's sensitivity_labels. 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 `next_cursor`
+     * 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

@@ -108,13 +108,54 @@ export class StatewaveClient {
             subject_id: params.subject_id,
             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.caller_id !== undefined && { caller_id: params.caller_id }),
+            ...(params.caller_type !== undefined && { caller_type: params.caller_type }),
         });
     }
+    // -- Memory labels (#50) ----------------------------------------------
+    /**
+     * Replace a memory's sensitivity_labels. 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 just the assembled context string, ready to inject into a prompt. */
     async getContextString(params) {
         const bundle = await this.getContext(params);
         return bundle.assembled_context;
     }
+    // -- 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 `next_cursor`
+     * to fetch the next page.
+     */
+    async listReceipts(params) {
+        const qs = new URLSearchParams({ subject_id: params.subject_id });
+        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)}`);
     }

package/dist/types.d.ts

@@ -21,6 +21,12 @@ export interface Memory {
     source_episode_ids: string[];
     metadata: Record<string, unknown>;
     status: 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.
+     */
+    sensitivity_labels?: string[];
     created_at: string;
     updated_at: string;
 }
@@ -41,6 +47,83 @@ export interface ContextBundle {
     provenance: Record<string, unknown>;
     assembled_context: string;
     token_estimate: number;
+    /** ULID of the state-assembly receipt, when one was emitted. */
+    receipt_id?: string | null;
+    /** True iff a receipt was successfully written for this call. */
+    receipt_emitted?: 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". */
+    memory_id?: 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";
+    /** Present when type === "episode". */
+    episode_id?: string;
+    source?: string;
+    event_type?: string;
+    occurred_at?: 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[];
+    mode: "log_only" | "enforce";
+}
+export interface ReceiptOutput {
+    context_hash: string;
+    context_size_bytes: number;
+    canonicalization_version: number;
+    token_estimate: 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;
+    mode: "retrieval" | string;
+    query_id: string | null;
+    task_id: string | null;
+    tenant_id: string | null;
+    subject_id: string;
+    task: string;
+    as_of: string;
+    created_at: string;
+    selected_entries: ReceiptSelectedEntry[];
+    policy: ReceiptPolicy;
+    output: ReceiptOutput;
+    region: string | null;
+    receipt_signature: 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;
+}
+export interface ListReceiptsParams {
+    subject_id: string;
+    since?: string;
+    until?: string;
+    cursor?: string;
+    limit?: number;
 }
 export interface Timeline {
     subject_id: string;
@@ -94,6 +177,32 @@ export interface GetContextParams {
     subject_id: string;
     task: string;
     max_tokens?: number;
+    session_id?: 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;
+    /**
+     * 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.
+     */
+    caller_id?: string;
+    caller_type?: string;
+}
+export interface SetMemoryLabelsParams {
+    memory_id: string;
+    /**
+     * Replacement label list. Server normalizes (dedup + lowercase +
+     * trim) and caps at 32 entries. Empty list clears all labels.
+     */
+    sensitivity_labels: string[];
 }
 export interface ClientOptions {
     baseUrl?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statewavedev/sdk",
-  "version": "0.7.0",
-  "description": "Official TypeScript SDK for Statewave — Memory OS for AI agents",
+  "version": "0.8.0",
+  "description": "Official TypeScript SDK for Statewave — the open-source memory runtime for AI agents.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",