npm - @creature-ai/sdk - Versions diffs - 0.1.6 → 0.1.8 - Mend

@creature-ai/sdk 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/server/index.d.ts CHANGED Viewed

@@ -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.
  */
@@ -41,15 +100,27 @@ interface ResourceConfig {
     displayModes: DisplayMode[];
     /**
      * HTML content for the resource.
-     * Can be a string path (resolved relative to the server file's directory),
-     * or a function that returns the HTML content.
+     *
+     * Accepts three formats:
+     * 1. **File path** (local development): `"ui/main.html"` - loaded from filesystem
+     * 2. **Raw HTML** (serverless-safe): `"<!DOCTYPE html>..."` - used directly
+     * 3. **Function** (lazy loading): `() => htmlContent` - called when needed
+     *
+     * The SDK auto-detects HTML content (starts with `<`) vs file paths.
+     * For serverless (Vercel, Lambda), use raw HTML or a function.
      *
      * @example
-     * // Simple path (recommended)
+     * // Local development - file path
      * html: "ui/main.html"
      *
-     * // Function for dynamic content
-     * html: () => loadHtml("./ui/main.html")
+     * @example
+     * // Serverless - bundled HTML (import at build time)
+     * import { BUNDLED_HTML } from "./ui-bundle.js";
+     * html: BUNDLED_HTML
+     *
+     * @example
+     * // Serverless - function (lazy)
+     * html: () => fs.readFileSync("./dist/ui/main.html", "utf-8")
      */
     html: string | (() => string | Promise<string>);
     /** Optional icon for pips */
@@ -77,16 +148,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 +204,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 +263,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 +295,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 +322,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 +382,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 +420,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 +496,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 +583,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;
@@ -459,10 +619,29 @@ declare function svgToDataUri(svg: string): string;
  */
 declare function loadHtml(filePath: string, basePath?: string): string;
 /**
- * Create an HTML loader function for a file path.
- * Useful for defining resources with lazy-loaded HTML.
+ * Check if a string is HTML content (vs a file path).
+ *
+ * HTML content detection:
+ * - Starts with `<` (with optional whitespace/BOM)
+ * - Starts with `<!DOCTYPE` (case-insensitive)
+ *
+ * This enables serverless deployments where HTML is bundled at build time
+ * and passed directly as a string, rather than loaded from the filesystem.
+ */
+declare function isHtmlContent(str: string): boolean;
+/**
+ * Create an HTML loader function for a file path or HTML content.
+ *
+ * For serverless environments (Vercel, Lambda), developers can:
+ * 1. Pass HTML content directly: `html: "<!DOCTYPE html>..."`
+ * 2. Use a function: `html: () => BUNDLED_HTML`
+ * 3. Import bundled HTML: `html: await import("./ui-bundle.js").then(m => m.HTML)`
+ *
+ * The SDK automatically detects whether the string is:
+ * - HTML content (starts with `<`) → returns as-is
+ * - File path → loads via filesystem (local dev only)
  */
-declare function htmlLoader(filePath: string, basePath?: string): () => string;
+declare function htmlLoader(htmlOrPath: string, basePath?: string): () => string;
 /**
  * Middleware for adding cross-platform compatibility to the official MCP SDK.
@@ -520,4 +699,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, isHtmlContent, loadHtml, svgToDataUri, verifyCreatureToken, wrapServer };