@firststep-studio/sdk 0.1.0 → 0.2.0

package/llms.txt

@@ -11,7 +11,7 @@ cd my-handler
 npm run dev
 ```
 
-This scaffolds a working echo bot with streaming, forms, and tunnel support.
+This scaffolds a working multi-stage handler with Gemini streaming, Dashboard persistence, and rich UI cards.
 
 ## Installation
 
@@ -31,9 +31,11 @@ User -> FirstStep Studio -> POST /message -> Your Handler -> ProtocolResponse
 The SDK provides:
 1. `ProtocolHandler` interface: what you implement
 2. `createServer()`: standalone HTTP server that handles routing, auth, and SSE streaming
-3. Type definitions for all request/response shapes
-4. Auth utilities for HMAC-SHA256 signature verification
-5. UCP client for classifier integration
+3. `streamMetadata`: builder functions for Dashboard persistence (schema, form data, routing, agent transitions)
+4. `renderMarkers`: builder functions for rich UI cards (helplines, resources, providers, emergency alerts)
+5. Type definitions for all request/response shapes
+6. Auth utilities for HMAC-SHA256 signature verification
+7. UCP client for classifier integration
 
 ## Endpoints (handled by createServer)
 
@@ -121,7 +123,7 @@ interface ProtocolResponse {
   agentId: string;                    // REQUIRED: current agent identifier
   sessionStatus: SessionStatus;       // REQUIRED: 'active' | 'completed' | 'error'
   form?: ProtocolForm;                // OPTIONAL: render a form in the UI
-  metadata?: Record<string, unknown>; // OPTIONAL: arbitrary metadata
+  metadata?: Record<string, unknown>; // OPTIONAL: metadata for Dashboard persistence
 }
 ```
 
@@ -131,6 +133,35 @@ interface ProtocolResponse {
 - `'completed'` - session is done, no more messages expected
 - `'error'` - something went wrong
 
+### Non-streaming metadata
+
+When using `handleMessage()` (non-streaming), include Dashboard metadata in the `metadata` field of the response. The Studio proxy reads `metadata.schema`, `metadata.formData`, `metadata.currentAgent`, and `metadata.routing` and persists them.
+
+The recommended pattern is to delegate to `handleStream()` and merge metadata:
+
+```typescript
+async handleMessage(request, context) {
+  const chunks: string[] = [];
+  const mergedMetadata: Record<string, unknown> = {};
+
+  for await (const chunk of this.handleStream!(request, context)) {
+    if (chunk.type === 'text') {
+      chunks.push(typeof chunk.content === 'string' ? chunk.content : '');
+    } else if (chunk.type === 'metadata' && chunk.content) {
+      Object.assign(mergedMetadata, chunk.content);
+    }
+  }
+
+  return {
+    message: chunks.join(''),
+    sessionId: request.sessionId || 'new',
+    agentId: 'main',
+    sessionStatus: 'active',
+    metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : undefined,
+  };
+},
+```
+
 ## Streaming
 
 If your handler declares `streaming: true` in capabilities and implements `handleStream`, the server exposes `/message/stream` as an SSE endpoint.
@@ -180,6 +211,305 @@ data: {"sessionId":"abc"}
 
 If `handleStream` is not implemented, the server falls back to `handleMessage` and sends the full response as a single SSE burst.
 
+## Stream Metadata (Dashboard Persistence)
+
+The `streamMetadata` module provides builder functions that return ready-to-yield `ProtocolStreamChunk` objects. These chunks are intercepted by the Studio proxy and persisted to MongoDB for Dashboard features (Form Insights, Session History, Routing Logs, Agent Transitions).
+
+```typescript
+import { streamMetadata } from '@firststep-studio/sdk';
+```
+
+### declareSchema
+
+Declare your handler's agents and questions. Yield once during session init (welcome). The Studio proxy stores this so the Dashboard can display question-level analytics.
+
+```typescript
+yield streamMetadata.declareSchema({
+  agents: [
+    { id: 'intake',  title: 'Intake',  order: 0 },
+    { id: 'support', title: 'Support', order: 1 },
+    { id: 'closing', title: 'Closing', order: 2 },
+  ],
+  questions: [
+    { id: 'name',    agentId: 'intake',  title: 'Name',    type: 'text' },
+    { id: 'concern', agentId: 'support', title: 'Concern', type: 'text' },
+    { id: 'mood',    agentId: 'support', title: 'Mood',    type: 'choice' },
+  ],
+});
+// Produces: { type: 'metadata', content: { schema: { agents: [...], questions: [...] } } }
+```
+
+#### SchemaAgent
+
+```typescript
+interface SchemaAgent {
+  id: string;       // Agent/stage identifier
+  title: string;    // Display title
+  order?: number;   // Display order (0-based)
+}
+```
+
+#### SchemaQuestion
+
+```typescript
+interface SchemaQuestion {
+  id: string;       // Question/field identifier
+  agentId: string;  // Which agent owns this question
+  title: string;    // Display title
+  type: 'text' | 'choice' | 'rating' | 'date' | 'location' | 'preference';
+  choices?: { id: string; text: string }[];           // For choice type
+  maxRating?: number;                                  // For rating type
+  ratingStyle?: string;                                // For rating type
+  preferenceLabels?: { positive: string; negative: string }; // For preference type
+}
+```
+
+### formDataUpdate
+
+Send collected form field values for Dashboard persistence. Call after each turn when new fields are captured. Values are incrementally merged into the session's form data.
+
+```typescript
+yield streamMetadata.formDataUpdate({
+  name: 'Alice',
+  name_completed_at: Date.now(),
+  name_turn_number: 2,
+});
+// Produces: { type: 'metadata', content: { formData: { name: 'Alice', ... } } }
+```
+
+Convention: alongside each field value, include `{fieldId}_completed_at` (timestamp) and `{fieldId}_turn_number` (turn index) for analytics tracking.
+
+### agentTransition
+
+Signal an agent/stage transition. The Studio proxy records this in routing logs so the Dashboard can show the conversation's agent flow.
+
+```typescript
+yield streamMetadata.agentTransition({ id: 'support', title: 'Support' });
+// Produces: { type: 'metadata', content: { currentAgent: { id: 'support', title: 'Support' } } }
+```
+
+### routingResult
+
+Send a routing/classification result. The Studio proxy records this in routing logs as a classification event with category, level, and confidence score.
+
+```typescript
+yield streamMetadata.routingResult({
+  decision: 'classified',
+  reason: 'User message contains crisis indicators',
+  category: 'crisis',
+  level: 'high',
+  score: 92,
+});
+// Produces: { type: 'metadata', content: { routing: { decision: 'classified', ... } } }
+```
+
+#### RoutingClassificationPayload
+
+```typescript
+interface RoutingClassificationPayload {
+  decision: string;   // e.g., 'classified', 'routed'
+  reason: string;     // Human-readable explanation
+  category: string;   // Classification category
+  level: string;      // Risk/priority level
+  score: number;      // Confidence score (0-100)
+}
+```
+
+## Render Markers (Rich UI Cards)
+
+The `renderMarkers` module provides builder functions that return marker strings. These are yielded as `text` chunks. The Studio frontend parses them from the finalized message and renders rich UI components (carousels, alerts, cards).
+
+```typescript
+import { renderMarkers } from '@firststep-studio/sdk';
+```
+
+Render markers are always yielded as text chunks:
+```typescript
+yield { type: 'text', content: renderMarkers.helplineCard({ ... }) };
+```
+
+The marker format is: `[RENDER_TYPE]{"json":"payload"}[/RENDER_TYPE]`
+
+### helplineCard
+
+Renders a carousel of helpline cards with contact buttons (call, text, chat, WhatsApp).
+
+```typescript
+yield {
+  type: 'text',
+  content: renderMarkers.helplineCard({
+    helplines: [
+      {
+        name: '988 Suicide & Crisis Lifeline',
+        phoneNumber: '988',
+        categories: ['crisis', 'mental health'],
+        status: 'open',
+        statusLabel: 'Available 24/7',
+        website: 'https://988lifeline.org',
+      },
+      {
+        name: 'Crisis Text Line',
+        smsNumber: '741741',
+        categories: ['crisis', 'text support'],
+        status: 'open',
+        statusLabel: 'Text HOME',
+      },
+    ],
+    type: 'throughline', // 'throughline' | 'throughline_fallback' | 'stage'
+  }),
+};
+```
+
+#### HelplineCardItem
+
+```typescript
+interface HelplineCardItem {
+  name: string;
+  description?: string;
+  categories: string[];
+  status: 'open' | 'closed';
+  statusLabel: string;
+  statusBadge?: string;      // e.g., 'Best Match'
+  hoursText?: string;
+  supportTypes?: string;
+  smsNumber?: string;
+  phoneNumber?: string;
+  website?: string;
+  webchat?: string;
+  whatsapp?: string;
+  specialties?: string[];
+  highlightedTag?: string;
+  verified?: boolean;
+}
+```
+
+### emergency
+
+Renders a prominent emergency alert with a large call button.
+
+```typescript
+yield {
+  type: 'text',
+  content: renderMarkers.emergency({
+    number: '911',
+    countryName: 'United States',
+    countryCode: 'US',
+  }),
+};
+```
+
+### resourceCard
+
+Renders a carousel of resource cards with descriptions, tags, and visit buttons.
+
+```typescript
+yield {
+  type: 'text',
+  content: renderMarkers.resourceCard({
+    resources: [
+      {
+        name: 'Mindfulness Exercises',
+        url: 'https://example.com/mindfulness',
+        description: 'Simple breathing and grounding techniques.',
+        tags: ['wellness', 'self-care'],
+        video_url: 'https://example.com/video.mp4', // optional video thumbnail
+      },
+    ],
+  }),
+};
+```
+
+#### ResourceCardItem
+
+```typescript
+interface ResourceCardItem {
+  name: string;
+  url?: string;
+  description?: string;
+  video_url?: string;
+  type?: string;
+  tags?: string[];
+  highlightedTag?: string;
+}
+```
+
+### providerCard
+
+Renders a carousel of provider directory cards with specialty/language tags and contact info.
+
+```typescript
+yield {
+  type: 'text',
+  content: renderMarkers.providerCard({
+    providers: [
+      {
+        id: 'provider-1',
+        name: 'Dr. Smith',
+        type: 'therapist',
+        specialty: ['anxiety', 'depression'],
+        language: ['English', 'Spanish'],
+        description: 'Licensed clinical psychologist.',
+        contact_phone: '+1-555-0100',
+        contact_email: 'dr.smith@example.com',
+        address: '123 Main St, City, ST',
+      },
+    ],
+  }),
+};
+```
+
+### safetyPlan
+
+Renders a multi-section safety plan with expandable sections and save/export actions.
+
+```typescript
+yield {
+  type: 'text',
+  content: renderMarkers.safetyPlan({
+    sections: [
+      {
+        id: 'warning-signs',
+        title: 'Warning Signs',
+        items: ['Feeling overwhelmed', 'Withdrawing from others'],
+      },
+      {
+        id: 'coping-strategies',
+        title: 'Coping Strategies',
+        items: ['Deep breathing', 'Going for a walk'],
+      },
+      {
+        id: 'contacts',
+        title: 'People to Contact',
+        items: [
+          { name: 'Trusted Friend', phone: '555-0101' },
+          { name: '988 Lifeline', phone: '988' },
+        ],
+      },
+    ],
+    actions: { savePng: true, saveTxt: true, copy: true },
+  }),
+};
+```
+
+### reportCard
+
+Renders a summary card of collected report data with a submit button.
+
+```typescript
+yield {
+  type: 'text',
+  content: renderMarkers.reportCard({
+    topic: 'Workplace harassment',
+    location: 'Office Building A',
+    description: 'Detailed description of the incident...',
+    perpetrator_known: true,
+    contact_mode: 'email',
+    contact_value: 'reporter@example.com',
+    submitEndpoint: 'https://api.example.com/reports',
+  }),
+};
+```
+
 ## Forms
 
 Forms let your handler render structured input fields in the FirstStep Studio UI.
@@ -465,10 +795,13 @@ interface ClassificationResult {
 }
 ```
 
-## Complete Example: Echo Handler
+## Complete Example: Multi-Stage Handler
+
+A handler that uses every SDK feature: streaming, Dashboard metadata, rich UI cards, and stage-based conversation flow.
 
 ```typescript
 import { createServer } from '@firststep-studio/sdk/server';
+import { streamMetadata, renderMarkers } from '@firststep-studio/sdk';
 import type {
   ProtocolHandler,
   ProtocolRequest,
@@ -479,63 +812,140 @@ import type {
   HandlerInfo,
 } from '@firststep-studio/sdk';
 
+// In-memory session state (use a database in production)
+const sessions = new Map<string, { stage: string; name?: string; concern?: string }>();
+
 const handler: ProtocolHandler = {
+  // Non-streaming: delegate to handleStream and merge metadata
   async handleMessage(request, context): Promise<ProtocolResponse> {
-    const sessionId = request.sessionId || `session-${Date.now()}`;
-    const userMessage = request.message?.trim();
-
-    // Session init
-    if (!userMessage) {
-      return {
-        message: 'Hello! Send me a message.',
-        sessionId,
-        agentId: 'main',
-        sessionStatus: 'active',
-      };
+    const chunks: string[] = [];
+    const mergedMetadata: Record<string, unknown> = {};
+
+    for await (const chunk of this.handleStream!(request, context)) {
+      if (chunk.type === 'text') {
+        chunks.push(typeof chunk.content === 'string' ? chunk.content : '');
+      } else if (chunk.type === 'metadata' && chunk.content) {
+        Object.assign(mergedMetadata, chunk.content);
+      }
     }
 
-    // Echo back
     return {
-      message: `Echo: ${userMessage}`,
-      sessionId,
+      message: chunks.join(''),
+      sessionId: request.sessionId || 'new',
       agentId: 'main',
       sessionStatus: 'active',
+      metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : undefined,
     };
   },
 
   async *handleStream(request, context): AsyncGenerator<ProtocolStreamChunk> {
-    const response = await handler.handleMessage(request, context);
-    const words = response.message.split(' ');
+    const sessionId = request.sessionId || `session-${Date.now()}`;
 
-    for (let i = 0; i < words.length; i++) {
-      yield { type: 'text', content: (i === 0 ? '' : ' ') + words[i] };
-      await new Promise(r => setTimeout(r, 30));
+    // ── WELCOME (no message = session init) ──
+    if (!request.message) {
+      // 1. Declare schema for Dashboard Form Insights
+      yield streamMetadata.declareSchema({
+        agents: [
+          { id: 'intake',  title: 'Intake',  order: 0 },
+          { id: 'support', title: 'Support', order: 1 },
+        ],
+        questions: [
+          { id: 'name',    agentId: 'intake',  title: 'Name',    type: 'text' },
+          { id: 'concern', agentId: 'support', title: 'Concern', type: 'text' },
+        ],
+      });
+
+      yield { type: 'text', content: 'Welcome! What is your name?' };
+      yield { type: 'status', content: 'active' };
+      return;
+    }
+
+    // ── NORMAL MESSAGE ──
+    const session = sessions.get(sessionId) || { stage: 'intake' };
+
+    if (session.stage === 'intake') {
+      session.name = request.message;
+      session.stage = 'support';
+      sessions.set(sessionId, session);
+
+      // 2. Persist collected field to Dashboard
+      yield streamMetadata.formDataUpdate({
+        name: session.name,
+        name_completed_at: Date.now(),
+        name_turn_number: 1,
+      });
+
+      // 3. Signal agent transition
+      yield streamMetadata.agentTransition({ id: 'support', title: 'Support' });
+
+      yield { type: 'text', content: `Hi ${session.name}! What can I help you with?` };
+    } else {
+      session.concern = request.message;
+      sessions.set(sessionId, session);
+
+      // 4. Persist concern field
+      yield streamMetadata.formDataUpdate({
+        concern: session.concern,
+        concern_completed_at: Date.now(),
+        concern_turn_number: 2,
+      });
+
+      // 5. Send routing classification
+      const isUrgent = /crisis|emergency|hurt/i.test(request.message);
+      yield streamMetadata.routingResult({
+        decision: 'classified',
+        reason: isUrgent ? 'Crisis indicators detected' : 'Standard request',
+        category: isUrgent ? 'crisis' : 'general',
+        level: isUrgent ? 'high' : 'low',
+        score: isUrgent ? 90 : 20,
+      });
+
+      yield { type: 'text', content: 'Thank you for sharing. Here are some resources:' };
+
+      // 6. Emit rich UI cards
+      yield {
+        type: 'text',
+        content: renderMarkers.helplineCard({
+          helplines: [{
+            name: '988 Suicide & Crisis Lifeline',
+            phoneNumber: '988',
+            categories: ['crisis'],
+            status: 'open',
+            statusLabel: 'Available 24/7',
+          }],
+        }),
+      };
+
+      yield {
+        type: 'text',
+        content: renderMarkers.resourceCard({
+          resources: [{
+            name: 'Coping Strategies Guide',
+            url: 'https://example.com/coping',
+            description: 'Evidence-based techniques for managing stress.',
+            tags: ['wellness', 'self-care'],
+          }],
+        }),
+      };
     }
 
-    yield { type: 'status', content: response.sessionStatus };
+    yield { type: 'status', content: 'active' };
   },
 
   getCapabilities(): ProtocolCapabilities {
-    return {
-      streaming: true,
-      formQuestions: false,
-      knowledgeActions: false,
-      integrations: false,
-    };
+    return { streaming: true, formQuestions: false, knowledgeActions: false, integrations: false };
   },
 
   getHandlerInfo(): HandlerInfo {
-    return { name: 'Echo Handler' };
+    return { name: 'My Handler', description: 'Multi-stage support handler.' };
   },
 };
 
-const token = process.env.FIRSTSTEP_TOKEN || '';
-const port = parseInt(process.env.PORT || '4001', 10);
-
+// Start server
 const server = createServer(handler, {
-  token,
-  port,
-  skipSignatureVerification: !token,
+  token: process.env.FIRSTSTEP_TOKEN || '',
+  port: parseInt(process.env.PORT || '4001', 10),
+  skipSignatureVerification: !process.env.FIRSTSTEP_TOKEN,
 });
 
 server.start();
@@ -552,6 +962,9 @@ server.start();
 // Server (separate entry point)
 import { createServer } from '@firststep-studio/sdk/server';
 
+// Builder modules (main entry point)
+import { streamMetadata, renderMarkers, MARKER_TYPES } from '@firststep-studio/sdk';
+
 // Types (main entry point)
 import type {
   // Core
@@ -561,6 +974,18 @@ import type {
   // Streaming
   ProtocolStreamChunk, ProtocolError,
 
+  // Stream Metadata Payloads
+  SchemaDeclarationPayload, SchemaAgent, SchemaQuestion,
+  AgentTransitionPayload, RoutingClassificationPayload,
+
+  // Render Marker Payloads
+  HelplineCardPayload, HelplineCardItem,
+  EmergencyPayload,
+  ResourceCardPayload, ResourceCardItem,
+  ProviderCardPayload, ProviderCardItem,
+  SafetyPlanPayload, SafetyPlanSection,
+  ReportCardPayload, MarkerType,
+
   // Forms
   ProtocolForm, ProtocolFormField, ProtocolFormOption, ProtocolFieldValidation,
 

package/package.json

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