@firststep-studio/sdk 0.12.0 → 0.14.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DYJ44S2E.mjs';
-export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-DYJ44S2E.mjs';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload, c as StorageContext, d as StorageSetOptions, e as SessionContext, f as SessionState, F as FormData, g as FormFieldValue } from './types-D-QFhpnJ.mjs';
+export { Q as AnalyticsContext, J as ChatbotInfo, M as ClassifierConfig, G as DeploymentInfo, X as FormFieldDefinition, Y as FormFieldType, W as FormSchema, s as HandlerInfo, a0 as HandoffContext, k as HandoffInboundContext, a1 as HandoffOptions, B as Helpline, z as HelplineResult, y as HelplineSearchOptions, I as IntegrationContext, x as IntegrationResult, U as InteractionEvent, V as InteractionEventType, w as KnowledgeColumnMetadata, K as KnowledgeContext, v as KnowledgeMetadata, u as KnowledgeResult, L as LoggerContext, r as ProtocolCapabilities, t as ProtocolContext, p as ProtocolError, o as ProtocolFieldValidation, l as ProtocolForm, m as ProtocolFormField, n as ProtocolFormOption, q as ProtocolHandler, Z as ProtocolRegistration, h as ProtocolRequest, i as ProtocolResponse, E as RoutingDecision, N as RoutingLog, _ as SchemaAgent, $ as SchemaQuestion, O as SessionMetadata, j as SessionStatus, T as ThroughlineReference, D as ThroughlineTopicFallback } from './types-D-QFhpnJ.mjs';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -889,6 +889,18 @@ declare class PlatformClient {
         delete: (id: string) => Promise<{
             deletedRecords: number;
         }>;
+        /**
+         * List a sheet's records (newest first). Full-list surfaces (admin
+         * tables, exact name matching) where semantic search is the wrong
+         * tool. `limit` defaults to 500 (server max 2000).
+         */
+        listRecords: (id: string, sheetId: string, options?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            records: PlatformKnowledgeRecord[];
+            total: number;
+        }>;
         /**
          * Append one record to a sheet. Embeds async when ragEnabled.
          */
@@ -1221,4 +1233,51 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+/**
+ * HTTP-backed implementation of StorageContext.
+ * All operations call back to Studio's protocol-resources API.
+ * Data is scoped to the deployment via the JWT token.
+ */
+declare class StorageClient implements StorageContext {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, options?: StorageSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(prefix?: string): Promise<string[]>;
+    merge(key: string, partial: Record<string, unknown>): Promise<void>;
+    append(key: string, item: unknown): Promise<void>;
+    private _post;
+}
+
+/**
+ * HTTP-backed implementation of SessionContext.
+ *
+ * All operations call back to Studio's protocol-resources `/session/*` API,
+ * which is backed by the Redis hot-session store (protocolSession.service).
+ * Session is scoped to the deployment + sessionId encoded in the JWT token, so
+ * the request bodies never carry the session id themselves.
+ *
+ * This is the external-handler counterpart to the in-process SessionContext
+ * the built-in GuidedForm engine gets via handlers/context.ts — same
+ * interface, same Redis backend, reached over HTTP instead of in-process.
+ */
+declare class SessionClient implements SessionContext {
+    sessionId: string;
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string, sessionId: string);
+    getState(): Promise<SessionState>;
+    updateState(updates: Partial<SessionState>): Promise<void>;
+    getHistory(): Promise<ChatMessage[]>;
+    saveMessage(message: ChatMessage): Promise<void>;
+    complete(): Promise<void>;
+    getFormData(): Promise<FormData>;
+    updateFormField(fieldId: string, value: FormFieldValue): Promise<void>;
+    updateFormData(fields: Record<string, FormFieldValue>): Promise<void>;
+    private _post;
+}
+
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, FormData, FormFieldValue, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, SessionClient, SessionContext, SessionState, StorageClient, StorageContext, StorageSetOptions, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DYJ44S2E.js';
-export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-DYJ44S2E.js';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload, c as StorageContext, d as StorageSetOptions, e as SessionContext, f as SessionState, F as FormData, g as FormFieldValue } from './types-D-QFhpnJ.js';
+export { Q as AnalyticsContext, J as ChatbotInfo, M as ClassifierConfig, G as DeploymentInfo, X as FormFieldDefinition, Y as FormFieldType, W as FormSchema, s as HandlerInfo, a0 as HandoffContext, k as HandoffInboundContext, a1 as HandoffOptions, B as Helpline, z as HelplineResult, y as HelplineSearchOptions, I as IntegrationContext, x as IntegrationResult, U as InteractionEvent, V as InteractionEventType, w as KnowledgeColumnMetadata, K as KnowledgeContext, v as KnowledgeMetadata, u as KnowledgeResult, L as LoggerContext, r as ProtocolCapabilities, t as ProtocolContext, p as ProtocolError, o as ProtocolFieldValidation, l as ProtocolForm, m as ProtocolFormField, n as ProtocolFormOption, q as ProtocolHandler, Z as ProtocolRegistration, h as ProtocolRequest, i as ProtocolResponse, E as RoutingDecision, N as RoutingLog, _ as SchemaAgent, $ as SchemaQuestion, O as SessionMetadata, j as SessionStatus, T as ThroughlineReference, D as ThroughlineTopicFallback } from './types-D-QFhpnJ.js';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -889,6 +889,18 @@ declare class PlatformClient {
         delete: (id: string) => Promise<{
             deletedRecords: number;
         }>;
+        /**
+         * List a sheet's records (newest first). Full-list surfaces (admin
+         * tables, exact name matching) where semantic search is the wrong
+         * tool. `limit` defaults to 500 (server max 2000).
+         */
+        listRecords: (id: string, sheetId: string, options?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            records: PlatformKnowledgeRecord[];
+            total: number;
+        }>;
         /**
          * Append one record to a sheet. Embeds async when ragEnabled.
          */
@@ -1221,4 +1233,51 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+/**
+ * HTTP-backed implementation of StorageContext.
+ * All operations call back to Studio's protocol-resources API.
+ * Data is scoped to the deployment via the JWT token.
+ */
+declare class StorageClient implements StorageContext {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, options?: StorageSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(prefix?: string): Promise<string[]>;
+    merge(key: string, partial: Record<string, unknown>): Promise<void>;
+    append(key: string, item: unknown): Promise<void>;
+    private _post;
+}
+
+/**
+ * HTTP-backed implementation of SessionContext.
+ *
+ * All operations call back to Studio's protocol-resources `/session/*` API,
+ * which is backed by the Redis hot-session store (protocolSession.service).
+ * Session is scoped to the deployment + sessionId encoded in the JWT token, so
+ * the request bodies never carry the session id themselves.
+ *
+ * This is the external-handler counterpart to the in-process SessionContext
+ * the built-in GuidedForm engine gets via handlers/context.ts — same
+ * interface, same Redis backend, reached over HTTP instead of in-process.
+ */
+declare class SessionClient implements SessionContext {
+    sessionId: string;
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string, sessionId: string);
+    getState(): Promise<SessionState>;
+    updateState(updates: Partial<SessionState>): Promise<void>;
+    getHistory(): Promise<ChatMessage[]>;
+    saveMessage(message: ChatMessage): Promise<void>;
+    complete(): Promise<void>;
+    getFormData(): Promise<FormData>;
+    updateFormField(fieldId: string, value: FormFieldValue): Promise<void>;
+    updateFormData(fields: Record<string, FormFieldValue>): Promise<void>;
+    private _post;
+}
+
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, FormData, FormFieldValue, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, SessionClient, SessionContext, SessionState, StorageClient, StorageContext, StorageSetOptions, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.js

@@ -25,6 +25,8 @@ __export(index_exports, {
   MARKER_TYPES: () => MARKER_TYPES,
   PlatformClient: () => PlatformClient,
   PlatformError: () => PlatformError,
+  SessionClient: () => SessionClient,
+  StorageClient: () => StorageClient,
   UCPClient: () => UCPClient,
   UCPError: () => UCPError,
   classifyWithUCP: () => classifyWithUCP,
@@ -464,6 +466,20 @@ var PlatformClient = class {
         );
         return { deletedRecords: data.deletedRecords };
       },
+      /**
+       * List a sheet's records (newest first). Full-list surfaces (admin
+       * tables, exact name matching) where semantic search is the wrong
+       * tool. `limit` defaults to 500 (server max 2000).
+       */
+      listRecords: async (id, sheetId, options = {}) => {
+        const params = new URLSearchParams({ sheetId });
+        if (options.limit !== void 0) params.set("limit", String(options.limit));
+        if (options.offset !== void 0) params.set("offset", String(options.offset));
+        return this.request(
+          `/api/protocol/knowledge/${encodeURIComponent(id)}/records?${params}`,
+          "Failed to list records"
+        );
+      },
       /**
        * Append one record to a sheet. Embeds async when ragEnabled.
        */
@@ -854,6 +870,117 @@ var LLMClient = class {
 function createLLMClient(config) {
   return new LLMClient(config);
 }
+
+// src/resources/storageClient.ts
+var StorageClient = class {
+  constructor(baseUrl, token) {
+    this.baseUrl = baseUrl;
+    this.token = token;
+  }
+  async get(key) {
+    const res = await this._post("/storage/get", { key });
+    if (!res.success) return null;
+    return res.value ?? null;
+  }
+  async set(key, value, options) {
+    await this._post("/storage/set", { key, value, ttl: options?.ttl });
+  }
+  async delete(key) {
+    await this._post("/storage/delete", { key });
+  }
+  async has(key) {
+    const res = await this._post("/storage/has", { key });
+    return res.exists === true;
+  }
+  async keys(prefix) {
+    const res = await this._post("/storage/keys", { prefix });
+    return res.keys ?? [];
+  }
+  async merge(key, partial) {
+    await this._post("/storage/merge", { key, partial });
+  }
+  async append(key, item) {
+    await this._post("/storage/append", { key, item });
+  }
+  async _post(path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      console.error(`[StorageClient] ${path} failed: ${res.status} ${text}`);
+      return { success: false, error: `HTTP ${res.status}` };
+    }
+    return res.json();
+  }
+};
+
+// src/resources/sessionClient.ts
+var SessionClient = class {
+  constructor(baseUrl, token, sessionId) {
+    this.baseUrl = baseUrl;
+    this.token = token;
+    this.sessionId = sessionId;
+  }
+  async getState() {
+    const res = await this._post("/session/get-state", {});
+    return reviveState(res.state);
+  }
+  async updateState(updates) {
+    await this._post("/session/update-state", { updates });
+  }
+  async getHistory() {
+    const res = await this._post("/session/get-history", {});
+    return (res.messages ?? []).map(reviveMessage);
+  }
+  async saveMessage(message) {
+    await this._post("/session/save-message", { message });
+  }
+  async complete() {
+    await this._post("/session/complete", {});
+  }
+  async getFormData() {
+    const res = await this._post("/session/get-form-data", {});
+    return res.formData ?? {};
+  }
+  async updateFormField(fieldId, value) {
+    await this._post("/session/update-form-field", { fieldId, value });
+  }
+  async updateFormData(fields) {
+    await this._post("/session/update-form-data", { fields });
+  }
+  async _post(path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      console.error(`[SessionClient] ${path} failed: ${res.status} ${text}`);
+      throw new Error(`SessionClient ${path} failed: HTTP ${res.status}`);
+    }
+    return res.json();
+  }
+};
+function reviveState(state) {
+  if (!state) return state;
+  if (state.createdAt) state.createdAt = new Date(state.createdAt);
+  if (state.updatedAt) state.updatedAt = new Date(state.updatedAt);
+  return state;
+}
+function reviveMessage(msg) {
+  if (msg?.timestamp) msg.timestamp = new Date(msg.timestamp);
+  return msg;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LLMClient,
@@ -861,6 +988,8 @@ function createLLMClient(config) {
   MARKER_TYPES,
   PlatformClient,
   PlatformError,
+  SessionClient,
+  StorageClient,
   UCPClient,
   UCPError,
   classifyWithUCP,