@firststep-studio/sdk 0.5.0 → 0.7.0

package/dist/{types-fhi9K2il.d.mts → types-DCrYoOfK.d.mts}

@@ -154,6 +154,8 @@ interface ProtocolContext {
     knowledge: KnowledgeContext;
     /** Integration access */
     integrations: IntegrationContext;
+    /** Handler document store (backed by Studio MongoDB) */
+    storage?: StorageContext;
     /** Analytics tracking */
     analytics: AnalyticsContext;
     /** Logging */
@@ -313,9 +315,28 @@ interface SchemaQuestion {
         negative: string;
     };
 }
+/**
+ * Optional context about the chatbot for persona generation and testing.
+ * Handlers can provide as much or as little as they have available.
+ */
+interface SchemaBrief {
+    /** What the chatbot does */
+    description?: string;
+    /** Target audience description (e.g. "Teens and young adults aged 13-25") */
+    audience?: string;
+    /** Chatbot goals/objectives */
+    goals?: string[];
+    /** Stage/agent objectives for richer persona context */
+    stageDescriptions?: Array<{
+        id: string;
+        objective: string;
+    }>;
+}
 interface SchemaDeclarationPayload {
     agents: SchemaAgent[];
     questions: SchemaQuestion[];
+    /** Optional context for virtual persona testing and simulation */
+    brief?: SchemaBrief;
 }
 /**
  * Agent transition payload - sent when the conversation moves to a new stage.
@@ -379,6 +400,38 @@ interface Helpline {
     website?: string;
     description?: string;
 }
+/**
+ * Handler document store backed by Studio MongoDB.
+ * Opaque to Studio: stores data but never reads or interprets it.
+ * Key naming, data structure, and lifecycle are the handler's responsibility.
+ * All operations are scoped to the deployment (isolated by JWT token).
+ */
+interface StorageContext {
+    /** Get a value by key. Returns null if not found. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Set a value by key. Overwrites if exists. */
+    set(key: string, value: unknown, options?: StorageSetOptions): Promise<void>;
+    /** Delete a key. */
+    delete(key: string): Promise<void>;
+    /** Check if key exists. */
+    has(key: string): Promise<boolean>;
+    /** List keys matching a prefix. Returns all keys if no prefix given. */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Shallow merge a partial object into an existing value.
+     * Creates the key if it doesn't exist.
+     */
+    merge(key: string, partial: Record<string, unknown>): Promise<void>;
+    /**
+     * Append an item to an array stored at key.
+     * Creates the array if the key doesn't exist.
+     */
+    append(key: string, item: unknown): Promise<void>;
+}
+interface StorageSetOptions {
+    /** TTL in seconds. Key auto-deletes after expiry. */
+    ttl?: number;
+}
 interface LoggerContext {
     debug(message: string, data?: Record<string, unknown>): void;
     info(message: string, data?: Record<string, unknown>): void;
@@ -598,4 +651,4 @@ interface HandoffInboundContext {
     returnResult?: HandoffReturnPayload;
 }
 
-export type { AgentTransitionPayload as A, RoutingLog as B, ChatMessage as C, DeploymentInfo as D, SessionMetadata as E, FormData as F, AnalyticsContext as G, HandoffRequestPayload as H, IntegrationContext as I, InteractionEvent as J, KnowledgeContext as K, LoggerContext as L, InteractionEventType as M, FormSchema as N, FormFieldDefinition as O, ProtocolStreamChunk as P, FormFieldType as Q, RoutingClassificationPayload as R, SchemaDeclarationPayload as S, ProtocolRegistration as T, SchemaAgent as U, SchemaQuestion as V, HandoffContext as W, HandoffOptions as X, HandoffReturnPayload as a, HandoffOfferPayload as b, ProtocolRequest as c, ProtocolResponse as d, SessionStatus as e, HandoffInboundContext as f, ProtocolForm as g, ProtocolFormField as h, ProtocolFormOption as i, ProtocolFieldValidation as j, ProtocolError as k, ProtocolHandler as l, ProtocolCapabilities as m, HandlerInfo as n, ProtocolContext as o, SessionContext as p, SessionState as q, KnowledgeResult as r, IntegrationResult as s, HelplineSearchOptions as t, HelplineResult as u, Helpline as v, RoutingDecision as w, ChatbotInfo as x, ClassifierConfig as y, FormFieldValue as z };
+export type { AgentTransitionPayload as A, ClassifierConfig as B, ChatMessage as C, DeploymentInfo as D, FormFieldValue as E, FormData as F, RoutingLog as G, HandoffRequestPayload as H, IntegrationContext as I, SessionMetadata as J, KnowledgeContext as K, LoggerContext as L, AnalyticsContext as M, InteractionEvent as N, InteractionEventType as O, ProtocolStreamChunk as P, FormSchema as Q, RoutingClassificationPayload as R, SchemaDeclarationPayload as S, FormFieldDefinition as T, FormFieldType as U, ProtocolRegistration as V, SchemaAgent as W, SchemaQuestion as X, HandoffContext as Y, HandoffOptions as Z, HandoffReturnPayload as a, HandoffOfferPayload as b, ProtocolRequest as c, ProtocolResponse as d, SessionStatus as e, HandoffInboundContext as f, ProtocolForm as g, ProtocolFormField as h, ProtocolFormOption as i, ProtocolFieldValidation as j, ProtocolError as k, ProtocolHandler as l, ProtocolCapabilities as m, HandlerInfo as n, ProtocolContext as o, SessionContext as p, SessionState as q, KnowledgeResult as r, IntegrationResult as s, HelplineSearchOptions as t, HelplineResult as u, Helpline as v, StorageContext as w, StorageSetOptions as x, RoutingDecision as y, ChatbotInfo as z };

package/dist/{types-fhi9K2il.d.ts → types-DCrYoOfK.d.ts}

@@ -154,6 +154,8 @@ interface ProtocolContext {
     knowledge: KnowledgeContext;
     /** Integration access */
     integrations: IntegrationContext;
+    /** Handler document store (backed by Studio MongoDB) */
+    storage?: StorageContext;
     /** Analytics tracking */
     analytics: AnalyticsContext;
     /** Logging */
@@ -313,9 +315,28 @@ interface SchemaQuestion {
         negative: string;
     };
 }
+/**
+ * Optional context about the chatbot for persona generation and testing.
+ * Handlers can provide as much or as little as they have available.
+ */
+interface SchemaBrief {
+    /** What the chatbot does */
+    description?: string;
+    /** Target audience description (e.g. "Teens and young adults aged 13-25") */
+    audience?: string;
+    /** Chatbot goals/objectives */
+    goals?: string[];
+    /** Stage/agent objectives for richer persona context */
+    stageDescriptions?: Array<{
+        id: string;
+        objective: string;
+    }>;
+}
 interface SchemaDeclarationPayload {
     agents: SchemaAgent[];
     questions: SchemaQuestion[];
+    /** Optional context for virtual persona testing and simulation */
+    brief?: SchemaBrief;
 }
 /**
  * Agent transition payload - sent when the conversation moves to a new stage.
@@ -379,6 +400,38 @@ interface Helpline {
     website?: string;
     description?: string;
 }
+/**
+ * Handler document store backed by Studio MongoDB.
+ * Opaque to Studio: stores data but never reads or interprets it.
+ * Key naming, data structure, and lifecycle are the handler's responsibility.
+ * All operations are scoped to the deployment (isolated by JWT token).
+ */
+interface StorageContext {
+    /** Get a value by key. Returns null if not found. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Set a value by key. Overwrites if exists. */
+    set(key: string, value: unknown, options?: StorageSetOptions): Promise<void>;
+    /** Delete a key. */
+    delete(key: string): Promise<void>;
+    /** Check if key exists. */
+    has(key: string): Promise<boolean>;
+    /** List keys matching a prefix. Returns all keys if no prefix given. */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Shallow merge a partial object into an existing value.
+     * Creates the key if it doesn't exist.
+     */
+    merge(key: string, partial: Record<string, unknown>): Promise<void>;
+    /**
+     * Append an item to an array stored at key.
+     * Creates the array if the key doesn't exist.
+     */
+    append(key: string, item: unknown): Promise<void>;
+}
+interface StorageSetOptions {
+    /** TTL in seconds. Key auto-deletes after expiry. */
+    ttl?: number;
+}
 interface LoggerContext {
     debug(message: string, data?: Record<string, unknown>): void;
     info(message: string, data?: Record<string, unknown>): void;
@@ -598,4 +651,4 @@ interface HandoffInboundContext {
     returnResult?: HandoffReturnPayload;
 }
 
-export type { AgentTransitionPayload as A, RoutingLog as B, ChatMessage as C, DeploymentInfo as D, SessionMetadata as E, FormData as F, AnalyticsContext as G, HandoffRequestPayload as H, IntegrationContext as I, InteractionEvent as J, KnowledgeContext as K, LoggerContext as L, InteractionEventType as M, FormSchema as N, FormFieldDefinition as O, ProtocolStreamChunk as P, FormFieldType as Q, RoutingClassificationPayload as R, SchemaDeclarationPayload as S, ProtocolRegistration as T, SchemaAgent as U, SchemaQuestion as V, HandoffContext as W, HandoffOptions as X, HandoffReturnPayload as a, HandoffOfferPayload as b, ProtocolRequest as c, ProtocolResponse as d, SessionStatus as e, HandoffInboundContext as f, ProtocolForm as g, ProtocolFormField as h, ProtocolFormOption as i, ProtocolFieldValidation as j, ProtocolError as k, ProtocolHandler as l, ProtocolCapabilities as m, HandlerInfo as n, ProtocolContext as o, SessionContext as p, SessionState as q, KnowledgeResult as r, IntegrationResult as s, HelplineSearchOptions as t, HelplineResult as u, Helpline as v, RoutingDecision as w, ChatbotInfo as x, ClassifierConfig as y, FormFieldValue as z };
+export type { AgentTransitionPayload as A, ClassifierConfig as B, ChatMessage as C, DeploymentInfo as D, FormFieldValue as E, FormData as F, RoutingLog as G, HandoffRequestPayload as H, IntegrationContext as I, SessionMetadata as J, KnowledgeContext as K, LoggerContext as L, AnalyticsContext as M, InteractionEvent as N, InteractionEventType as O, ProtocolStreamChunk as P, FormSchema as Q, RoutingClassificationPayload as R, SchemaDeclarationPayload as S, FormFieldDefinition as T, FormFieldType as U, ProtocolRegistration as V, SchemaAgent as W, SchemaQuestion as X, HandoffContext as Y, HandoffOptions as Z, HandoffReturnPayload as a, HandoffOfferPayload as b, ProtocolRequest as c, ProtocolResponse as d, SessionStatus as e, HandoffInboundContext as f, ProtocolForm as g, ProtocolFormField as h, ProtocolFormOption as i, ProtocolFieldValidation as j, ProtocolError as k, ProtocolHandler as l, ProtocolCapabilities as m, HandlerInfo as n, ProtocolContext as o, SessionContext as p, SessionState as q, KnowledgeResult as r, IntegrationResult as s, HelplineSearchOptions as t, HelplineResult as u, Helpline as v, StorageContext as w, StorageSetOptions as x, RoutingDecision as y, ChatbotInfo as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firststep-studio/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "SDK for building protocol handlers that integrate with FirstStep Studio",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",