@firststep-studio/sdk 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @firststep-studio/sdk
+
+SDK for building protocol handlers that integrate with FirstStep Studio.
+
+## Install
+
+```bash
+npm install @firststep-studio/sdk
+```
+
+## Usage
+
+```typescript
+import { createServer } from '@firststep-studio/sdk/server';
+import type { ProtocolHandler } from '@firststep-studio/sdk';
+
+const handler: ProtocolHandler = {
+  async handleMessage(request, context) {
+    return {
+      message: `Echo: ${request.message}`,
+      sessionId: request.sessionId || `session-${Date.now()}`,
+      agentId: 'main',
+      sessionStatus: 'active',
+    };
+  },
+  getCapabilities() {
+    return { streaming: false, formQuestions: false, knowledgeActions: false, integrations: false };
+  },
+};
+
+createServer(handler, {
+  token: process.env.FIRSTSTEP_TOKEN || '',
+  port: 4001,
+  skipSignatureVerification: !process.env.FIRSTSTEP_TOKEN,
+}).start();
+```
+
+## LLM Reference
+
+See `llms.txt` for full API specification.

package/dist/index.d.mts

@@ -0,0 +1,299 @@
+import { C as ChatMessage } from './types-Bm98aHcd.mjs';
+export { A as AnalyticsContext, r as ChatbotInfo, s as ClassifierConfig, D as DeploymentInfo, F as FormData, z as FormFieldDefinition, B as FormFieldType, t as FormFieldValue, y as FormSchema, H as HandlerInfo, q as Helpline, p as HelplineResult, o as HelplineSearchOptions, I as IntegrationContext, n as IntegrationResult, w as InteractionEvent, x as InteractionEventType, K as KnowledgeContext, m as KnowledgeResult, L as LoggerContext, i as ProtocolCapabilities, j as ProtocolContext, g as ProtocolError, e as ProtocolFieldValidation, b as ProtocolForm, c as ProtocolFormField, d as ProtocolFormOption, h as ProtocolHandler, E as ProtocolRegistration, P as ProtocolRequest, a as ProtocolResponse, f as ProtocolStreamChunk, R as RoutingDecision, u as RoutingLog, k as SessionContext, v as SessionMetadata, l as SessionState, S as SessionStatus } from './types-Bm98aHcd.mjs';
+
+/**
+ * UCP (Universal Classification Protocol) Types
+ *
+ * Standard protocol for communicating with classifier services.
+ * Any classifier implementing UCP can be used with FirstStep SDK.
+ */
+/**
+ * UCP Message format for classification
+ */
+interface UCPMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message role */
+    role: 'user' | 'assistant';
+    /** Message content */
+    content: string;
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * UCP Classification Request
+ */
+interface UCPClassifyRequest {
+    /** Messages to classify */
+    messages: UCPMessage[];
+}
+/**
+ * UCP Classification Response
+ */
+interface UCPClassifyResponse {
+    /** Classification category */
+    category: string;
+    /** Classification level */
+    level: string;
+    /** Classification score (0-100) */
+    score: number;
+    /** Rationale for classification */
+    rationale: string;
+    /** Additional metadata */
+    metadata?: {
+        executionTime?: number;
+        timestamp?: number;
+        [key: string]: unknown;
+    };
+    /** All category results (for multi-category classifiers) */
+    allCategoryResults?: Array<{
+        category: string;
+        level: string;
+        score: number;
+    }>;
+}
+/**
+ * UCP Error Response
+ */
+interface UCPErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * UCP Classifier Info Response
+ */
+interface UCPInfoResponse {
+    /** Classifier name */
+    name: string;
+    /** Classifier version */
+    version: string;
+    /** Classifier description */
+    description: string;
+    /** Provider info */
+    provider: {
+        name: string;
+        website?: string;
+        contact?: string;
+    };
+    /** Classifier capabilities */
+    capabilities: {
+        maxConversationTurns: number;
+        averageLatency: number;
+        supportsBatch?: boolean;
+    };
+    /** Pricing info */
+    pricing?: {
+        tier: string;
+        pricePerRequest?: number;
+        currency?: string;
+    };
+}
+/**
+ * UCP Client configuration
+ */
+interface UCPClientConfig {
+    /** Base URL of the UCP endpoint (e.g., "https://api.example.com/ucp/v1") */
+    baseUrl: string;
+    /** Classifier ID */
+    classifierId: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Simplified configuration using just a URL
+ * URL format: {baseUrl}/classifiers/{classifierId}
+ */
+interface UCPEndpointConfig {
+    /** Full endpoint URL */
+    endpoint: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Classification result for SDK consumers
+ * Normalized from UCP response
+ */
+interface ClassificationResult {
+    /** Classifier ID or endpoint */
+    classifierId: string;
+    /** Classification category */
+    category: string;
+    /** Classification level */
+    level: string;
+    /** Classification score (normalized to 0-1) */
+    confidence: number;
+    /** Rationale/reasoning */
+    reasoning?: string;
+    /** Raw UCP response */
+    raw?: UCPClassifyResponse;
+}
+
+/**
+ * UCP (Universal Classification Protocol) Client
+ *
+ * Client for communicating with UCP-compliant classifier endpoints.
+ * Supports both full configuration and simple endpoint URL.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with endpoint URL
+ * const client = UCPClient.fromEndpoint('https://api.example.com/ucp/v1/classifiers/abc123');
+ *
+ * // With API key
+ * const client = UCPClient.fromEndpoint(
+ *   'https://api.example.com/ucp/v1/classifiers/abc123',
+ *   { apiKey: 'your-api-key' }
+ * );
+ *
+ * // Classify messages
+ * const result = await client.classify(messages);
+ * ```
+ */
+
+/**
+ * UCP Client for classifier communication
+ */
+declare class UCPClient {
+    private baseUrl;
+    private classifierId;
+    private apiKey?;
+    private timeout;
+    private headers;
+    constructor(config: UCPClientConfig);
+    /**
+     * Create client from a full endpoint URL
+     *
+     * URL format: {baseUrl}/classifiers/{classifierId}
+     * Example: https://api.example.com/ucp/v1/classifiers/abc123
+     */
+    static fromEndpoint(endpoint: string, options?: {
+        apiKey?: string;
+        timeout?: number;
+    }): UCPClient;
+    /**
+     * Get the classify endpoint URL
+     */
+    get classifyUrl(): string;
+    /**
+     * Get the info endpoint URL
+     */
+    get infoUrl(): string;
+    /**
+     * Classify messages using UCP protocol
+     */
+    classify(messages: UCPMessage[]): Promise<ClassificationResult>;
+    /**
+     * Classify ChatMessage array (convenience method)
+     * Converts ChatMessage to UCPMessage format
+     */
+    classifyChat(messages: ChatMessage[]): Promise<ClassificationResult>;
+    /**
+     * Get classifier info
+     */
+    getInfo(): Promise<UCPInfoResponse>;
+    /**
+     * Check if the classifier endpoint is reachable
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Internal fetch helper with error handling
+     */
+    private fetch;
+}
+/**
+ * UCP-specific error class
+ */
+declare class UCPError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(code: string, message: string, details?: unknown | undefined);
+}
+/**
+ * Create a UCP client from an endpoint URL
+ */
+declare function createUCPClient(endpoint: string, options?: {
+    apiKey?: string;
+    timeout?: number;
+}): UCPClient;
+/**
+ * Classify messages using a UCP endpoint
+ * One-shot function for simple usage
+ */
+declare function classifyWithUCP(endpoint: string, messages: ChatMessage[], options?: {
+    apiKey?: string;
+    timeout?: number;
+}): Promise<ClassificationResult>;
+
+/**
+ * Verify an HMAC-SHA256 request signature.
+ *
+ * The handler server can use this to verify that incoming webhook
+ * requests were signed by the FirstStep platform using the shared token.
+ *
+ * @param token - The API token (FIRSTSTEP_TOKEN)
+ * @param payload - The raw request body string
+ * @param signature - The signature from the X-FirstStep-Signature header
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyRequestSignature } from '@firststep-studio/sdk';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const signature = req.headers['x-firststep-signature'] as string;
+ *   if (!verifyRequestSignature(process.env.FIRSTSTEP_TOKEN!, req.body, signature)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *   // Process the request...
+ * });
+ * ```
+ */
+declare function verifyRequestSignature(token: string, payload: string, signature: string): boolean;
+/**
+ * Create an HMAC-SHA256 signature for a payload.
+ *
+ * Used by the platform to sign outgoing requests to handler servers.
+ *
+ * @param token - The API token
+ * @param payload - The request body string to sign
+ * @returns The hex-encoded HMAC signature
+ */
+declare function createRequestSignature(token: string, payload: string): string;
+/**
+ * Create an Authorization header value for API requests.
+ *
+ * @param token - The API token (fst_xxx)
+ * @returns The header value, e.g. "Bearer fst_xxx"
+ *
+ * @example
+ * ```typescript
+ * import { createAuthHeader } from '@firststep-studio/sdk';
+ *
+ * const response = await fetch('https://api.firststep.ai/api/projects', {
+ *   headers: {
+ *     'Authorization': createAuthHeader(process.env.FIRSTSTEP_TOKEN!),
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthHeader(token: string): string;
+/**
+ * Validate that a token has the correct format (fst_ prefix + 40 hex chars).
+ *
+ * @param token - The token string to validate
+ * @returns true if the token matches the expected format
+ */
+declare function isValidToken(token: string): boolean;
+
+export { ChatMessage, type ClassificationResult, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createRequestSignature, createUCPClient, isValidToken, verifyRequestSignature };

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+import { C as ChatMessage } from './types-Bm98aHcd.js';
+export { A as AnalyticsContext, r as ChatbotInfo, s as ClassifierConfig, D as DeploymentInfo, F as FormData, z as FormFieldDefinition, B as FormFieldType, t as FormFieldValue, y as FormSchema, H as HandlerInfo, q as Helpline, p as HelplineResult, o as HelplineSearchOptions, I as IntegrationContext, n as IntegrationResult, w as InteractionEvent, x as InteractionEventType, K as KnowledgeContext, m as KnowledgeResult, L as LoggerContext, i as ProtocolCapabilities, j as ProtocolContext, g as ProtocolError, e as ProtocolFieldValidation, b as ProtocolForm, c as ProtocolFormField, d as ProtocolFormOption, h as ProtocolHandler, E as ProtocolRegistration, P as ProtocolRequest, a as ProtocolResponse, f as ProtocolStreamChunk, R as RoutingDecision, u as RoutingLog, k as SessionContext, v as SessionMetadata, l as SessionState, S as SessionStatus } from './types-Bm98aHcd.js';
+
+/**
+ * UCP (Universal Classification Protocol) Types
+ *
+ * Standard protocol for communicating with classifier services.
+ * Any classifier implementing UCP can be used with FirstStep SDK.
+ */
+/**
+ * UCP Message format for classification
+ */
+interface UCPMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message role */
+    role: 'user' | 'assistant';
+    /** Message content */
+    content: string;
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * UCP Classification Request
+ */
+interface UCPClassifyRequest {
+    /** Messages to classify */
+    messages: UCPMessage[];
+}
+/**
+ * UCP Classification Response
+ */
+interface UCPClassifyResponse {
+    /** Classification category */
+    category: string;
+    /** Classification level */
+    level: string;
+    /** Classification score (0-100) */
+    score: number;
+    /** Rationale for classification */
+    rationale: string;
+    /** Additional metadata */
+    metadata?: {
+        executionTime?: number;
+        timestamp?: number;
+        [key: string]: unknown;
+    };
+    /** All category results (for multi-category classifiers) */
+    allCategoryResults?: Array<{
+        category: string;
+        level: string;
+        score: number;
+    }>;
+}
+/**
+ * UCP Error Response
+ */
+interface UCPErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * UCP Classifier Info Response
+ */
+interface UCPInfoResponse {
+    /** Classifier name */
+    name: string;
+    /** Classifier version */
+    version: string;
+    /** Classifier description */
+    description: string;
+    /** Provider info */
+    provider: {
+        name: string;
+        website?: string;
+        contact?: string;
+    };
+    /** Classifier capabilities */
+    capabilities: {
+        maxConversationTurns: number;
+        averageLatency: number;
+        supportsBatch?: boolean;
+    };
+    /** Pricing info */
+    pricing?: {
+        tier: string;
+        pricePerRequest?: number;
+        currency?: string;
+    };
+}
+/**
+ * UCP Client configuration
+ */
+interface UCPClientConfig {
+    /** Base URL of the UCP endpoint (e.g., "https://api.example.com/ucp/v1") */
+    baseUrl: string;
+    /** Classifier ID */
+    classifierId: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Simplified configuration using just a URL
+ * URL format: {baseUrl}/classifiers/{classifierId}
+ */
+interface UCPEndpointConfig {
+    /** Full endpoint URL */
+    endpoint: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Classification result for SDK consumers
+ * Normalized from UCP response
+ */
+interface ClassificationResult {
+    /** Classifier ID or endpoint */
+    classifierId: string;
+    /** Classification category */
+    category: string;
+    /** Classification level */
+    level: string;
+    /** Classification score (normalized to 0-1) */
+    confidence: number;
+    /** Rationale/reasoning */
+    reasoning?: string;
+    /** Raw UCP response */
+    raw?: UCPClassifyResponse;
+}
+
+/**
+ * UCP (Universal Classification Protocol) Client
+ *
+ * Client for communicating with UCP-compliant classifier endpoints.
+ * Supports both full configuration and simple endpoint URL.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with endpoint URL
+ * const client = UCPClient.fromEndpoint('https://api.example.com/ucp/v1/classifiers/abc123');
+ *
+ * // With API key
+ * const client = UCPClient.fromEndpoint(
+ *   'https://api.example.com/ucp/v1/classifiers/abc123',
+ *   { apiKey: 'your-api-key' }
+ * );
+ *
+ * // Classify messages
+ * const result = await client.classify(messages);
+ * ```
+ */
+
+/**
+ * UCP Client for classifier communication
+ */
+declare class UCPClient {
+    private baseUrl;
+    private classifierId;
+    private apiKey?;
+    private timeout;
+    private headers;
+    constructor(config: UCPClientConfig);
+    /**
+     * Create client from a full endpoint URL
+     *
+     * URL format: {baseUrl}/classifiers/{classifierId}
+     * Example: https://api.example.com/ucp/v1/classifiers/abc123
+     */
+    static fromEndpoint(endpoint: string, options?: {
+        apiKey?: string;
+        timeout?: number;
+    }): UCPClient;
+    /**
+     * Get the classify endpoint URL
+     */
+    get classifyUrl(): string;
+    /**
+     * Get the info endpoint URL
+     */
+    get infoUrl(): string;
+    /**
+     * Classify messages using UCP protocol
+     */
+    classify(messages: UCPMessage[]): Promise<ClassificationResult>;
+    /**
+     * Classify ChatMessage array (convenience method)
+     * Converts ChatMessage to UCPMessage format
+     */
+    classifyChat(messages: ChatMessage[]): Promise<ClassificationResult>;
+    /**
+     * Get classifier info
+     */
+    getInfo(): Promise<UCPInfoResponse>;
+    /**
+     * Check if the classifier endpoint is reachable
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Internal fetch helper with error handling
+     */
+    private fetch;
+}
+/**
+ * UCP-specific error class
+ */
+declare class UCPError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(code: string, message: string, details?: unknown | undefined);
+}
+/**
+ * Create a UCP client from an endpoint URL
+ */
+declare function createUCPClient(endpoint: string, options?: {
+    apiKey?: string;
+    timeout?: number;
+}): UCPClient;
+/**
+ * Classify messages using a UCP endpoint
+ * One-shot function for simple usage
+ */
+declare function classifyWithUCP(endpoint: string, messages: ChatMessage[], options?: {
+    apiKey?: string;
+    timeout?: number;
+}): Promise<ClassificationResult>;
+
+/**
+ * Verify an HMAC-SHA256 request signature.
+ *
+ * The handler server can use this to verify that incoming webhook
+ * requests were signed by the FirstStep platform using the shared token.
+ *
+ * @param token - The API token (FIRSTSTEP_TOKEN)
+ * @param payload - The raw request body string
+ * @param signature - The signature from the X-FirstStep-Signature header
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyRequestSignature } from '@firststep-studio/sdk';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const signature = req.headers['x-firststep-signature'] as string;
+ *   if (!verifyRequestSignature(process.env.FIRSTSTEP_TOKEN!, req.body, signature)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *   // Process the request...
+ * });
+ * ```
+ */
+declare function verifyRequestSignature(token: string, payload: string, signature: string): boolean;
+/**
+ * Create an HMAC-SHA256 signature for a payload.
+ *
+ * Used by the platform to sign outgoing requests to handler servers.
+ *
+ * @param token - The API token
+ * @param payload - The request body string to sign
+ * @returns The hex-encoded HMAC signature
+ */
+declare function createRequestSignature(token: string, payload: string): string;
+/**
+ * Create an Authorization header value for API requests.
+ *
+ * @param token - The API token (fst_xxx)
+ * @returns The header value, e.g. "Bearer fst_xxx"
+ *
+ * @example
+ * ```typescript
+ * import { createAuthHeader } from '@firststep-studio/sdk';
+ *
+ * const response = await fetch('https://api.firststep.ai/api/projects', {
+ *   headers: {
+ *     'Authorization': createAuthHeader(process.env.FIRSTSTEP_TOKEN!),
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthHeader(token: string): string;
+/**
+ * Validate that a token has the correct format (fst_ prefix + 40 hex chars).
+ *
+ * @param token - The token string to validate
+ * @returns true if the token matches the expected format
+ */
+declare function isValidToken(token: string): boolean;
+
+export { ChatMessage, type ClassificationResult, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createRequestSignature, createUCPClient, isValidToken, verifyRequestSignature };