@firststep-studio/sdk 0.1.0

package/llms.txt

@@ -0,0 +1,597 @@
+# @firststep-studio/sdk
+
+SDK for building protocol handlers that integrate with FirstStep Studio.
+A protocol handler is a standalone HTTP server that receives chat messages from FirstStep Studio and returns responses.
+
+## Quick Start
+
+```bash
+npx create-firststep-app
+cd my-handler
+npm run dev
+```
+
+This scaffolds a working echo bot with streaming, forms, and tunnel support.
+
+## Installation
+
+```bash
+npm install @firststep-studio/sdk
+```
+
+## Architecture
+
+FirstStep Studio sends chat messages to your handler via HTTP. Your handler processes them and returns responses.
+
+```
+User -> FirstStep Studio -> POST /message -> Your Handler -> ProtocolResponse
+                         <- JSON response <-
+```
+
+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
+
+## Endpoints (handled by createServer)
+
+- `GET /health` - always returns 200
+- `POST /handshake` - returns handler capabilities (signature verified)
+- `POST /message` - handles a chat message, returns ProtocolResponse (signature verified)
+- `POST /message/stream` - handles a chat message via SSE stream (signature verified)
+
+## Core Interface: ProtocolHandler
+
+This is the only interface you need to implement.
+
+```typescript
+import { createServer } from '@firststep-studio/sdk/server';
+import type {
+  ProtocolHandler,
+  ProtocolRequest,
+  ProtocolResponse,
+  ProtocolContext,
+  ProtocolCapabilities,
+  ProtocolStreamChunk,
+  HandlerInfo,
+} from '@firststep-studio/sdk';
+
+const handler: ProtocolHandler = {
+  // REQUIRED: handle a chat message
+  async handleMessage(
+    request: ProtocolRequest,
+    context: ProtocolContext
+  ): Promise<ProtocolResponse> {
+    // ...
+  },
+
+  // OPTIONAL: handle streaming responses
+  async *handleStream(
+    request: ProtocolRequest,
+    context: ProtocolContext
+  ): AsyncGenerator<ProtocolStreamChunk> {
+    // ...
+  },
+
+  // REQUIRED: declare capabilities
+  getCapabilities(): ProtocolCapabilities {
+    return {
+      streaming: true,
+      formQuestions: true,
+      knowledgeActions: false,
+      integrations: false,
+    };
+  },
+
+  // OPTIONAL: handler metadata for handshake auto-fill
+  getHandlerInfo(): HandlerInfo {
+    return {
+      name: 'My Handler',
+      description: 'Does something useful.',
+    };
+  },
+};
+```
+
+## ProtocolRequest
+
+Sent by FirstStep Studio to your handler.
+
+```typescript
+interface ProtocolRequest {
+  message?: string;          // User message. If absent, this is session init.
+  sessionId?: string;        // Session ID. New session if absent.
+  deploymentSlug: string;    // Deployment identifier.
+  metadata?: Record<string, unknown>;
+}
+```
+
+When `message` is undefined or empty, the handler should return an initial greeting/welcome message.
+
+## ProtocolResponse
+
+What your handler returns.
+
+```typescript
+interface ProtocolResponse {
+  message: string;                    // REQUIRED: response text
+  sessionId: string;                  // REQUIRED: session ID
+  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
+}
+```
+
+### SessionStatus values
+
+- `'active'` - conversation continues
+- `'completed'` - session is done, no more messages expected
+- `'error'` - something went wrong
+
+## Streaming
+
+If your handler declares `streaming: true` in capabilities and implements `handleStream`, the server exposes `/message/stream` as an SSE endpoint.
+
+Yield chunks one at a time:
+
+```typescript
+async *handleStream(request, context) {
+  // Stream text word by word
+  const words = 'Hello world from streaming'.split(' ');
+  for (const word of words) {
+    yield { type: 'text', content: word + ' ' };
+    await new Promise(r => setTimeout(r, 50));
+  }
+
+  // Optionally yield metadata
+  yield { type: 'metadata', content: { processingTime: 123 } };
+
+  // Optionally yield a form
+  yield { type: 'form', content: { type: 'question', fields: [...] } };
+
+  // Always yield status last
+  yield { type: 'status', content: 'active' };
+}
+```
+
+### ProtocolStreamChunk
+
+```typescript
+interface ProtocolStreamChunk {
+  type: 'text' | 'form' | 'status' | 'error' | 'metadata';
+  content: string | ProtocolForm | SessionStatus | ProtocolError | Record<string, unknown>;
+}
+```
+
+SSE event format sent to the client:
+```
+event: text
+data: {"type":"text","content":"Hello ","sessionId":"abc"}
+
+event: status
+data: {"type":"status","content":"active","sessionId":"abc"}
+
+event: done
+data: {"sessionId":"abc"}
+```
+
+If `handleStream` is not implemented, the server falls back to `handleMessage` and sends the full response as a single SSE burst.
+
+## Forms
+
+Forms let your handler render structured input fields in the FirstStep Studio UI.
+
+```typescript
+interface ProtocolForm {
+  type: 'question' | 'closing' | 'custom';
+  questionId?: string;
+  fields: ProtocolFormField[];
+  metadata?: Record<string, unknown>;
+}
+
+interface ProtocolFormField {
+  id: string;
+  type: 'text' | 'textarea' | 'select' | 'multiselect' | 'date' | 'number' | 'email' | 'phone';
+  label: string;
+  placeholder?: string;
+  options?: ProtocolFormOption[];  // required for select/multiselect
+  required?: boolean;
+  validation?: ProtocolFieldValidation;
+}
+
+interface ProtocolFormOption {
+  value: string;
+  label: string;
+}
+
+interface ProtocolFieldValidation {
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  message?: string;  // custom validation error message
+}
+```
+
+### Form example
+
+```typescript
+return {
+  message: 'Please fill out this form:',
+  sessionId,
+  agentId: 'main',
+  sessionStatus: 'active',
+  form: {
+    type: 'question',
+    questionId: 'contact-info',
+    fields: [
+      {
+        id: 'name',
+        type: 'text',
+        label: 'Your Name',
+        placeholder: 'Enter your name',
+        required: true,
+      },
+      {
+        id: 'email',
+        type: 'email',
+        label: 'Email Address',
+        required: true,
+        validation: {
+          pattern: '^[^@]+@[^@]+\\.[^@]+$',
+          message: 'Please enter a valid email.',
+        },
+      },
+      {
+        id: 'topic',
+        type: 'select',
+        label: 'What is this about?',
+        options: [
+          { value: 'support', label: 'Support' },
+          { value: 'sales', label: 'Sales' },
+          { value: 'feedback', label: 'Feedback' },
+        ],
+        required: true,
+      },
+    ],
+  },
+};
+```
+
+## createServer
+
+Creates a standalone HTTP server. Zero external dependencies (uses Node.js built-in `http` module).
+
+```typescript
+import { createServer } from '@firststep-studio/sdk/server';
+
+const server = createServer(handler, {
+  token: process.env.FIRSTSTEP_TOKEN || '',
+  port: 4001,                          // default: PORT env or 3001
+  host: '0.0.0.0',                     // default: '0.0.0.0'
+  skipSignatureVerification: false,     // set true for local dev without token
+});
+
+server.start();  // returns Promise<void>
+server.stop();   // graceful shutdown, returns Promise<void>
+```
+
+### ServerConfig
+
+```typescript
+interface ServerConfig {
+  token: string;                        // FIRSTSTEP_TOKEN for HMAC verification
+  port?: number;                        // defaults to PORT env or 3001
+  host?: string;                        // defaults to '0.0.0.0'
+  skipSignatureVerification?: boolean;  // for local dev only
+}
+```
+
+### Integrating with Express/Fastify
+
+If you already have an HTTP framework:
+
+```typescript
+const server = createServer(handler, { token: '...' });
+const requestHandler = server.getRequestHandler();
+
+// Express
+app.use('/firststep', requestHandler);
+
+// Fastify
+fastify.all('/firststep/*', (req, reply) => {
+  requestHandler(req.raw, reply.raw);
+});
+```
+
+## Authentication
+
+All requests from FirstStep Studio include an `X-FirstStep-Signature` header containing an HMAC-SHA256 signature of the request body, signed with your API token.
+
+The `createServer` handles verification automatically. If you need manual verification:
+
+```typescript
+import { verifyRequestSignature, createRequestSignature, isValidToken } from '@firststep-studio/sdk';
+
+// Verify incoming request
+const isValid = verifyRequestSignature(token, rawBody, signatureHeader);
+
+// Create a signature (for testing)
+const signature = createRequestSignature(token, JSON.stringify(payload));
+
+// Validate token format (fst_ + 40 hex chars)
+const valid = isValidToken('fst_abc123...');
+```
+
+### Token format
+
+Tokens follow the pattern: `fst_` prefix + 40 hexadecimal characters (total 44 characters).
+
+## ProtocolContext
+
+Passed to your handler methods. Provides access to FirstStep Studio platform features.
+
+When running standalone (via createServer), context methods are no-op stubs. When called from the FirstStep platform, they connect to real services.
+
+```typescript
+interface ProtocolContext {
+  session: SessionContext;        // session state, history, form data
+  knowledge: KnowledgeContext;    // knowledge base queries
+  integrations: IntegrationContext; // third-party integrations
+  analytics: AnalyticsContext;    // event tracking
+  logger: LoggerContext;          // structured logging
+  deployment: DeploymentInfo;     // deployment metadata
+  chatbot?: ChatbotInfo;          // chatbot config (GuidedForm only)
+}
+```
+
+### SessionContext
+
+```typescript
+interface SessionContext {
+  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>;
+}
+```
+
+### KnowledgeContext
+
+```typescript
+interface KnowledgeContext {
+  queryDatabase(knowledgeId: string, query: string): Promise<KnowledgeResult>;
+  searchPages(knowledgeId: string, query: string): Promise<KnowledgeResult>;
+}
+
+interface KnowledgeResult {
+  success: boolean;
+  records?: Record<string, unknown>[];
+  error?: string;
+}
+```
+
+### AnalyticsContext
+
+```typescript
+interface AnalyticsContext {
+  logActionExecuted(type: 'knowledge' | 'helpline' | 'integration', actionId: string, metadata?: Record<string, unknown>): void;
+  logInteraction(event: InteractionEvent): void;
+  logCustomEvent(eventName: string, data?: Record<string, unknown>): void;
+}
+
+type InteractionEventType =
+  | 'helpline_sms_click'
+  | 'helpline_call_click'
+  | 'helpline_website_click'
+  | 'knowledge_link_click'
+  | 'announcement_cta_click'
+  | 'card_click'
+  | 'form_submit'
+  | 'custom';
+```
+
+### LoggerContext
+
+```typescript
+interface LoggerContext {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+  logRouting(decision: RoutingDecision): void;
+  logToolUse(tool: string, params: Record<string, unknown>, result: unknown): void;
+}
+```
+
+## UCP (Universal Classification Protocol)
+
+Optional module for integrating with classifier services.
+
+```typescript
+import { createUCPClient, classifyWithUCP, UCPClient } from '@firststep-studio/sdk';
+
+// One-shot classification
+const result = await classifyWithUCP(
+  'https://api.example.com/ucp/v1/classifiers/abc123',
+  chatMessages,
+  { apiKey: 'optional-key' }
+);
+// result: { classifierId, category, level, confidence, reasoning, raw }
+
+// Reusable client
+const client = createUCPClient('https://api.example.com/ucp/v1/classifiers/abc123');
+const result = await client.classify(ucpMessages);
+const info = await client.getInfo();
+const healthy = await client.healthCheck();
+```
+
+### UCP Types
+
+```typescript
+interface UCPMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: number;  // Unix ms
+  metadata?: Record<string, unknown>;
+}
+
+interface UCPClassifyResponse {
+  category: string;
+  level: string;
+  score: number;       // 0-100
+  rationale: string;
+  metadata?: { executionTime?: number; timestamp?: number };
+  allCategoryResults?: Array<{ category: string; level: string; score: number }>;
+}
+
+interface ClassificationResult {
+  classifierId: string;
+  category: string;
+  level: string;
+  confidence: number;  // 0-1 (normalized from score)
+  reasoning?: string;
+  raw?: UCPClassifyResponse;
+}
+```
+
+## Complete Example: Echo Handler
+
+```typescript
+import { createServer } from '@firststep-studio/sdk/server';
+import type {
+  ProtocolHandler,
+  ProtocolRequest,
+  ProtocolResponse,
+  ProtocolContext,
+  ProtocolCapabilities,
+  ProtocolStreamChunk,
+  HandlerInfo,
+} from '@firststep-studio/sdk';
+
+const handler: ProtocolHandler = {
+  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',
+      };
+    }
+
+    // Echo back
+    return {
+      message: `Echo: ${userMessage}`,
+      sessionId,
+      agentId: 'main',
+      sessionStatus: 'active',
+    };
+  },
+
+  async *handleStream(request, context): AsyncGenerator<ProtocolStreamChunk> {
+    const response = await handler.handleMessage(request, context);
+    const words = response.message.split(' ');
+
+    for (let i = 0; i < words.length; i++) {
+      yield { type: 'text', content: (i === 0 ? '' : ' ') + words[i] };
+      await new Promise(r => setTimeout(r, 30));
+    }
+
+    yield { type: 'status', content: response.sessionStatus };
+  },
+
+  getCapabilities(): ProtocolCapabilities {
+    return {
+      streaming: true,
+      formQuestions: false,
+      knowledgeActions: false,
+      integrations: false,
+    };
+  },
+
+  getHandlerInfo(): HandlerInfo {
+    return { name: 'Echo Handler' };
+  },
+};
+
+const token = process.env.FIRSTSTEP_TOKEN || '';
+const port = parseInt(process.env.PORT || '4001', 10);
+
+const server = createServer(handler, {
+  token,
+  port,
+  skipSignatureVerification: !token,
+});
+
+server.start();
+```
+
+## Environment Variables
+
+- `FIRSTSTEP_TOKEN` - API token (format: `fst_` + 40 hex chars). Required for production. Without it, signature verification is disabled.
+- `PORT` - Server port. Default: 3001.
+
+## Imports Summary
+
+```typescript
+// Server (separate entry point)
+import { createServer } from '@firststep-studio/sdk/server';
+
+// Types (main entry point)
+import type {
+  // Core
+  ProtocolHandler, ProtocolRequest, ProtocolResponse, SessionStatus,
+  ProtocolCapabilities, HandlerInfo,
+
+  // Streaming
+  ProtocolStreamChunk, ProtocolError,
+
+  // Forms
+  ProtocolForm, ProtocolFormField, ProtocolFormOption, ProtocolFieldValidation,
+
+  // Context
+  ProtocolContext, SessionContext, SessionState, ChatMessage,
+  KnowledgeContext, KnowledgeResult,
+  IntegrationContext, IntegrationResult,
+  AnalyticsContext, InteractionEvent, InteractionEventType,
+  LoggerContext, RoutingDecision,
+  DeploymentInfo, ChatbotInfo,
+
+  // Platform data types
+  FormData, FormFieldValue, RoutingLog, SessionMetadata,
+  FormSchema, FormFieldDefinition, FormFieldType,
+  ProtocolRegistration,
+
+  // UCP
+  UCPMessage, UCPClassifyRequest, UCPClassifyResponse,
+  UCPClientConfig, ClassificationResult,
+} from '@firststep-studio/sdk';
+
+// Auth utilities (main entry point)
+import {
+  verifyRequestSignature,
+  createRequestSignature,
+  createAuthHeader,
+  isValidToken,
+} from '@firststep-studio/sdk';
+
+// UCP client (main entry point)
+import {
+  UCPClient, UCPError, createUCPClient, classifyWithUCP,
+} from '@firststep-studio/sdk';
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@firststep-studio/sdk",
+  "version": "0.1.0",
+  "description": "SDK for building protocol handlers that integrate with FirstStep Studio",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "firststep",
+    "protocol",
+    "sdk",
+    "chatbot"
+  ],
+  "author": "FirstStep",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7.0"
+  }
+}