@statewavedev/sdk 0.9.0 → 0.10.0

package/README.md

@@ -12,6 +12,12 @@ Official TypeScript SDK for [Statewave](https://github.com/smaramwbc/statewave)
 
 > ⚠️ **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
@@ -145,6 +151,59 @@ 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
@@ -189,8 +248,13 @@ All response types are fully typed:
 - `ListSubjectsResult` — paginated subject listing
 - `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`
+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;
@@ -47,6 +47,35 @@ export declare class StatewaveClient {
      * 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

@@ -195,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)}`);
     }

package/dist/types.d.ts

@@ -166,6 +166,95 @@ export interface CompileJob {
     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 {
     subjectId: string;
     source: string;
@@ -213,6 +302,53 @@ export interface SetMemoryLabelsParams {
      */
     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;
     apiKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewavedev/sdk",
-  "version": "0.9.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",