@buildbase/sdk 0.0.54 → 0.0.56

package/dist/mcp/index.d.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /** An Agent Skill (Agent Skills Discovery RFC v0.2.0) published by this app. */
 interface AgentSkill {
-    /** Stable slug, e.g. `imejis-api`. */
+    /** Stable slug, e.g. `acme-api`. */
     name: string;
     /** One-line human/agent-readable summary. */
     description: string;
@@ -18,7 +18,7 @@ interface AgentSkill {
 }
 /** One API described in an API Catalog (RFC 9727 / RFC 9264 linkset). */
 interface ApiCatalogApi {
-    /** Anchor URL identifying the API, e.g. `https://api.imejis.io`. */
+    /** Anchor URL identifying the API, e.g. `https://api.example.com`. */
     anchor: string;
     /** OpenAPI / machine-readable description URL (link rel `service-desc`). */
     serviceDesc?: string;
@@ -39,7 +39,7 @@ interface McpServerCard {
     endpoint: string;
     /** Transport type. Defaults to `"streamable-http"`. */
     transport?: string;
-    /** MCP protocol version the server speaks. Defaults to `"2025-06-18"`. */
+    /** MCP protocol version the server speaks. Defaults to `"2025-11-25"`. */
     protocolVersion?: string;
     /**
      * Capability flags. Booleans per SEP-1649 v1.0; a legacy object value
@@ -143,7 +143,7 @@ interface AgentReadyConfig {
     /** The org id (24-hex) whose agent-readiness config to serve. */
     orgId: string;
     /**
-     * This app's public origin, e.g. `https://imejis.io`. Used to build absolute
+     * This app's public origin, e.g. `https://example.com`. Used to build absolute
      * URLs in the Agent Card and to match RFC 9728 resource paths.
      */
     siteUrl: string;
@@ -307,14 +307,14 @@ interface DiscoveryDocument {
  */
 
 /** Every built-in tool, keyed by name. */
-declare const builtinMcpTools: ReadonlyMap<string, McpToolDefinition<any>>;
+declare const builtinMcpTools: ReadonlyMap<string, AnyMcpTool>;
 /** The name of a built-in BuildBase MCP tool. */
 type BuiltinMcpToolName = 'list_workspaces' | 'get_workspace' | 'get_user_profile' | 'list_workspace_users' | 'get_subscription' | 'get_plans' | 'get_plan_versions' | 'get_public_plans' | 'get_plan_version' | 'list_invoices' | 'get_invoice' | 'get_quota_usage' | 'get_all_quota_usage' | 'get_usage_logs' | 'get_credit_balance' | 'list_credit_transactions' | 'get_credit_packages' | 'get_credit_buckets' | 'get_expiring_credits' | 'get_public_credit_packages' | 'check_feature_flag' | 'check_permission' | 'resolve_permissions' | 'get_settings' | 'record_usage' | 'record_usage_batch' | 'consume_credits' | 'send_notification' | 'create_workspace' | 'update_workspace' | 'delete_workspace' | 'invite_workspace_user' | 'remove_workspace_user' | 'update_workspace_user_role' | 'update_user_profile' | 'update_feature_flag' | 'create_subscription_checkout' | 'update_subscription' | 'cancel_subscription' | 'resume_subscription' | 'get_billing_portal_url' | 'purchase_credits';
 /** Resolve a `builtinTools` config value to the tools it selects. */
 declare function selectBuiltinTools(selection: 'all' | 'readonly' | false | {
     include?: BuiltinMcpToolName[];
     exclude?: BuiltinMcpToolName[];
-}): McpToolDefinition<any>[];
+}): AnyMcpTool[];
 
 interface IDocument {
     _id: string;
@@ -1088,7 +1088,7 @@ interface ISettings {
         /** Auto-create workspace on first login */
         autoCreateFirst: boolean;
     };
-    [key: string]: any;
+    [key: string]: unknown;
 }
 
 /** Data passed to a notification template for merge tag replacement. */
@@ -1147,7 +1147,7 @@ interface NotificationData {
         push?: boolean;
     };
     /** Any additional merge tags available as {{key}} in the email template. */
-    [key: string]: any;
+    [key: string]: unknown;
 }
 /** Result of sending a notification. */
 interface NotificationResult {
@@ -1163,6 +1163,88 @@ interface NotificationResult {
     reason?: string;
 }
 
+/**
+ * API client for the signed-in user's devices — the browsers/apps they have
+ * signed in from. Session-authed (x-session-id + x-device-id), scoped to the
+ * current user. Extends BaseApi for shared URL/auth/request handling.
+ *
+ * A device row is login history. Signing a device out revokes its live sessions
+ * but keeps the row (shown as signed-out); "forget" also removes the row.
+ */
+
+/** Coarse geo/network info resolved from the request IP (a lightweight subset). */
+interface IIpInfoLite {
+    ip?: string;
+    hostname?: string;
+    country?: string;
+    city?: string;
+    region?: string;
+    /** "lat,long" string, as provided by the IP lookup. */
+    loc?: string;
+    timezone?: string;
+}
+/** A device the current user has signed in from. */
+interface IDeviceView {
+    /** Stable per-browser/app identifier (the `x-device-id` the client sends). */
+    deviceId: string;
+    /** User-editable label (falls back to a derived name). */
+    name: string;
+    /** IP the device was last seen from. */
+    ip: string;
+    /** Resolved geo/network info for `ip`, when available. */
+    ipInfo: IIpInfoLite | null;
+    userAgent: string;
+    origin: string;
+    /** Whether the user marked this device trusted (longer sessions, fewer prompts). */
+    trusted: boolean;
+    /** ISO string — first time this device was seen. */
+    firstSeenAt?: string;
+    /** ISO string — most recent activity from this device. */
+    lastActiveAt?: string;
+    /** True when this is the device the request came from. */
+    current: boolean;
+    /** Number of live sessions currently on this device. */
+    activeSessions: number;
+    /** Whether this device has an active push-notification subscription. */
+    pushEnabled: boolean;
+}
+
+/**
+ * API client for the signed-in user's active sessions. Session-authed
+ * (x-session-id), scoped to the current user. Extends BaseApi for shared
+ * URL/auth/request handling.
+ *
+ * The raw session id is never exposed — a session's public handle is its
+ * mirror-row id (`ISessionView.id`), which is what `revoke` takes.
+ * "Sign out everywhere" / "sign out current" stay on the auth logout flow.
+ */
+
+/** One live session of the current user, joined to its device's label. */
+interface ISessionView {
+    /** Public handle (mirror-row id) — NOT the raw session id. Use for `revoke`. */
+    id: string;
+    /** The device this session was born on. */
+    deviceId: string;
+    /** OAuth client id, or 'first-party' for a normal app sign-in. */
+    clientId: string;
+    ip: string;
+    ipInfo: IIpInfoLite | null;
+    userAgent: string;
+    origin: string;
+    /** ISO string. */
+    createdAt?: string;
+    /** ISO string. */
+    lastActiveAt?: string;
+    /** ISO string — when the session expires (reflects the org session policy). */
+    expiresAt?: string;
+    /** True when this is the session making the request. */
+    current: boolean;
+    /** The device's label only; ip/userAgent/etc. live on the session itself. */
+    device: {
+        name: string;
+    } | null;
+}
+
 interface WorkspaceActions {
     list(): Promise<IWorkspace[]>;
     get(workspaceId: string): Promise<IWorkspace>;
@@ -1259,6 +1341,28 @@ interface PermissionActions {
     /** Resolve all permissions for a user in a workspace. Returns both platform and app permissions. */
     resolve(workspaceId: string, userId: string): Promise<Set<string>>;
 }
+/** Manage the signed-in user's devices (login history + per-device sign-out). */
+interface DeviceActions {
+    /** List the devices the user has signed in from. */
+    list(): Promise<IDeviceView[]>;
+    /** Rename a device's user-facing label. */
+    rename(deviceId: string, name: string): Promise<void>;
+    /** Sign a device out (revoke its live sessions; keep the history row). */
+    signOut(deviceId: string): Promise<{
+        revokedSessions: number;
+    }>;
+    /** Sign a device out AND remove its history row ("forget"). */
+    forget(deviceId: string): Promise<{
+        revokedSessions: number;
+    }>;
+}
+/** Manage the signed-in user's active sessions. */
+interface SessionActions {
+    /** List the user's live sessions (each joined to its device label). */
+    list(): Promise<ISessionView[]>;
+    /** Sign out one session by its public handle (`ISessionView.id`). */
+    revoke(id: string): Promise<void>;
+}
 interface NotificationActions {
     /**
      * Send a notification to a user or all workspace members.
@@ -1315,6 +1419,8 @@ interface ScopedActions {
     permissions: PermissionActions;
     notification: NotificationActions;
     credits: CreditActions;
+    devices: DeviceActions;
+    sessions: SessionActions;
 }
 
 /**
@@ -1349,13 +1455,20 @@ interface ScopedActions {
  *
  * export const mcp = createMcpHandler({
  *   buildbase,
- *   serverInfo: { name: 'imejis', version: '1.0.0' },
+ *   serverInfo: { name: 'acme', version: '1.0.0' },
  *   auth: {
  *     verify: (token) => {
  *       const c = verifyClientJwt(token, process.env.BUILDBASE_CLIENT_SECRET!);
- *       return { sessionId: String(c.sid), userId: String(c.sub), scopes: c.scope };
+ *       // Claims beyond RFC 7519 are `unknown` — narrow before use.
+ *       return {
+ *         sessionId: typeof c.sid === 'string' ? c.sid : '',
+ *         userId: c.sub,
+ *         scopes: Array.isArray(c.scope)
+ *           ? c.scope.filter((s): s is string => typeof s === 'string')
+ *           : undefined,
+ *       };
  *     },
- *     resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
+ *     resourceMetadataUrl: 'https://example.com/.well-known/oauth-protected-resource',
  *   },
  * });
  *
@@ -1422,6 +1535,14 @@ interface McpToolContext<TCustom = unknown> {
      */
     custom: TCustom;
 }
+/** An icon for display in host UIs (SEP-973, protocol 2025-11-25). */
+interface McpIcon {
+    /** Icon URL (https or data URI). */
+    src: string;
+    mimeType?: string;
+    /** e.g. `['48x48']` or `['any']` for scalable formats. */
+    sizes?: string[];
+}
 /** MCP tool annotations (behavior hints for agents). */
 interface McpToolAnnotations {
     title?: string;
@@ -1430,6 +1551,70 @@ interface McpToolAnnotations {
     idempotentHint?: boolean;
     openWorldHint?: boolean;
 }
+/** Plain text block. */
+interface McpTextContent {
+    type: 'text';
+    text: string;
+}
+/** Base64-encoded image (`data` has no data-URI prefix). */
+interface McpImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+/** Base64-encoded audio (`data` has no data-URI prefix). */
+interface McpAudioContent {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+}
+/** Link to a resource the client may fetch — the content itself is not embedded. */
+interface McpResourceLinkContent {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+}
+/** Resource contents embedded directly in the result (text or base64 blob). */
+interface McpEmbeddedResourceContent {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        title?: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    });
+}
+/** Any content block a tool result may carry. */
+type McpContentBlock = McpTextContent | McpImageContent | McpAudioContent | McpResourceLinkContent | McpEmbeddedResourceContent;
+/**
+ * Full wire-shaped tool result. Return this from `execute` to control the
+ * result exactly — mixed content blocks (text + images + resource links),
+ * `structuredContent`, and the `isError` flag. Any other return value keeps
+ * the legacy behavior: strings become one text block, objects become
+ * JSON text + `structuredContent`.
+ */
+interface McpToolResult {
+    content: McpContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** Text content block (`mcpText('done')`). */
+declare const mcpText: (text: string) => McpTextContent;
+/** Image content block from base64 data (`mcpImage(pngBase64, 'image/png')`). */
+declare const mcpImage: (data: string, mimeType: string) => McpImageContent;
+/** Audio content block from base64 data (`mcpAudio(wavBase64, 'audio/wav')`). */
+declare const mcpAudio: (data: string, mimeType: string) => McpAudioContent;
+/** Resource-link content block (`mcpResourceLink('https://…/report.pdf', 'report')`). */
+declare const mcpResourceLink: (uri: string, name: string, extra?: Omit<McpResourceLinkContent, "type" | "uri" | "name">) => McpResourceLinkContent;
+/** Embedded-resource content block (`mcpEmbeddedResource({ uri, text })`). */
+declare const mcpEmbeddedResource: (resource: McpEmbeddedResourceContent["resource"]) => McpEmbeddedResourceContent;
 /** A tool exposed over MCP. Use {@link defineMcpTool} for inferred input types. */
 interface McpToolDefinition<S extends z.ZodType = z.ZodType, TCustom = any> {
     /** Tool name: `[a-zA-Z0-9_-]`, 1–128 chars. */
@@ -1441,6 +1626,8 @@ interface McpToolDefinition<S extends z.ZodType = z.ZodType, TCustom = any> {
      */
     inputSchema: S | Record<string, unknown>;
     annotations?: McpToolAnnotations;
+    /** Optional icons for host UIs (protocol 2025-11-25). */
+    icons?: McpIcon[];
     /**
      * Scopes required to see/call this tool. The token must carry ALL of them
      * (`McpAuthInfo.scopes`) for the tool to be visible or callable; a token
@@ -1448,8 +1635,98 @@ interface McpToolDefinition<S extends z.ZodType = z.ZodType, TCustom = any> {
      * no scopes and are governed by `builtinTools` + the user's own permissions.
      */
     requiredScopes?: string[];
+    /**
+     * Runs the tool. Return an {@link McpToolResult} for full control over the
+     * wire result (images, resource links, mixed blocks); any other value is
+     * auto-wrapped (string → text block; object → JSON text + structuredContent).
+     */
     execute: (input: z.output<S>, ctx: McpToolContext<TCustom>) => unknown | Promise<unknown>;
 }
+/**
+ * Existential tool type for heterogeneous lists (registries, config arrays).
+ * Each tool keeps its precise schema/context types at its definition site
+ * (use {@link defineMcpTool}); `any` here only erases them for storage —
+ * never use it to define a tool.
+ */
+type AnyMcpTool = McpToolDefinition<any, any>;
+/**
+ * What a resource `read` may return. Strings become text contents, plain
+ * objects become pretty-printed JSON (`application/json`), and an explicit
+ * `{ text }` or `{ blob }` shape is used as-is (blob = base64).
+ */
+type McpResourceReadResult = string | {
+    text: string;
+    mimeType?: string;
+} | {
+    blob: string;
+    mimeType?: string;
+} | object;
+/** A fixed-URI resource served via `resources/list` + `resources/read`. */
+interface McpResourceDefinition<TCustom = any> {
+    /** Unique resource URI (custom schemes welcome, e.g. `app://orders`). */
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    icons?: McpIcon[];
+    /** Same gating semantics as tools: token must carry ALL listed scopes. */
+    requiredScopes?: string[];
+    read: (ctx: McpToolContext<TCustom>) => McpResourceReadResult | Promise<McpResourceReadResult>;
+}
+/**
+ * A parameterized resource (RFC 6570 level-1 `{var}` templates only), served
+ * via `resources/templates/list` and matched on `resources/read`.
+ */
+interface McpResourceTemplateDefinition<TCustom = any> {
+    /** e.g. `buildbase://workspace/{workspaceId}` — `{var}` matches one segment. */
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    icons?: McpIcon[];
+    requiredScopes?: string[];
+    read: (params: Record<string, string>, uri: string, ctx: McpToolContext<TCustom>) => McpResourceReadResult | Promise<McpResourceReadResult>;
+}
+/** Message content allowed in prompts (spec: text, image, audio, embedded resource). */
+type McpPromptContent = McpTextContent | McpImageContent | McpAudioContent | McpEmbeddedResourceContent;
+/** One message of a prompt template. */
+interface McpPromptMessage {
+    role: 'user' | 'assistant';
+    content: McpPromptContent;
+}
+/** A prompt template served via `prompts/list` + `prompts/get`. */
+interface McpPromptDefinition<TCustom = any> {
+    /** Unique prompt name (same charset rules as tool names). */
+    name: string;
+    title?: string;
+    description?: string;
+    icons?: McpIcon[];
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    requiredScopes?: string[];
+    /**
+     * Build the messages. A plain string return becomes one user text message;
+     * an array is used as the messages; the object form also sets `description`.
+     */
+    get: (args: Record<string, string>, ctx: McpToolContext<TCustom>) => string | McpPromptMessage[] | {
+        description?: string;
+        messages: McpPromptMessage[];
+    } | Promise<string | McpPromptMessage[] | {
+        description?: string;
+        messages: McpPromptMessage[];
+    }>;
+}
+/** Identity helper for inferred types (mirror of {@link defineMcpTool}). */
+declare const defineMcpResource: <TCustom = any>(resource: McpResourceDefinition<TCustom>) => McpResourceDefinition<TCustom>;
+/** Identity helper for inferred types (mirror of {@link defineMcpTool}). */
+declare const defineMcpResourceTemplate: <TCustom = any>(template: McpResourceTemplateDefinition<TCustom>) => McpResourceTemplateDefinition<TCustom>;
+/** Identity helper for inferred types (mirror of {@link defineMcpTool}). */
+declare const defineMcpPrompt: <TCustom = any>(prompt: McpPromptDefinition<TCustom>) => McpPromptDefinition<TCustom>;
 /** Configuration for {@link createMcpHandler}. */
 interface CreateMcpHandlerConfig {
     /**
@@ -1486,7 +1763,28 @@ interface CreateMcpHandlerConfig {
      * built-in (your definition wins); duplicate custom names or invalid names
      * throw at create time.
      */
-    tools?: McpToolDefinition<any, any>[];
+    tools?: AnyMcpTool[];
+    /**
+     * App-defined resources (`resources/list` + `resources/read`). The
+     * `resources` capability is advertised only when at least one resource,
+     * template, or `builtinResources` is configured.
+     */
+    resources?: McpResourceDefinition[];
+    /** App-defined parameterized resources (`resources/templates/list`). */
+    resourceTemplates?: McpResourceTemplateDefinition[];
+    /**
+     * Built-in BuildBase context resources (opt-in; requires `buildbase`):
+     * `buildbase://profile`, `buildbase://workspaces`, and the
+     * `buildbase://workspace/{workspaceId}` template — read-only context a host
+     * can load without spending tool calls. Richer data (subscription, usage,
+     * credits) stays tools-only.
+     */
+    builtinResources?: boolean;
+    /**
+     * App-defined prompt templates (`prompts/list` + `prompts/get`). The
+     * `prompts` capability is advertised only when at least one is configured.
+     */
+    prompts?: McpPromptDefinition[];
     /**
      * Which built-in BuildBase tools to expose. **Defaults to `'readonly'`**
      * when a `buildbase` client is configured (`false` otherwise) — reads only,
@@ -1661,6 +1959,24 @@ interface AppTokenRequestClaims {
     sessionId?: string;
     [claim: string]: unknown;
 }
+/**
+ * A verified JWT payload: registered claims (RFC 7519) are typed AND
+ * runtime-validated by {@link verifyClientJwt} (a signed token whose `sub` is
+ * a number is rejected, so the types here are real guarantees). Every other
+ * claim is `unknown` — custom claims are attacker-influenced input until you
+ * narrow them (`typeof payload.sid === 'string'`), even after the signature
+ * checks out.
+ */
+interface VerifiedJwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+    [claim: string]: unknown;
+}
 /** Options for {@link verifyClientJwt} (all optional; secure defaults). */
 interface VerifyClientJwtOptions {
     /** Allowed clock skew in seconds for `exp`/`nbf`. Default 60. */
@@ -1682,7 +1998,7 @@ interface VerifyClientJwtOptions {
  * and — by default — that an `exp` is present at all. Optionally pins `iss`/`aud`.
  * Throws {@link AppBridgeError} on any failure.
  */
-declare function verifyClientJwt(token: string, clientSecret: string, options?: VerifyClientJwtOptions): Record<string, any>;
+declare function verifyClientJwt(token: string, clientSecret: string, options?: VerifyClientJwtOptions): VerifiedJwtPayload;
 /** Extract the token from an `Authorization: Bearer <token>` header. */
 declare function extractBearerToken(authorization: string | null | undefined): string | null;
 /**
@@ -1782,7 +2098,7 @@ interface AgentStackConfig {
             version: string;
         };
         /** Your custom tools. */
-        tools?: McpToolDefinition<any, any>[];
+        tools?: AnyMcpTool[];
         /** Built-in tool selection. Default `'readonly'`. */
         builtinTools?: CreateMcpHandlerConfig['builtinTools'];
         /** Scopes advertised on the protected-resource metadata. */
@@ -1952,5 +2268,5 @@ declare function buildbaseAuth(options: BuildBaseAuthOptions): {
     resourceMetadataUrl?: string;
 };
 
-export { AppBridgeError, bearerChallenge, buildbaseAuth, builtinMcpTools, createAgentStack, createMcpHandler, createSessionRefCrypto, defineMcpTool, extractBearerToken, mintAgentToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
-export type { AgentStack, AgentStackConfig, BuildBaseAuthOptions, BuiltinMcpToolName, CreateMcpHandlerConfig, McpAuthInfo, McpBuildBaseClient, McpHandler, McpHttpRequest, McpHttpResponse, McpServerCard, McpToolAnnotations, McpToolContext, McpToolDefinition, MintAgentTokenOptions, ScopedActions, SessionRefCrypto };
+export { AppBridgeError, bearerChallenge, buildbaseAuth, builtinMcpTools, createAgentStack, createMcpHandler, createSessionRefCrypto, defineMcpPrompt, defineMcpResource, defineMcpResourceTemplate, defineMcpTool, extractBearerToken, mcpAudio, mcpEmbeddedResource, mcpImage, mcpResourceLink, mcpText, mintAgentToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
+export type { AgentStack, AgentStackConfig, AnyMcpTool, BuildBaseAuthOptions, BuiltinMcpToolName, CreateMcpHandlerConfig, McpAudioContent, McpAuthInfo, McpBuildBaseClient, McpContentBlock, McpEmbeddedResourceContent, McpHandler, McpHttpRequest, McpHttpResponse, McpIcon, McpImageContent, McpPromptContent, McpPromptDefinition, McpPromptMessage, McpResourceDefinition, McpResourceLinkContent, McpResourceReadResult, McpResourceTemplateDefinition, McpServerCard, McpTextContent, McpToolAnnotations, McpToolContext, McpToolDefinition, McpToolResult, MintAgentTokenOptions, ScopedActions, SessionRefCrypto, VerifiedJwtPayload };