@firststep-studio/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,238 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UCPClient: () => UCPClient,
+  UCPError: () => UCPError,
+  classifyWithUCP: () => classifyWithUCP,
+  createAuthHeader: () => createAuthHeader,
+  createRequestSignature: () => createRequestSignature,
+  createUCPClient: () => createUCPClient,
+  isValidToken: () => isValidToken,
+  verifyRequestSignature: () => verifyRequestSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ucp/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+var UCPClient = class _UCPClient {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.classifierId = config.classifierId;
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.headers = config.headers ?? {};
+  }
+  /**
+   * Create client from a full endpoint URL
+   *
+   * URL format: {baseUrl}/classifiers/{classifierId}
+   * Example: https://api.example.com/ucp/v1/classifiers/abc123
+   */
+  static fromEndpoint(endpoint, options) {
+    const url = new URL(endpoint);
+    const pathParts = url.pathname.split("/");
+    const classifiersIndex = pathParts.indexOf("classifiers");
+    if (classifiersIndex === -1 || classifiersIndex >= pathParts.length - 1) {
+      throw new Error(
+        `Invalid UCP endpoint URL: ${endpoint}. Expected format: {baseUrl}/classifiers/{classifierId}`
+      );
+    }
+    const classifierId = pathParts[classifiersIndex + 1];
+    const baseUrlPath = pathParts.slice(0, classifiersIndex).join("/");
+    const baseUrl = `${url.protocol}//${url.host}${baseUrlPath}`;
+    return new _UCPClient({
+      baseUrl,
+      classifierId,
+      apiKey: options?.apiKey,
+      timeout: options?.timeout
+    });
+  }
+  /**
+   * Get the classify endpoint URL
+   */
+  get classifyUrl() {
+    return `${this.baseUrl}/classifiers/${this.classifierId}/classify`;
+  }
+  /**
+   * Get the info endpoint URL
+   */
+  get infoUrl() {
+    return `${this.baseUrl}/classifiers/${this.classifierId}/info`;
+  }
+  /**
+   * Classify messages using UCP protocol
+   */
+  async classify(messages) {
+    const request = { messages };
+    const response = await this.fetch(
+      this.classifyUrl,
+      {
+        method: "POST",
+        body: JSON.stringify(request)
+      }
+    );
+    return {
+      classifierId: this.classifierId,
+      category: response.category,
+      level: response.level,
+      confidence: response.score / 100,
+      // Normalize to 0-1
+      reasoning: response.rationale,
+      raw: response
+    };
+  }
+  /**
+   * Classify ChatMessage array (convenience method)
+   * Converts ChatMessage to UCPMessage format
+   */
+  async classifyChat(messages) {
+    const ucpMessages = messages.filter((m) => m.role === "user" || m.role === "assistant").map((m, index) => ({
+      id: `msg-${index}`,
+      role: m.role,
+      content: m.content,
+      timestamp: m.timestamp ? m.timestamp.getTime() : Date.now(),
+      metadata: m.metadata
+    }));
+    return this.classify(ucpMessages);
+  }
+  /**
+   * Get classifier info
+   */
+  async getInfo() {
+    return this.fetch(this.infoUrl, {
+      method: "GET"
+    });
+  }
+  /**
+   * Check if the classifier endpoint is reachable
+   */
+  async healthCheck() {
+    try {
+      const healthUrl = `${this.baseUrl}/health`;
+      const response = await fetch(healthUrl, {
+        method: "GET",
+        signal: AbortSignal.timeout(5e3)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Internal fetch helper with error handling
+   */
+  async fetch(url, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.headers
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const ucpError = errorData;
+        throw new UCPError(
+          ucpError.error?.code || `HTTP_${response.status}`,
+          ucpError.error?.message || `HTTP ${response.status}: ${response.statusText}`,
+          ucpError.error?.details
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof UCPError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new UCPError("TIMEOUT", `Request timed out after ${this.timeout}ms`);
+        }
+        throw new UCPError("NETWORK_ERROR", error.message);
+      }
+      throw new UCPError("UNKNOWN_ERROR", "An unknown error occurred");
+    }
+  }
+};
+var UCPError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "UCPError";
+  }
+};
+function createUCPClient(endpoint, options) {
+  return UCPClient.fromEndpoint(endpoint, options);
+}
+async function classifyWithUCP(endpoint, messages, options) {
+  const client = createUCPClient(endpoint, options);
+  return client.classifyChat(messages);
+}
+
+// src/auth.ts
+var import_crypto = require("crypto");
+var TOKEN_PREFIX = "fst_";
+var TOKEN_LENGTH = 44;
+function verifyRequestSignature(token, payload, signature) {
+  try {
+    const expected = (0, import_crypto.createHmac)("sha256", token).update(payload).digest("hex");
+    const expectedBuffer = Buffer.from(expected, "hex");
+    const signatureBuffer = Buffer.from(signature, "hex");
+    if (expectedBuffer.length !== signatureBuffer.length) {
+      return false;
+    }
+    return (0, import_crypto.timingSafeEqual)(expectedBuffer, signatureBuffer);
+  } catch {
+    return false;
+  }
+}
+function createRequestSignature(token, payload) {
+  return (0, import_crypto.createHmac)("sha256", token).update(payload).digest("hex");
+}
+function createAuthHeader(token) {
+  return `Bearer ${token}`;
+}
+function isValidToken(token) {
+  return typeof token === "string" && token.startsWith(TOKEN_PREFIX) && token.length === TOKEN_LENGTH;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UCPClient,
+  UCPError,
+  classifyWithUCP,
+  createAuthHeader,
+  createRequestSignature,
+  createUCPClient,
+  isValidToken,
+  verifyRequestSignature
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/ucp/client.ts","../src/auth.ts"],"sourcesContent":["/**\n * FirstStep SDK\n *\n * SDK for building protocol handlers that integrate with FirstStep Studio.\n *\n * @example\n * ```typescript\n * import { ProtocolHandler, ProtocolRequest, ProtocolResponse, ProtocolContext } from '@firststep-studio/sdk';\n *\n * class MyHandler implements ProtocolHandler {\n *   async handleMessage(request: ProtocolRequest, context: ProtocolContext): Promise<ProtocolResponse> {\n *     // Your implementation\n *   }\n *\n *   getCapabilities() {\n *     return { streaming: false, formQuestions: false, knowledgeActions: false, integrations: false };\n *   }\n * }\n * ```\n */\n\n// Core types\nexport type {\n  ProtocolRequest,\n  ProtocolResponse,\n  SessionStatus,\n} from './types';\n\n// Form types\nexport type {\n  ProtocolForm,\n  ProtocolFormField,\n  ProtocolFormOption,\n  ProtocolFieldValidation,\n} from './types';\n\n// Streaming types\nexport type {\n  ProtocolStreamChunk,\n  ProtocolError,\n} from './types';\n\n// Handler interface\nexport type {\n  ProtocolHandler,\n  ProtocolCapabilities,\n  HandlerInfo,\n} from './types';\n\n// Context types\nexport type {\n  ProtocolContext,\n  SessionContext,\n  SessionState,\n  ChatMessage,\n  KnowledgeContext,\n  KnowledgeResult,\n  IntegrationContext,\n  IntegrationResult,\n  HelplineSearchOptions,\n  HelplineResult,\n  Helpline,\n  LoggerContext,\n  RoutingDecision,\n  DeploymentInfo,\n  ChatbotInfo,\n  ClassifierConfig,\n} from './types';\n\n// ============================================\n// Platform Standard Data Types\n// ============================================\n\nexport type {\n  // Form Data\n  FormData,\n  FormFieldValue,\n\n  // Routing Logs\n  RoutingLog,\n\n  // Session Metadata\n  SessionMetadata,\n\n  // Analytics\n  AnalyticsContext,\n  InteractionEvent,\n  InteractionEventType,\n\n  // Form Schema (Protocol Registration)\n  FormSchema,\n  FormFieldDefinition,\n  FormFieldType,\n\n  // Protocol Registration\n  ProtocolRegistration,\n} from './types';\n\n// ============================================\n// UCP (Universal Classification Protocol)\n// ============================================\n\n// UCP Types\nexport type {\n  UCPMessage,\n  UCPClassifyRequest,\n  UCPClassifyResponse,\n  UCPErrorResponse,\n  UCPInfoResponse,\n  UCPClientConfig,\n  UCPEndpointConfig,\n  ClassificationResult,\n} from './ucp';\n\n// UCP Client\nexport {\n  UCPClient,\n  UCPError,\n  createUCPClient,\n  classifyWithUCP,\n} from './ucp';\n\n// ============================================\n// Auth Utilities\n// ============================================\n\nexport {\n  verifyRequestSignature,\n  createRequestSignature,\n  createAuthHeader,\n  isValidToken,\n} from './auth';\n","/**\n * UCP (Universal Classification Protocol) Client\n *\n * Client for communicating with UCP-compliant classifier endpoints.\n * Supports both full configuration and simple endpoint URL.\n *\n * @example\n * ```typescript\n * // Simple usage with endpoint URL\n * const client = UCPClient.fromEndpoint('https://api.example.com/ucp/v1/classifiers/abc123');\n *\n * // With API key\n * const client = UCPClient.fromEndpoint(\n *   'https://api.example.com/ucp/v1/classifiers/abc123',\n *   { apiKey: 'your-api-key' }\n * );\n *\n * // Classify messages\n * const result = await client.classify(messages);\n * ```\n */\n\nimport type {\n  UCPMessage,\n  UCPClassifyRequest,\n  UCPClassifyResponse,\n  UCPErrorResponse,\n  UCPInfoResponse,\n  UCPClientConfig,\n  UCPEndpointConfig,\n  ClassificationResult,\n} from './types';\nimport type { ChatMessage } from '../types';\n\n// Default timeout for requests\nconst DEFAULT_TIMEOUT = 30000;\n\n/**\n * UCP Client for classifier communication\n */\nexport class UCPClient {\n  private baseUrl: string;\n  private classifierId: string;\n  private apiKey?: string;\n  private timeout: number;\n  private headers: Record<string, string>;\n\n  constructor(config: UCPClientConfig) {\n    // Normalize base URL (remove trailing slash)\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.classifierId = config.classifierId;\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;\n    this.headers = config.headers ?? {};\n  }\n\n  /**\n   * Create client from a full endpoint URL\n   *\n   * URL format: {baseUrl}/classifiers/{classifierId}\n   * Example: https://api.example.com/ucp/v1/classifiers/abc123\n   */\n  static fromEndpoint(\n    endpoint: string,\n    options?: { apiKey?: string; timeout?: number }\n  ): UCPClient {\n    // Parse endpoint URL to extract baseUrl and classifierId\n    const url = new URL(endpoint);\n    const pathParts = url.pathname.split('/');\n\n    // Find \"classifiers\" in path and get the ID after it\n    const classifiersIndex = pathParts.indexOf('classifiers');\n    if (classifiersIndex === -1 || classifiersIndex >= pathParts.length - 1) {\n      throw new Error(\n        `Invalid UCP endpoint URL: ${endpoint}. Expected format: {baseUrl}/classifiers/{classifierId}`\n      );\n    }\n\n    const classifierId = pathParts[classifiersIndex + 1];\n    const baseUrlPath = pathParts.slice(0, classifiersIndex).join('/');\n    const baseUrl = `${url.protocol}//${url.host}${baseUrlPath}`;\n\n    return new UCPClient({\n      baseUrl,\n      classifierId,\n      apiKey: options?.apiKey,\n      timeout: options?.timeout,\n    });\n  }\n\n  /**\n   * Get the classify endpoint URL\n   */\n  get classifyUrl(): string {\n    return `${this.baseUrl}/classifiers/${this.classifierId}/classify`;\n  }\n\n  /**\n   * Get the info endpoint URL\n   */\n  get infoUrl(): string {\n    return `${this.baseUrl}/classifiers/${this.classifierId}/info`;\n  }\n\n  /**\n   * Classify messages using UCP protocol\n   */\n  async classify(messages: UCPMessage[]): Promise<ClassificationResult> {\n    const request: UCPClassifyRequest = { messages };\n\n    const response = await this.fetch<UCPClassifyResponse>(\n      this.classifyUrl,\n      {\n        method: 'POST',\n        body: JSON.stringify(request),\n      }\n    );\n\n    // Normalize to SDK format\n    return {\n      classifierId: this.classifierId,\n      category: response.category,\n      level: response.level,\n      confidence: response.score / 100, // Normalize to 0-1\n      reasoning: response.rationale,\n      raw: response,\n    };\n  }\n\n  /**\n   * Classify ChatMessage array (convenience method)\n   * Converts ChatMessage to UCPMessage format\n   */\n  async classifyChat(messages: ChatMessage[]): Promise<ClassificationResult> {\n    const ucpMessages: UCPMessage[] = messages\n      .filter(m => m.role === 'user' || m.role === 'assistant')\n      .map((m, index) => ({\n        id: `msg-${index}`,\n        role: m.role as 'user' | 'assistant',\n        content: m.content,\n        timestamp: m.timestamp ? m.timestamp.getTime() : Date.now(),\n        metadata: m.metadata,\n      }));\n\n    return this.classify(ucpMessages);\n  }\n\n  /**\n   * Get classifier info\n   */\n  async getInfo(): Promise<UCPInfoResponse> {\n    return this.fetch<UCPInfoResponse>(this.infoUrl, {\n      method: 'GET',\n    });\n  }\n\n  /**\n   * Check if the classifier endpoint is reachable\n   */\n  async healthCheck(): Promise<boolean> {\n    try {\n      const healthUrl = `${this.baseUrl}/health`;\n      const response = await fetch(healthUrl, {\n        method: 'GET',\n        signal: AbortSignal.timeout(5000),\n      });\n      return response.ok;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Internal fetch helper with error handling\n   */\n  private async fetch<T>(url: string, options: RequestInit): Promise<T> {\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      ...this.headers,\n    };\n\n    if (this.apiKey) {\n      headers['Authorization'] = `Bearer ${this.apiKey}`;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const response = await fetch(url, {\n        ...options,\n        headers,\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeoutId);\n\n      if (!response.ok) {\n        const errorData = await response.json().catch(() => ({}));\n        const ucpError = errorData as UCPErrorResponse;\n\n        throw new UCPError(\n          ucpError.error?.code || `HTTP_${response.status}`,\n          ucpError.error?.message || `HTTP ${response.status}: ${response.statusText}`,\n          ucpError.error?.details\n        );\n      }\n\n      return response.json() as Promise<T>;\n    } catch (error) {\n      clearTimeout(timeoutId);\n\n      if (error instanceof UCPError) {\n        throw error;\n      }\n\n      if (error instanceof Error) {\n        if (error.name === 'AbortError') {\n          throw new UCPError('TIMEOUT', `Request timed out after ${this.timeout}ms`);\n        }\n        throw new UCPError('NETWORK_ERROR', error.message);\n      }\n\n      throw new UCPError('UNKNOWN_ERROR', 'An unknown error occurred');\n    }\n  }\n}\n\n/**\n * UCP-specific error class\n */\nexport class UCPError extends Error {\n  constructor(\n    public code: string,\n    message: string,\n    public details?: unknown\n  ) {\n    super(message);\n    this.name = 'UCPError';\n  }\n}\n\n// ============================================\n// Convenience Functions\n// ============================================\n\n/**\n * Create a UCP client from an endpoint URL\n */\nexport function createUCPClient(\n  endpoint: string,\n  options?: { apiKey?: string; timeout?: number }\n): UCPClient {\n  return UCPClient.fromEndpoint(endpoint, options);\n}\n\n/**\n * Classify messages using a UCP endpoint\n * One-shot function for simple usage\n */\nexport async function classifyWithUCP(\n  endpoint: string,\n  messages: ChatMessage[],\n  options?: { apiKey?: string; timeout?: number }\n): Promise<ClassificationResult> {\n  const client = createUCPClient(endpoint, options);\n  return client.classifyChat(messages);\n}\n","import { createHmac, timingSafeEqual } from 'crypto';\n\nconst TOKEN_PREFIX = 'fst_';\nconst TOKEN_LENGTH = 44; // fst_ (4) + 40 hex chars\n\n/**\n * Verify an HMAC-SHA256 request signature.\n *\n * The handler server can use this to verify that incoming webhook\n * requests were signed by the FirstStep platform using the shared token.\n *\n * @param token - The API token (FIRSTSTEP_TOKEN)\n * @param payload - The raw request body string\n * @param signature - The signature from the X-FirstStep-Signature header\n * @returns true if the signature is valid\n *\n * @example\n * ```typescript\n * import { verifyRequestSignature } from '@firststep-studio/sdk';\n *\n * app.post('/webhook', (req, res) => {\n *   const signature = req.headers['x-firststep-signature'] as string;\n *   if (!verifyRequestSignature(process.env.FIRSTSTEP_TOKEN!, req.body, signature)) {\n *     return res.status(401).send('Invalid signature');\n *   }\n *   // Process the request...\n * });\n * ```\n */\nexport function verifyRequestSignature(\n  token: string,\n  payload: string,\n  signature: string\n): boolean {\n  try {\n    const expected = createHmac('sha256', token)\n      .update(payload)\n      .digest('hex');\n    const expectedBuffer = Buffer.from(expected, 'hex');\n    const signatureBuffer = Buffer.from(signature, 'hex');\n\n    if (expectedBuffer.length !== signatureBuffer.length) {\n      return false;\n    }\n\n    return timingSafeEqual(expectedBuffer, signatureBuffer);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Create an HMAC-SHA256 signature for a payload.\n *\n * Used by the platform to sign outgoing requests to handler servers.\n *\n * @param token - The API token\n * @param payload - The request body string to sign\n * @returns The hex-encoded HMAC signature\n */\nexport function createRequestSignature(\n  token: string,\n  payload: string\n): string {\n  return createHmac('sha256', token).update(payload).digest('hex');\n}\n\n/**\n * Create an Authorization header value for API requests.\n *\n * @param token - The API token (fst_xxx)\n * @returns The header value, e.g. \"Bearer fst_xxx\"\n *\n * @example\n * ```typescript\n * import { createAuthHeader } from '@firststep-studio/sdk';\n *\n * const response = await fetch('https://api.firststep.ai/api/projects', {\n *   headers: {\n *     'Authorization': createAuthHeader(process.env.FIRSTSTEP_TOKEN!),\n *   },\n * });\n * ```\n */\nexport function createAuthHeader(token: string): string {\n  return `Bearer ${token}`;\n}\n\n/**\n * Validate that a token has the correct format (fst_ prefix + 40 hex chars).\n *\n * @param token - The token string to validate\n * @returns true if the token matches the expected format\n */\nexport function isValidToken(token: string): boolean {\n  return (\n    typeof token === 'string' &&\n    token.startsWith(TOKEN_PREFIX) &&\n    token.length === TOKEN_LENGTH\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,204 @@
+// src/ucp/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+var UCPClient = class _UCPClient {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.classifierId = config.classifierId;
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.headers = config.headers ?? {};
+  }
+  /**
+   * Create client from a full endpoint URL
+   *
+   * URL format: {baseUrl}/classifiers/{classifierId}
+   * Example: https://api.example.com/ucp/v1/classifiers/abc123
+   */
+  static fromEndpoint(endpoint, options) {
+    const url = new URL(endpoint);
+    const pathParts = url.pathname.split("/");
+    const classifiersIndex = pathParts.indexOf("classifiers");
+    if (classifiersIndex === -1 || classifiersIndex >= pathParts.length - 1) {
+      throw new Error(
+        `Invalid UCP endpoint URL: ${endpoint}. Expected format: {baseUrl}/classifiers/{classifierId}`
+      );
+    }
+    const classifierId = pathParts[classifiersIndex + 1];
+    const baseUrlPath = pathParts.slice(0, classifiersIndex).join("/");
+    const baseUrl = `${url.protocol}//${url.host}${baseUrlPath}`;
+    return new _UCPClient({
+      baseUrl,
+      classifierId,
+      apiKey: options?.apiKey,
+      timeout: options?.timeout
+    });
+  }
+  /**
+   * Get the classify endpoint URL
+   */
+  get classifyUrl() {
+    return `${this.baseUrl}/classifiers/${this.classifierId}/classify`;
+  }
+  /**
+   * Get the info endpoint URL
+   */
+  get infoUrl() {
+    return `${this.baseUrl}/classifiers/${this.classifierId}/info`;
+  }
+  /**
+   * Classify messages using UCP protocol
+   */
+  async classify(messages) {
+    const request = { messages };
+    const response = await this.fetch(
+      this.classifyUrl,
+      {
+        method: "POST",
+        body: JSON.stringify(request)
+      }
+    );
+    return {
+      classifierId: this.classifierId,
+      category: response.category,
+      level: response.level,
+      confidence: response.score / 100,
+      // Normalize to 0-1
+      reasoning: response.rationale,
+      raw: response
+    };
+  }
+  /**
+   * Classify ChatMessage array (convenience method)
+   * Converts ChatMessage to UCPMessage format
+   */
+  async classifyChat(messages) {
+    const ucpMessages = messages.filter((m) => m.role === "user" || m.role === "assistant").map((m, index) => ({
+      id: `msg-${index}`,
+      role: m.role,
+      content: m.content,
+      timestamp: m.timestamp ? m.timestamp.getTime() : Date.now(),
+      metadata: m.metadata
+    }));
+    return this.classify(ucpMessages);
+  }
+  /**
+   * Get classifier info
+   */
+  async getInfo() {
+    return this.fetch(this.infoUrl, {
+      method: "GET"
+    });
+  }
+  /**
+   * Check if the classifier endpoint is reachable
+   */
+  async healthCheck() {
+    try {
+      const healthUrl = `${this.baseUrl}/health`;
+      const response = await fetch(healthUrl, {
+        method: "GET",
+        signal: AbortSignal.timeout(5e3)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Internal fetch helper with error handling
+   */
+  async fetch(url, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.headers
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const ucpError = errorData;
+        throw new UCPError(
+          ucpError.error?.code || `HTTP_${response.status}`,
+          ucpError.error?.message || `HTTP ${response.status}: ${response.statusText}`,
+          ucpError.error?.details
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof UCPError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new UCPError("TIMEOUT", `Request timed out after ${this.timeout}ms`);
+        }
+        throw new UCPError("NETWORK_ERROR", error.message);
+      }
+      throw new UCPError("UNKNOWN_ERROR", "An unknown error occurred");
+    }
+  }
+};
+var UCPError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "UCPError";
+  }
+};
+function createUCPClient(endpoint, options) {
+  return UCPClient.fromEndpoint(endpoint, options);
+}
+async function classifyWithUCP(endpoint, messages, options) {
+  const client = createUCPClient(endpoint, options);
+  return client.classifyChat(messages);
+}
+
+// src/auth.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var TOKEN_PREFIX = "fst_";
+var TOKEN_LENGTH = 44;
+function verifyRequestSignature(token, payload, signature) {
+  try {
+    const expected = createHmac("sha256", token).update(payload).digest("hex");
+    const expectedBuffer = Buffer.from(expected, "hex");
+    const signatureBuffer = Buffer.from(signature, "hex");
+    if (expectedBuffer.length !== signatureBuffer.length) {
+      return false;
+    }
+    return timingSafeEqual(expectedBuffer, signatureBuffer);
+  } catch {
+    return false;
+  }
+}
+function createRequestSignature(token, payload) {
+  return createHmac("sha256", token).update(payload).digest("hex");
+}
+function createAuthHeader(token) {
+  return `Bearer ${token}`;
+}
+function isValidToken(token) {
+  return typeof token === "string" && token.startsWith(TOKEN_PREFIX) && token.length === TOKEN_LENGTH;
+}
+export {
+  UCPClient,
+  UCPError,
+  classifyWithUCP,
+  createAuthHeader,
+  createRequestSignature,
+  createUCPClient,
+  isValidToken,
+  verifyRequestSignature
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ucp/client.ts","../src/auth.ts"],"sourcesContent":["/**\n * UCP (Universal Classification Protocol) Client\n *\n * Client for communicating with UCP-compliant classifier endpoints.\n * Supports both full configuration and simple endpoint URL.\n *\n * @example\n * ```typescript\n * // Simple usage with endpoint URL\n * const client = UCPClient.fromEndpoint('https://api.example.com/ucp/v1/classifiers/abc123');\n *\n * // With API key\n * const client = UCPClient.fromEndpoint(\n *   'https://api.example.com/ucp/v1/classifiers/abc123',\n *   { apiKey: 'your-api-key' }\n * );\n *\n * // Classify messages\n * const result = await client.classify(messages);\n * ```\n */\n\nimport type {\n  UCPMessage,\n  UCPClassifyRequest,\n  UCPClassifyResponse,\n  UCPErrorResponse,\n  UCPInfoResponse,\n  UCPClientConfig,\n  UCPEndpointConfig,\n  ClassificationResult,\n} from './types';\nimport type { ChatMessage } from '../types';\n\n// Default timeout for requests\nconst DEFAULT_TIMEOUT = 30000;\n\n/**\n * UCP Client for classifier communication\n */\nexport class UCPClient {\n  private baseUrl: string;\n  private classifierId: string;\n  private apiKey?: string;\n  private timeout: number;\n  private headers: Record<string, string>;\n\n  constructor(config: UCPClientConfig) {\n    // Normalize base URL (remove trailing slash)\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.classifierId = config.classifierId;\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;\n    this.headers = config.headers ?? {};\n  }\n\n  /**\n   * Create client from a full endpoint URL\n   *\n   * URL format: {baseUrl}/classifiers/{classifierId}\n   * Example: https://api.example.com/ucp/v1/classifiers/abc123\n   */\n  static fromEndpoint(\n    endpoint: string,\n    options?: { apiKey?: string; timeout?: number }\n  ): UCPClient {\n    // Parse endpoint URL to extract baseUrl and classifierId\n    const url = new URL(endpoint);\n    const pathParts = url.pathname.split('/');\n\n    // Find \"classifiers\" in path and get the ID after it\n    const classifiersIndex = pathParts.indexOf('classifiers');\n    if (classifiersIndex === -1 || classifiersIndex >= pathParts.length - 1) {\n      throw new Error(\n        `Invalid UCP endpoint URL: ${endpoint}. Expected format: {baseUrl}/classifiers/{classifierId}`\n      );\n    }\n\n    const classifierId = pathParts[classifiersIndex + 1];\n    const baseUrlPath = pathParts.slice(0, classifiersIndex).join('/');\n    const baseUrl = `${url.protocol}//${url.host}${baseUrlPath}`;\n\n    return new UCPClient({\n      baseUrl,\n      classifierId,\n      apiKey: options?.apiKey,\n      timeout: options?.timeout,\n    });\n  }\n\n  /**\n   * Get the classify endpoint URL\n   */\n  get classifyUrl(): string {\n    return `${this.baseUrl}/classifiers/${this.classifierId}/classify`;\n  }\n\n  /**\n   * Get the info endpoint URL\n   */\n  get infoUrl(): string {\n    return `${this.baseUrl}/classifiers/${this.classifierId}/info`;\n  }\n\n  /**\n   * Classify messages using UCP protocol\n   */\n  async classify(messages: UCPMessage[]): Promise<ClassificationResult> {\n    const request: UCPClassifyRequest = { messages };\n\n    const response = await this.fetch<UCPClassifyResponse>(\n      this.classifyUrl,\n      {\n        method: 'POST',\n        body: JSON.stringify(request),\n      }\n    );\n\n    // Normalize to SDK format\n    return {\n      classifierId: this.classifierId,\n      category: response.category,\n      level: response.level,\n      confidence: response.score / 100, // Normalize to 0-1\n      reasoning: response.rationale,\n      raw: response,\n    };\n  }\n\n  /**\n   * Classify ChatMessage array (convenience method)\n   * Converts ChatMessage to UCPMessage format\n   */\n  async classifyChat(messages: ChatMessage[]): Promise<ClassificationResult> {\n    const ucpMessages: UCPMessage[] = messages\n      .filter(m => m.role === 'user' || m.role === 'assistant')\n      .map((m, index) => ({\n        id: `msg-${index}`,\n        role: m.role as 'user' | 'assistant',\n        content: m.content,\n        timestamp: m.timestamp ? m.timestamp.getTime() : Date.now(),\n        metadata: m.metadata,\n      }));\n\n    return this.classify(ucpMessages);\n  }\n\n  /**\n   * Get classifier info\n   */\n  async getInfo(): Promise<UCPInfoResponse> {\n    return this.fetch<UCPInfoResponse>(this.infoUrl, {\n      method: 'GET',\n    });\n  }\n\n  /**\n   * Check if the classifier endpoint is reachable\n   */\n  async healthCheck(): Promise<boolean> {\n    try {\n      const healthUrl = `${this.baseUrl}/health`;\n      const response = await fetch(healthUrl, {\n        method: 'GET',\n        signal: AbortSignal.timeout(5000),\n      });\n      return response.ok;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Internal fetch helper with error handling\n   */\n  private async fetch<T>(url: string, options: RequestInit): Promise<T> {\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      ...this.headers,\n    };\n\n    if (this.apiKey) {\n      headers['Authorization'] = `Bearer ${this.apiKey}`;\n    }\n\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const response = await fetch(url, {\n        ...options,\n        headers,\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeoutId);\n\n      if (!response.ok) {\n        const errorData = await response.json().catch(() => ({}));\n        const ucpError = errorData as UCPErrorResponse;\n\n        throw new UCPError(\n          ucpError.error?.code || `HTTP_${response.status}`,\n          ucpError.error?.message || `HTTP ${response.status}: ${response.statusText}`,\n          ucpError.error?.details\n        );\n      }\n\n      return response.json() as Promise<T>;\n    } catch (error) {\n      clearTimeout(timeoutId);\n\n      if (error instanceof UCPError) {\n        throw error;\n      }\n\n      if (error instanceof Error) {\n        if (error.name === 'AbortError') {\n          throw new UCPError('TIMEOUT', `Request timed out after ${this.timeout}ms`);\n        }\n        throw new UCPError('NETWORK_ERROR', error.message);\n      }\n\n      throw new UCPError('UNKNOWN_ERROR', 'An unknown error occurred');\n    }\n  }\n}\n\n/**\n * UCP-specific error class\n */\nexport class UCPError extends Error {\n  constructor(\n    public code: string,\n    message: string,\n    public details?: unknown\n  ) {\n    super(message);\n    this.name = 'UCPError';\n  }\n}\n\n// ============================================\n// Convenience Functions\n// ============================================\n\n/**\n * Create a UCP client from an endpoint URL\n */\nexport function createUCPClient(\n  endpoint: string,\n  options?: { apiKey?: string; timeout?: number }\n): UCPClient {\n  return UCPClient.fromEndpoint(endpoint, options);\n}\n\n/**\n * Classify messages using a UCP endpoint\n * One-shot function for simple usage\n */\nexport async function classifyWithUCP(\n  endpoint: string,\n  messages: ChatMessage[],\n  options?: { apiKey?: string; timeout?: number }\n): Promise<ClassificationResult> {\n  const client = createUCPClient(endpoint, options);\n  return client.classifyChat(messages);\n}\n","import { createHmac, timingSafeEqual } from 'crypto';\n\nconst TOKEN_PREFIX = 'fst_';\nconst TOKEN_LENGTH = 44; // fst_ (4) + 40 hex chars\n\n/**\n * Verify an HMAC-SHA256 request signature.\n *\n * The handler server can use this to verify that incoming webhook\n * requests were signed by the FirstStep platform using the shared token.\n *\n * @param token - The API token (FIRSTSTEP_TOKEN)\n * @param payload - The raw request body string\n * @param signature - The signature from the X-FirstStep-Signature header\n * @returns true if the signature is valid\n *\n * @example\n * ```typescript\n * import { verifyRequestSignature } from '@firststep-studio/sdk';\n *\n * app.post('/webhook', (req, res) => {\n *   const signature = req.headers['x-firststep-signature'] as string;\n *   if (!verifyRequestSignature(process.env.FIRSTSTEP_TOKEN!, req.body, signature)) {\n *     return res.status(401).send('Invalid signature');\n *   }\n *   // Process the request...\n * });\n * ```\n */\nexport function verifyRequestSignature(\n  token: string,\n  payload: string,\n  signature: string\n): boolean {\n  try {\n    const expected = createHmac('sha256', token)\n      .update(payload)\n      .digest('hex');\n    const expectedBuffer = Buffer.from(expected, 'hex');\n    const signatureBuffer = Buffer.from(signature, 'hex');\n\n    if (expectedBuffer.length !== signatureBuffer.length) {\n      return false;\n    }\n\n    return timingSafeEqual(expectedBuffer, signatureBuffer);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Create an HMAC-SHA256 signature for a payload.\n *\n * Used by the platform to sign outgoing requests to handler servers.\n *\n * @param token - The API token\n * @param payload - The request body string to sign\n * @returns The hex-encoded HMAC signature\n */\nexport function createRequestSignature(\n  token: string,\n  payload: string\n): string {\n  return createHmac('sha256', token).update(payload).digest('hex');\n}\n\n/**\n * Create an Authorization header value for API requests.\n *\n * @param token - The API token (fst_xxx)\n * @returns The header value, e.g. \"Bearer fst_xxx\"\n *\n * @example\n * ```typescript\n * import { createAuthHeader } from '@firststep-studio/sdk';\n *\n * const response = await fetch('https://api.firststep.ai/api/projects', {\n *   headers: {\n *     'Authorization': createAuthHeader(process.env.FIRSTSTEP_TOKEN!),\n *   },\n * });\n * ```\n */\nexport function createAuthHeader(token: string): string {\n  return `Bearer ${token}`;\n}\n\n/**\n * Validate that a token has the correct format (fst_ prefix + 40 hex chars).\n *\n * @param token - The token string to validate\n * @returns true if the token matches the expected format\n */\nexport function isValidToken(token: string): boolean {\n  return (\n    typeof token === 'string' &&\n    token.startsWith(TOKEN_PREFIX) &&\n    token.length === TOKEN_LENGTH\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/server.d.mts

@@ -0,0 +1,77 @@
+import { IncomingMessage, ServerResponse } from 'http';
+import { h as ProtocolHandler } from './types-Bm98aHcd.mjs';
+
+/**
+ * FirstStep SDK Server
+ *
+ * Standalone HTTP server for protocol handlers.
+ * Zero external dependencies, uses Node.js built-in `http` module.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@firststep-studio/sdk/server';
+ * import type { ProtocolHandler } from '@firststep-studio/sdk';
+ *
+ * const handler: ProtocolHandler = {
+ *   async handleMessage(request, context) {
+ *     return {
+ *       message: 'Hello from my handler!',
+ *       sessionId: request.sessionId || 'new',
+ *       agentId: 'main',
+ *       sessionStatus: 'active',
+ *     };
+ *   },
+ *   getCapabilities() {
+ *     return { streaming: false, formQuestions: false, knowledgeActions: false, integrations: false };
+ *   },
+ * };
+ *
+ * const server = createServer(handler, {
+ *   token: process.env.FIRSTSTEP_TOKEN!,
+ *   port: 3001,
+ * });
+ *
+ * server.start();
+ * ```
+ */
+
+interface ServerConfig {
+    /** API token (FIRSTSTEP_TOKEN). Used for request signature verification. */
+    token: string;
+    /** Port to listen on. Defaults to 3001, or the PORT env variable. */
+    port?: number;
+    /** Host to bind to. Defaults to '0.0.0.0'. */
+    host?: string;
+    /** Skip signature verification (for local development only). */
+    skipSignatureVerification?: boolean;
+}
+interface FirstStepServer {
+    /** Start the server */
+    start(): Promise<void>;
+    /** Stop the server gracefully */
+    stop(): Promise<void>;
+    /**
+     * Get the request handler function.
+     * Use this to integrate with Express, Fastify, or other frameworks.
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * const server = createServer(handler, { token: '...' });
+     * app.post('/handshake', server.getRequestHandler());
+     * app.post('/message', server.getRequestHandler());
+     * ```
+     */
+    getRequestHandler(): (req: IncomingMessage, res: ServerResponse) => void;
+}
+/**
+ * Create a standalone HTTP server for a protocol handler.
+ *
+ * The server exposes three endpoints:
+ * - `GET  /health`    - Health check (always 200)
+ * - `POST /handshake` - Returns handler capabilities (signature verified)
+ * - `POST /message`   - Handles a chat message (signature verified)
+ */
+declare function createServer(handler: ProtocolHandler, config: ServerConfig): FirstStepServer;
+
+export { type FirstStepServer, type ServerConfig, createServer };

package/dist/server.d.ts

@@ -0,0 +1,77 @@
+import { IncomingMessage, ServerResponse } from 'http';
+import { h as ProtocolHandler } from './types-Bm98aHcd.js';
+
+/**
+ * FirstStep SDK Server
+ *
+ * Standalone HTTP server for protocol handlers.
+ * Zero external dependencies, uses Node.js built-in `http` module.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@firststep-studio/sdk/server';
+ * import type { ProtocolHandler } from '@firststep-studio/sdk';
+ *
+ * const handler: ProtocolHandler = {
+ *   async handleMessage(request, context) {
+ *     return {
+ *       message: 'Hello from my handler!',
+ *       sessionId: request.sessionId || 'new',
+ *       agentId: 'main',
+ *       sessionStatus: 'active',
+ *     };
+ *   },
+ *   getCapabilities() {
+ *     return { streaming: false, formQuestions: false, knowledgeActions: false, integrations: false };
+ *   },
+ * };
+ *
+ * const server = createServer(handler, {
+ *   token: process.env.FIRSTSTEP_TOKEN!,
+ *   port: 3001,
+ * });
+ *
+ * server.start();
+ * ```
+ */
+
+interface ServerConfig {
+    /** API token (FIRSTSTEP_TOKEN). Used for request signature verification. */
+    token: string;
+    /** Port to listen on. Defaults to 3001, or the PORT env variable. */
+    port?: number;
+    /** Host to bind to. Defaults to '0.0.0.0'. */
+    host?: string;
+    /** Skip signature verification (for local development only). */
+    skipSignatureVerification?: boolean;
+}
+interface FirstStepServer {
+    /** Start the server */
+    start(): Promise<void>;
+    /** Stop the server gracefully */
+    stop(): Promise<void>;
+    /**
+     * Get the request handler function.
+     * Use this to integrate with Express, Fastify, or other frameworks.
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * const server = createServer(handler, { token: '...' });
+     * app.post('/handshake', server.getRequestHandler());
+     * app.post('/message', server.getRequestHandler());
+     * ```
+     */
+    getRequestHandler(): (req: IncomingMessage, res: ServerResponse) => void;
+}
+/**
+ * Create a standalone HTTP server for a protocol handler.
+ *
+ * The server exposes three endpoints:
+ * - `GET  /health`    - Health check (always 200)
+ * - `POST /handshake` - Returns handler capabilities (signature verified)
+ * - `POST /message`   - Handles a chat message (signature verified)
+ */
+declare function createServer(handler: ProtocolHandler, config: ServerConfig): FirstStepServer;
+
+export { type FirstStepServer, type ServerConfig, createServer };