@creature-ai/sdk 0.1.6 → 0.1.7

package/dist/server/index.d.ts

@@ -1,6 +1,65 @@
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+/**
+ * Interface for external state storage.
+ * Implementations can use Redis, DynamoDB, MongoDB, etc.
+ */
+interface StateAdapter {
+    /**
+     * Get state for an instance.
+     */
+    get<T>(instanceId: string): Promise<T | undefined>;
+    /**
+     * Set state for an instance.
+     */
+    set<T>(instanceId: string, state: T): Promise<void>;
+    /**
+     * Delete state for an instance.
+     */
+    delete(instanceId: string): Promise<void>;
+}
+/**
+ * Interface for external realtime communication.
+ * Implementations can use Pusher, Ably, Redis pub/sub, etc.
+ */
+interface RealtimeAdapter {
+    /**
+     * Send a message to all clients subscribed to an instance.
+     */
+    send<T>(instanceId: string, message: T): Promise<void>;
+    /**
+     * Subscribe to messages for an instance.
+     */
+    subscribe(instanceId: string, handler: (message: unknown) => void): () => void;
+    /**
+     * Get the WebSocket/channel URL for clients to connect.
+     */
+    getWebSocketUrl(instanceId: string): string;
+}
+/**
+ * Options for configuring adapters.
+ */
+interface AdapterOptions {
+    /** External state adapter (for stateful features in serverless). */
+    stateAdapter?: StateAdapter;
+    /** External realtime adapter (for WebSocket-like features in serverless). */
+    realtimeAdapter?: RealtimeAdapter;
+}
+/**
+ * Options for vercelMcp adapter.
+ */
+interface VercelMcpOptions extends AdapterOptions {
+    /** Base path for MCP routes (default: '/api'). */
+    basePath?: string;
+    /** Maximum duration for serverless function (default: 60). */
+    maxDuration?: number;
+}
+/**
+ * Options for awsLambda adapter.
+ */
+interface AwsLambdaOptions extends AdapterOptions {
+}
 /**
  * MIME types for cross-platform compatibility.
  */
@@ -77,16 +136,10 @@ interface ResourceConfig {
     websocket?: boolean;
 }
 /**
- * Resource cache configuration.
- * Controls caching behavior for UI resource HTML content.
+ * Internal resource definition.
  */
-interface ResourceCacheConfig {
-    /** Maximum number of cached entries (default: 100) */
-    maxSize?: number;
-    /** Time-to-live in milliseconds. 0 = no expiry (default: 0) */
-    ttlMs?: number;
-    /** Whether caching is enabled (default: true) */
-    enabled?: boolean;
+interface ResourceDefinition {
+    config: ResourceConfig;
 }
 /**
  * Tool configuration.
@@ -139,6 +192,30 @@ interface ToolContext {
      * Automatically attached to tool result for UI routing.
      */
     instanceId: string;
+    /**
+     * Creature App Token for identity verification.
+     * ONLY present when:
+     * 1. App opted into Creature-managed auth (`auth: { creatureManaged: true }`)
+     * 2. Tool call originated from Creature host
+     *
+     * Use `verifyCreatureToken(context.creatureToken)` to verify and extract
+     * user identity for multi-tenant data access.
+     *
+     * @example
+     * ```typescript
+     * app.tool("save_note", { ... }, async ({ content }, context) => {
+     *   if (!context.creatureToken) {
+     *     return { error: "Authentication required" };
+     *   }
+     *   const identity = await verifyCreatureToken(context.creatureToken);
+     *   await db.notes.insert({
+     *     user_id: identity.user.id,
+     *     content,
+     *   });
+     * });
+     * ```
+     */
+    creatureToken?: string;
     /**
      * Get server-side state for this instance.
      * State is NOT sent to UI — use for PIDs, connections, handles.
@@ -174,6 +251,13 @@ interface ToolContext {
      */
     websocketUrl: string | undefined;
 }
+/**
+ * Internal tool definition with handler.
+ */
+interface ToolDefinition<TInput = unknown> {
+    config: ToolConfig;
+    handler: ToolHandler<TInput>;
+}
 /**
  * Context passed to onInstanceDestroy callback.
  */
@@ -199,6 +283,25 @@ interface TransportSessionInfo {
     /** The transport type for this session */
     transport: TransportType;
 }
+/**
+ * Creature-managed authentication configuration.
+ * When enabled, Creature provides user identity and tokens to your app.
+ */
+interface CreatureAuthConfig {
+    /**
+     * Enable Creature-managed authentication.
+     * When true, your app receives user identity (id, email, name) and
+     * organization/project context via hostContext.creature.
+     *
+     * Apps can use this for:
+     * - Auto-registering users without login screens
+     * - Scoping data to users/orgs/projects
+     * - Backend API calls with verified identity
+     *
+     * @default false
+     */
+    creatureManaged?: boolean;
+}
 /**
  * App configuration.
  */
@@ -207,6 +310,14 @@ interface AppConfig {
     name: string;
     /** App version */
     version: string;
+    /**
+     * Authentication configuration.
+     * Enable Creature-managed auth to receive user identity automatically.
+     *
+     * @example
+     * auth: { creatureManaged: true }
+     */
+    auth?: CreatureAuthConfig;
     /**
      * High-level instructions for using this MCP.
      * Sent to the model during initialization to provide context about
@@ -259,11 +370,6 @@ interface AppConfig {
      * Controls how long to wait for in-flight requests to complete.
      */
     keepAliveTimeout?: number;
-    /**
-     * Configuration for resource content caching.
-     * Resources are cached to avoid repeated file reads.
-     */
-    resourceCache?: ResourceCacheConfig;
 }
 /**
  * WebSocket connection for an instance.
@@ -302,8 +408,6 @@ declare class App {
     private callerDir;
     private shutdownRegistered;
     private isShuttingDown;
-    private resourceCache;
-    private resourceCacheConfig;
     /** Server-side instance state, keyed by instanceId. */
     private instanceState;
     /** Callbacks to invoke when an instance is destroyed. */
@@ -380,27 +484,73 @@ declare class App {
      */
     getTransportSessionCount(): number;
     /**
-     * Close a specific transport session.
+     * Get the app configuration.
      */
-    closeTransportSession(sessionId: string): boolean;
+    getConfig(): AppConfig;
     /**
-     * Clear all cached resource content.
+     * Get all tool definitions.
      */
-    clearResourceCache(): void;
+    getToolDefinitions(): Map<string, ToolDefinition>;
     /**
-     * Clear a specific resource from the cache.
+     * Get all resource definitions.
      */
-    clearResourceCacheEntry(uri: string): boolean;
+    getResourceDefinitions(): Map<string, ResourceDefinition>;
     /**
-     * Get resource cache statistics.
+     * Create a Vercel MCP adapter configuration.
+     * For use with Vercel's `mcp-handler` package.
+     *
+     * Note: This returns a configuration callback. The implementation
+     * is inline to avoid circular dependencies.
      */
-    getResourceCacheStats(): {
-        size: number;
-        maxSize: number;
-        enabled: boolean;
-    };
+    toVercelMcp(options?: VercelMcpOptions): (server: any, _context: any) => void;
+    /**
+     * Create an AWS Lambda handler.
+     *
+     * Note: This returns a Lambda handler function. The implementation
+     * is inline to avoid circular dependencies.
+     */
+    toAwsLambda(options?: AwsLambdaOptions): (event: any, _lambdaContext: any) => Promise<{
+        statusCode: number;
+        headers: {
+            "Access-Control-Allow-Origin": string;
+            "Access-Control-Allow-Methods": string;
+            "Access-Control-Allow-Headers": string;
+            "Content-Type": string;
+        };
+        body: string;
+    }>;
+    /**
+     * Close a specific transport session.
+     */
+    closeTransportSession(sessionId: string): boolean;
     private getPort;
     private getCallerDir;
+    /**
+     * Create a ToolContext for serverless environments.
+     * Shared between Vercel and Lambda adapters to avoid duplication.
+     */
+    /**
+     * In-memory state for serverless when no external adapter provided.
+     * Only useful for local development - won't persist across invocations in production.
+     */
+    private serverlessMemoryState;
+    private serverlessStateWarningLogged;
+    private serverlessRealtimeWarningLogged;
+    private createServerlessContext;
+    /**
+     * Format tool result for serverless response.
+     * Shared between Vercel and Lambda adapters.
+     */
+    private formatServerlessResult;
+    /**
+     * Create a Vercel MCP configuration callback.
+     * Returns a function compatible with Vercel's mcp-handler createMcpHandler.
+     */
+    private createServerlessConfig;
+    /**
+     * Create an AWS Lambda handler function.
+     */
+    private createLambdaHandler;
     private getHmrPort;
     private generateInstanceId;
     /**
@@ -421,8 +571,6 @@ declare class App {
      * Check if a field is required in a Zod schema.
      */
     private isFieldRequired;
-    private getCachedResource;
-    private setCachedResource;
     private createExpressApp;
     private handleMcpPost;
     private handleMcpGet;
@@ -520,4 +668,120 @@ declare function htmlLoader(filePath: string, basePath?: string): () => string;
  */
 declare function wrapServer<T extends McpServer>(server: T): T;
 
-export { App, type AppConfig, type DisplayMode, type IconConfig, type InstanceDestroyContext, MIME_TYPES, type ResourceCacheConfig, type ResourceConfig, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type WebSocketConnection, createApp, htmlLoader, loadHtml, svgToDataUri, wrapServer };
+/**
+ * User identity from a verified Creature token.
+ */
+interface CreatureUser {
+    /** Unique, stable user identifier */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's display name (may be undefined) */
+    name?: string;
+}
+/**
+ * Organization context from a verified Creature token.
+ */
+interface CreatureOrganization {
+    /** Unique organization identifier */
+    id: string;
+    /** Organization display name */
+    name: string;
+    /** URL-safe organization slug */
+    slug: string;
+}
+/**
+ * Project context from a verified Creature token.
+ */
+interface CreatureProject {
+    /** Unique project identifier */
+    id: string;
+    /** Project display name */
+    name: string;
+}
+/**
+ * Session context from a verified Creature token.
+ */
+interface CreatureSession {
+    /** Unique session identifier */
+    id: string;
+}
+/**
+ * Verified identity claims from a Creature App Token.
+ * Returned by verifyCreatureToken() on successful verification.
+ */
+interface CreatureIdentity {
+    /** User identity (always present for valid tokens) */
+    user: CreatureUser;
+    /** Organization context (present if user was in an org context) */
+    organization?: CreatureOrganization;
+    /** Project context (present if user was in a project context) */
+    project?: CreatureProject;
+    /** Session context */
+    session?: CreatureSession;
+    /** Token expiration time (ISO 8601 string) */
+    expiresAt: string;
+}
+/**
+ * Error thrown when token verification fails.
+ */
+declare class CreatureTokenError extends Error {
+    /** Error code from the verification API */
+    code: string;
+    constructor({ code, message }: {
+        code: string;
+        message: string;
+    });
+}
+/**
+ * Configuration for the Creature token verification API.
+ */
+interface VerifyConfig {
+    /**
+     * Base URL for the Creature API.
+     * Defaults to https://api.creature.run
+     * Can be overridden for testing or custom deployments.
+     */
+    apiUrl?: string;
+}
+/**
+ * Verifies a Creature App Token and returns the identity claims.
+ *
+ * Use this in your backend API to authenticate requests from your MCP App UI.
+ * The token is provided to your UI via `hostContext.creature.token` when you
+ * opt into Creature-managed auth.
+ *
+ * @param tokenOrHeader - The App Token (raw) or Authorization header ("Bearer <token>")
+ * @param config - Optional configuration (e.g., custom API URL)
+ * @returns The verified identity claims
+ * @throws {CreatureTokenError} If verification fails (invalid, expired, or malformed token)
+ *
+ * @example
+ * ```typescript
+ * import { verifyCreatureToken } from "@creature-ai/sdk/server";
+ *
+ * // In your Express/Hono/etc. API handler:
+ * app.post("/api/notes", async (req, res) => {
+ *   try {
+ *     const identity = await verifyCreatureToken(req.headers.authorization);
+ *
+ *     // Use identity to scope data access
+ *     const notes = await db.notes.find({
+ *       user_id: identity.user.id,
+ *       org_id: identity.organization?.id,
+ *     });
+ *
+ *     res.json({ notes });
+ *   } catch (err) {
+ *     if (err instanceof CreatureTokenError) {
+ *       res.status(401).json({ error: err.code, message: err.message });
+ *     } else {
+ *       res.status(500).json({ error: "internal_error" });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const verifyCreatureToken: (tokenOrHeader: string | undefined | null, config?: VerifyConfig) => Promise<CreatureIdentity>;
+
+export { type AdapterOptions, App, type AppConfig, type AwsLambdaOptions, type CreatureIdentity, type CreatureOrganization, type CreatureProject, type CreatureSession, CreatureTokenError, type CreatureUser, type DisplayMode, type IconConfig, type InstanceDestroyContext, MIME_TYPES, type RealtimeAdapter, type ResourceConfig, type StateAdapter, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type VercelMcpOptions, type WebSocketConnection, createApp, htmlLoader, loadHtml, svgToDataUri, verifyCreatureToken, wrapServer };