@buildbase/sdk 0.0.51 → 0.0.54

package/dist/mcp/index.d.ts

@@ -0,0 +1,1956 @@
+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`. */
+    name: string;
+    /** One-line human/agent-readable summary. */
+    description: string;
+    /** Full markdown content of the SKILL.md served for this skill. */
+    content: string;
+    /**
+     * Path the SKILL.md is served from. Defaults to
+     * `/.well-known/agent-skills/<name>/SKILL.md`.
+     */
+    path?: string;
+    /** Skill artifact kind. Defaults to `skill-md`. */
+    type?: 'skill-md' | 'archive';
+}
+/** 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: string;
+    /** OpenAPI / machine-readable description URL (link rel `service-desc`). */
+    serviceDesc?: string;
+    /** Human documentation URL (link rel `service-doc`). */
+    serviceDoc?: string;
+    /** Health / status endpoint URL (link rel `status`). */
+    status?: string;
+    /** Optional human title for the API. */
+    title?: string;
+}
+/** MCP Server Card (SEP-1649 v1.0), advertising a live MCP server. */
+interface McpServerCard {
+    /** Server name. */
+    name: string;
+    /** Server version. */
+    version: string;
+    /** MCP transport endpoint URL the agent connects to. */
+    endpoint: string;
+    /** Transport type. Defaults to `"streamable-http"`. */
+    transport?: string;
+    /** MCP protocol version the server speaks. Defaults to `"2025-06-18"`. */
+    protocolVersion?: string;
+    /**
+     * Capability flags. Booleans per SEP-1649 v1.0; a legacy object value
+     * (e.g. `{ tools: {} }`) is normalized to booleans by presence.
+     */
+    capabilities?: Record<string, unknown>;
+    /** Optional human description. */
+    description?: string;
+    /** Documentation URL. */
+    documentationUrl?: string;
+}
+/** One OAuth scope an app declares in its scope catalog. */
+interface AppScope {
+    /** Scope name, e.g. `designs:read`. */
+    name: string;
+    /** Human-readable description, shown on the consent screen. */
+    description: string;
+}
+/** One skill advertised on the A2A Agent Card. */
+interface A2ACardSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+}
+/**
+ * Overrides for the A2A Agent Card (`/.well-known/agent-card.json`). Every
+ * field is optional — the card is fully derived from `site` + `skills` by
+ * default. See {@link buildA2AAgentCard}.
+ */
+interface A2ACardConfig {
+    name?: string;
+    version?: string;
+    description?: string;
+    /** The endpoint agents connect to. Defaults to `siteUrl`. */
+    serviceUrl?: string;
+    /** Transport protocol advertised for `serviceUrl`. Defaults to `'http'`. */
+    transportProtocol?: string;
+    /** A2A capability flags. Defaults to `{ streaming: false, pushNotifications: false }`. */
+    capabilities?: Record<string, unknown>;
+    /** Skills; defaults to a mapping of `config.skills` (or a generic site skill). */
+    skills?: A2ACardSkill[];
+}
+/** One robots.txt policy group (a `User-agent:` block). */
+interface RobotsPolicy {
+    /** User-agent(s) this group applies to, e.g. `'*'` or `'GPTBot'`. */
+    userAgent: string | string[];
+    /** Paths to allow, e.g. `['/']`. */
+    allow?: string[];
+    /** Paths to disallow, e.g. `['/api/']`. */
+    disallow?: string[];
+    /** Optional `Crawl-delay` (non-standard but widely honored). */
+    crawlDelay?: number;
+}
+/**
+ * Content Signals (https://contentsignals.org) — declares how crawlers may use
+ * this site's content. Each flag renders as `<signal>=yes|no`; omitted flags
+ * are not emitted (unset = no preference expressed).
+ */
+interface ContentSignals {
+    /** May content be indexed for search? → `search=yes|no`. */
+    search?: boolean;
+    /** May content be used as AI input (RAG, grounding)? → `ai-input=yes|no`. */
+    aiInput?: boolean;
+    /** May content be used for AI training? → `ai-train=yes|no`. */
+    aiTrain?: boolean;
+}
+/** Configuration for `buildRobotsTxt`. Every field is optional. */
+interface RobotsConfig {
+    /** Policy groups. Defaults to `[{ userAgent: '*', allow: ['/'] }]`. */
+    policies?: RobotsPolicy[];
+    /**
+     * Stance toward known AI crawlers ({@link AI_BOT_USER_AGENTS}): `'allow'`
+     * (default — an explicit `Allow: /` group per bot, so readiness checkers see
+     * AI bots addressed), `'deny'` (a `Disallow: /` group per bot), or explicit
+     * per-bot policies for finer control.
+     */
+    aiBots?: 'allow' | 'deny' | RobotsPolicy[];
+    /** Content-Signal directive attached to the `User-agent: *` group. */
+    contentSignals?: ContentSignals;
+    /**
+     * Sitemap URLs. Defaults to `${siteUrl}/sitemap.xml` when `config.sitemap`
+     * is set; pass `[]` to emit no `Sitemap:` line.
+     */
+    sitemaps?: string[];
+}
+/** One URL entry for the generated sitemap.xml. */
+interface SitemapUrl {
+    /** Absolute URL, or a path resolved against `siteUrl`. */
+    loc: string;
+    /** ISO-8601 last-modified date. */
+    lastmod?: string;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    /** 0.0–1.0. */
+    priority?: number;
+}
+/** Configuration for the agent-readiness discovery layer. */
+interface AgentReadyConfig {
+    /** BuildBase server base URL, e.g. `https://api.buildbase.app` (no trailing slash needed). */
+    serverUrl: string;
+    /** 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
+     * URLs in the Agent Card and to match RFC 9728 resource paths.
+     */
+    siteUrl: string;
+    /** Static metadata for the Agent Card (`/.well-known/agent.json`). */
+    site: {
+        name: string;
+        description?: string;
+        /** Absolute URL to human/agent documentation. */
+        documentationUrl?: string;
+        /** Support/contact email surfaced on the Agent Card. */
+        contactEmail?: string;
+        /** Provider block; defaults to `{ name: site.name, url: siteUrl }`. */
+        provider?: {
+            name: string;
+            url: string;
+        };
+    };
+    /** Agent Skills to publish. Omit to skip the Agent Skills documents. */
+    skills?: AgentSkill[];
+    /**
+     * The app's OAuth scope catalog — the source of truth for `scopes_supported`
+     * in this app's RFC 9728 protected-resource metadata (served from your own
+     * origin). Declare real, per-app scopes here (`designs:read`,
+     * `render:execute`, …) instead of placeholders. A `protectedResources` entry
+     * without its own `scopes` list inherits every catalog scope name. Scopes are
+     * app-owned: the shared BuildBase authorization server stays scope-agnostic.
+     */
+    scopes?: AppScope[];
+    /** security.txt fields (RFC 9116). Omit to skip serving security.txt. */
+    security?: {
+        /** Contact URI(s) — email (`mailto:`) or URL. */
+        contact: string | string[];
+        /** ISO-8601 expiry; strongly recommended by RFC 9116. */
+        expires?: string;
+        /** Security policy URL. */
+        policy?: string;
+    };
+    /**
+     * API Catalog entries (RFC 9727), served at `/.well-known/api-catalog` as
+     * `application/linkset+json`. Omit to skip.
+     */
+    apiCatalog?: ApiCatalogApi[];
+    /**
+     * MCP Server Card (SEP-1649), served at `/.well-known/mcp/server-card.json`.
+     * Only set this when you actually run an MCP server — the card advertises a
+     * live transport endpoint. Omit to skip.
+     */
+    mcpServerCard?: McpServerCard;
+    /**
+     * Raw `/auth.md` content (agent registration/auth instructions). If omitted,
+     * `buildAuthMd` generates one from the OAuth metadata + site config.
+     */
+    authMd?: string;
+    /**
+     * Local `/llms.txt` content. Takes precedence over the org-authored llms.txt
+     * from the platform bundle — use when the app owns richer llms.txt content.
+     */
+    llmsTxt?: string;
+    /**
+     * Local `/llms-full.txt` content (llmstxt.org expanded document). Omit to
+     * skip serving it (or serve your own static file, which then wins).
+     */
+    llmsFullTxt?: string;
+    /**
+     * A2A Agent Card served at `/.well-known/agent-card.json`. Served by
+     * DEFAULT, derived from `site` + `skills`, so readiness scanners find a
+     * valid card with zero config. Pass `false` to disable, or an object to
+     * override any derived field.
+     */
+    a2aCard?: false | A2ACardConfig;
+    /**
+     * Web Bot Auth key directory (IETF WebBotAuth) served at
+     * `/.well-known/http-message-signatures-directory`. Only for apps whose own
+     * outbound bot/agent signs its requests — publish the JWKS public keys here
+     * so receiving sites can verify the signatures. Omitted = not served.
+     */
+    webBotAuth?: {
+        keys: Array<Record<string, unknown>>;
+    };
+    /**
+     * Extra literal documents served by {@link resolveAgentPath}, keyed by exact
+     * request path. The escape hatch for anything the SDK has no builder for —
+     * commerce discovery (x402, UCP, ACP, MPP), `/openapi.json`, future
+     * `.well-known` documents. A string value infers its content type from the
+     * path extension. Extra paths take precedence over built-in documents, so
+     * they can also override any SDK-generated document.
+     */
+    extraPaths?: Record<string, string | {
+        body: string;
+        contentType?: string;
+        status?: number;
+        cacheControl?: string;
+    }>;
+    /** robots.txt generation (`buildRobotsTxt`). Omitted = sane defaults. */
+    robots?: RobotsConfig;
+    /**
+     * URLs for a minimal generated sitemap.xml (`buildSitemap`). Omit when the
+     * app already generates sitemaps (e.g. next-sitemap) — the builder then
+     * returns null and your own files win.
+     */
+    sitemap?: {
+        urls: Array<string | SitemapUrl>;
+    };
+    /**
+     * RFC 9728 protected resources this app serves, defined locally (app-owned).
+     * When set, the SDK builds the `/.well-known/oauth-protected-resource`
+     * document from this config — `authorization_servers` is derived from
+     * `serverUrl`/`orgId` (the BuildBase issuer). Takes precedence over the
+     * platform bundle. Omit to fall back to the org-configured bundle.
+     */
+    protectedResources?: Array<{
+        /** The protected API's resource URI. Defaults to `siteUrl`. */
+        resource?: string;
+        /** Scopes this resource accepts (`scopes_supported`). */
+        scopes?: string[];
+        /** Human documentation URL (`resource_documentation`). */
+        documentationUrl?: string;
+        /** Bearer methods (`bearer_methods_supported`). Defaults to `['header']`. */
+        bearerMethods?: string[];
+    }>;
+    /** TTL (seconds) for cached platform fetches. Default 300 (5 min). */
+    cacheTtlSeconds?: number;
+    /**
+     * Timeout (ms) for platform fetches. Fail-soft on timeout, so a hung or slow
+     * BuildBase server can't hang discovery routes forever. Default 5000; set `0`
+     * to disable.
+     */
+    fetchTimeoutMs?: number;
+    /** Injectable fetch, mainly for testing. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** A rendered discovery document ready to become an HTTP response. */
+interface DiscoveryDocument {
+    status: number;
+    contentType: string;
+    body: string;
+    cacheControl: string;
+    /** Value for a `Vary` response header, when the body is negotiated. */
+    vary?: string;
+}
+
+/**
+ * Built-in MCP tools mapping BuildBase capabilities to agent-callable tools.
+ *
+ * Authorization model: the agent acts as an authenticated app user — it knows
+ * your app, not BuildBase. Built-in tools therefore carry NO BuildBase-specific
+ * scope requirement; they're available whenever your `auth.verify` accepts the
+ * token and your app chose to expose them. Every call runs under the acting
+ * user's own BuildBase session, so the server enforces that user's permissions
+ * — an agent can never exceed what its user could do. Want per-scope gating on
+ * top? Set `requiredScopes` on your own custom tools — the handler enforces it.
+ *
+ * The read-vs-write boundary is YOUR choice via `builtinTools`: the default is
+ * `'readonly'` (reads only — least privilege). Opt in to `'all'` to also expose
+ * writes AND destructive/billing ops (workspace delete, subscription cancel,
+ * credit purchase — still gated by the user's own permissions), `false` to
+ * expose no built-ins, or `{ include, exclude }` to hand-pick specific tools.
+ *
+ * Every workspace-scoped tool accepts an optional `workspaceId` and falls back
+ * to the workspace pinned on the verified token (`McpAuthInfo.workspaceId`).
+ */
+
+/** Every built-in tool, keyed by name. */
+declare const builtinMcpTools: ReadonlyMap<string, McpToolDefinition<any>>;
+/** 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>[];
+
+interface IDocument {
+    _id: string;
+    /** Optional; some APIs only return _id. Prefer _id for identity. */
+    id?: string;
+    createdAt: string;
+    updatedAt: string;
+    deleted: boolean;
+}
+interface IUser extends IDocument {
+    _id: string;
+    name: string;
+    email: string;
+    /** Profile image URL. Often omitted or empty from API. */
+    image?: string;
+    role: string;
+    /** ISO country code. May be omitted. */
+    country?: string;
+    /** IANA timezone. May be omitted. */
+    timezone?: string;
+    /** Language code. May be omitted. */
+    language?: string;
+    /** Currency code. May be omitted. */
+    currency?: string;
+    attributes?: Record<string, string | number | boolean>;
+}
+type BillingInterval = 'monthly' | 'yearly' | 'quarterly';
+/** Subscription status constants */
+declare const SubscriptionStatus: {
+    readonly Active: "active";
+    readonly Trialing: "trialing";
+    readonly Canceled: "canceled";
+    readonly PastDue: "past_due";
+    readonly Paused: "paused";
+    readonly Incomplete: "incomplete";
+    readonly Unpaid: "unpaid";
+};
+type SubscriptionStatusType = (typeof SubscriptionStatus)[keyof typeof SubscriptionStatus];
+interface ISubscription {
+    _id: string;
+    subscriptionStatus: SubscriptionStatusType;
+    /** Stripe Subscription ID (e.g. 'sub_...'). Present when linked to Stripe. */
+    subscriptionId?: string;
+    stripePriceId?: string;
+    stripeCurrentPeriodEnd?: string;
+    /** When the current monthly usage period ends (quotas reset on this date). */
+    usageCurrentPeriodEnd?: string;
+    cancelAtPeriodEnd: boolean;
+    billingInterval?: BillingInterval;
+    /** Trial start date (ISO string). Set when subscription is in trial. */
+    trialStart?: string;
+    /** Trial end date (ISO string). Set when subscription is in trial. */
+    trialEnd?: string;
+    /** When the subscription was canceled (ISO string). Soft-delete marker. */
+    canceledAt?: string;
+    /** Dunning state: 'none', 'notified', 'warning', 'final', 'suspended'. */
+    dunningState?: string;
+    /** Whether this subscription uses per-seat pricing. */
+    seatPricingEnabled?: boolean;
+    /** Current billable seat count. */
+    currentSeatCount?: number;
+    createdAt: string;
+    updatedAt: string;
+    plan?: {
+        _id: string;
+        name: string;
+        slug: string;
+        description?: string;
+        /** Stripe currency code (e.g. 'usd', 'inr', 'eur'). */
+        currency?: string;
+    };
+}
+interface ISubscriptionItem {
+    _id: string;
+    type: 'feature' | 'limit' | 'quota';
+    name: string;
+    slug: string;
+    description?: string;
+    category: string;
+}
+/** Per-interval quota value (plan-group/versions and public plans schema). */
+interface IQuotaIntervalValue {
+    included: number;
+    /** Overage price in cents. Omitted in public plans; use pricingVariant.quotaOverages for display. */
+    overage?: number;
+    /** Stripe price ID for overage. Omitted in public plans; use pricingVariant.quotaOveragePriceIds. */
+    priceId?: string;
+    /** Unit size for overage pricing (e.g. 1000 = price per 1000 units). */
+    unitSize?: number;
+}
+/** Quota defined per billing interval (new plan-group/versions schema) */
+interface IQuotaByInterval {
+    /** Whether over-usage beyond included is allowed (billed as overage). When false, usage is hard-capped at included amount. Default true. */
+    allowOverage?: boolean;
+    monthly?: IQuotaIntervalValue;
+    yearly?: IQuotaIntervalValue;
+    quarterly?: IQuotaIntervalValue;
+}
+/** Base pricing per interval. Values are often in cents (Stripe); convert for display. */
+interface IBasePricing {
+    monthly: number;
+    yearly: number;
+    quarterly: number;
+}
+/** Stripe price IDs per billing interval (for a single currency variant). */
+interface IStripePricesByInterval {
+    monthlyPriceId?: string;
+    yearlyPriceId?: string;
+    quarterlyPriceId?: string;
+    monthly?: string;
+    yearly?: string;
+}
+/** Overage amounts in cents per interval, keyed by quota slug. Used in pricing variants. */
+type IQuotaOveragesByInterval = Record<string, {
+    monthly?: number;
+    yearly?: number;
+    quarterly?: number;
+}>;
+/** Overage Stripe price IDs per interval, keyed by quota slug. Used in pricing variants. */
+type IQuotaOveragePriceIdsByInterval = Record<string, {
+    monthly?: string;
+    yearly?: string;
+    quarterly?: string;
+}>;
+/**
+ * Multi-currency pricing variant at plan version level.
+ * Each plan version can have multiple variants (e.g. usd, eur, inr, sgd).
+ */
+interface IPricingVariant {
+    _id: string;
+    currency: string;
+    basePricing: IBasePricing;
+    stripePrices: IStripePricesByInterval;
+    /** Per-seat pricing config. When enabled, a second recurring item is on the subscription. */
+    seatPricing?: {
+        enabled: boolean;
+        includedSeats: number;
+        /** Maximum seats allowed. 0 or undefined = unlimited. */
+        maxSeats?: number;
+        perSeat: IBasePricing;
+    };
+    /** Stripe Price IDs for the per-seat recurring price. */
+    seatStripePrices?: IStripePricesByInterval;
+    /** Overage cents per quota slug per interval. */
+    quotaOverages?: IQuotaOveragesByInterval;
+    /** Stripe price IDs for overage per quota slug per interval. */
+    quotaOveragePriceIds?: IQuotaOveragePriceIdsByInterval;
+}
+interface IPlanVersion {
+    _id: string;
+    version: number;
+    name: string;
+    status: 'draft' | 'published';
+    features?: Record<string, boolean>;
+    limits?: Record<string, number>;
+    /** Per-interval quotas (included, unitSize; overage from pricingVariant.quotaOverages). */
+    quotas?: Record<string, IQuotaByInterval>;
+    /** Multi-currency pricing. Each variant has currency, basePricing, stripePrices, quotaOverages. */
+    pricingVariants?: IPricingVariant[];
+    subscriptionItems?: ISubscriptionItem[];
+    /** Trial configuration. When enabled, users can start a free trial of this plan. */
+    trial?: {
+        enabled: boolean;
+        durationDays: number;
+        requireCard: boolean;
+    };
+    /** Credit grant configuration. When enabled, credits are granted to workspaces on this plan. */
+    creditGrant?: {
+        enabled: boolean;
+        /** Linked credit package (populated with name, slug, creditAmount). */
+        creditPackage?: {
+            _id: string;
+            name: string;
+            slug: string;
+            creditAmount: number;
+        } | string;
+        /** How unused plan credits are handled on renewal: 'reset' = expire old, 'topup' = add to existing. */
+        mode: 'reset' | 'topup';
+        /** true = credits given fresh every month, false = one-time lifetime grant (default). */
+        renewOnPeriod?: boolean;
+    };
+    isCurrent?: boolean;
+    isLegacy?: boolean;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+    stripeProductId?: string;
+}
+/** Plan version summary (e.g. plan.latestVersion from subscription API) with subscriptionItems as IDs. */
+interface IPlanVersionSummary extends Omit<IPlanVersion, 'subscriptionItems'> {
+    subscriptionItems?: string[];
+}
+interface IPlan {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    /** Stripe currency code (e.g. 'usd', 'inr', 'eur'). Used for pricing display. */
+    currency?: string;
+    /** Freemium plan: $0 base pricing, no seat billing, no trial. */
+    isFreemium?: boolean;
+    latestVersion?: IPlanVersionSummary;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface IPlanGroupLatestVersion {
+    _id: string;
+    version: number;
+    planVersionIds: string[];
+    requiredItems: string[];
+    status: 'draft' | 'published';
+    isCurrent?: boolean;
+    isLegacy?: boolean;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    description?: string;
+}
+interface IPlanGroup {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    latestVersion?: IPlanGroupLatestVersion;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface IPlanGroupVersion {
+    _id: string;
+    version: number;
+    description?: string;
+    group?: {
+        _id: string;
+        name: string;
+        description?: string;
+    };
+    planVersionIds: IPlanVersionWithPlan[] | string[];
+    requiredItems?: string[];
+    status?: 'draft' | 'published';
+    isCurrent?: boolean;
+    isLegacy?: boolean;
+    archived?: boolean;
+    deleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    id?: string;
+}
+interface ISubscriptionResponse {
+    subscription: ISubscription | null;
+    planVersion: IPlanVersion | null;
+    plan: IPlan | null;
+    group: IPlanGroup | null;
+    groupVersion: IPlanGroupVersion | null;
+}
+/** Plan version with nested plan info (name, slug, currency for display). */
+interface IPlanVersionWithPlan extends IPlanVersion {
+    plan: IPlan;
+}
+/**
+ * Plan group version with full plan versions (for GET .../plan-group/versions).
+ * Each plan has plan, subscriptionItems, quotas (per-interval), pricingVariants.
+ */
+interface IPlanGroupVersionWithPlans {
+    _id: string;
+    version: number;
+    description?: string;
+    /** Full plan versions with nested plan (name, slug, currency). */
+    plans: IPlanVersionWithPlan[];
+    isCurrent?: boolean;
+    whatsNew?: {
+        newPlans: IPlanVersionWithPlan[];
+        updatedPlans: IPlanVersionWithPlan[];
+        removedPlans: IPlanVersionWithPlan[];
+    };
+}
+interface IPlanGroupInfo {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+}
+/** Response from GET workspaces/:id/subscription/plan-group (and by version). */
+interface IPlanGroupResponse {
+    /** Plan group with latestVersion, archived, deleted, timestamps. May be null in some API responses. */
+    group: IPlanGroup | null;
+    /** Current group version with populated planVersionIds (or IDs). */
+    groupVersion: IPlanGroupVersion;
+    /** Full plan versions for display (subscriptionItems, pricingVariants, quotas). */
+    plans: IPlanVersionWithPlan[];
+}
+/**
+ * Response from GET workspaces/:workspaceId/subscription/plan-group/versions.
+ * Group summary plus current and available group versions; each version has plans with
+ * per-interval quotas and pricingVariants.
+ */
+interface IPlanGroupVersionsResponse {
+    /** Plan group summary (_id, name, slug). */
+    group: IPlanGroupInfo;
+    /** Current group version (user's version when subscribed, or latest published when not). */
+    currentVersion: IPlanGroupVersionWithPlans;
+    /** Newer versions when user has subscription; empty when no subscription. */
+    availableVersions: IPlanGroupVersionWithPlans[];
+}
+/**
+ * Optional Stripe-level overrides forwarded to the checkout session.
+ * Use this to pass affiliate/referral tracking data or other Stripe parameters
+ * that should be set on the checkout session or resulting subscription.
+ */
+interface ICheckoutStripeOptions {
+    /** Custom metadata merged into the Stripe checkout session metadata. */
+    metadata?: Record<string, string>;
+    /**
+     * Stripe `client_reference_id` — most affiliate platforms (Rewardful,
+     * FirstPromoter, PartnerStack, etc.) read this field to attribute conversions.
+     */
+    clientReferenceId?: string;
+    /** Custom metadata merged into `subscription_data.metadata` on the Stripe session. */
+    subscriptionMetadata?: Record<string, string>;
+}
+/** Request body for POST .../workspaces/:id/subscription/checkout. */
+interface ICheckoutSessionRequest {
+    planVersionId: string;
+    billingInterval?: BillingInterval;
+    currency?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+    /** Stripe-level overrides for affiliate tracking, referral IDs, etc. */
+    stripeOptions?: ICheckoutStripeOptions;
+}
+interface ICheckoutSessionResponse {
+    /** Response type discriminator. Added for centralized checkout flow. */
+    type?: 'checkout' | 'trial_started' | 'existing';
+    success: boolean;
+    checkoutUrl: string;
+    sessionId: string;
+    message: string;
+    planVersion?: {
+        _id: string;
+        version: number;
+        name: string;
+    };
+}
+/** No-card trial started server-side; no redirect needed. */
+interface ICheckoutTrialResult {
+    type: 'trial_started';
+    success: boolean;
+    checkoutUrl: null;
+    sessionId: null;
+    subscription: ISubscription;
+    message: string;
+}
+/** Workspace already has a matching active subscription. */
+interface ICheckoutExistingResult {
+    type: 'existing';
+    success: boolean;
+    checkoutUrl: null;
+    sessionId: null;
+    message: string;
+    existingSubscription?: {
+        _id: string;
+        subscriptionStatus: string;
+        stripePriceId?: string;
+    };
+}
+/**
+ * Discriminated union for POST /subscription/checkout responses.
+ * - `checkout`: Stripe checkout session created, redirect user to checkoutUrl
+ * - `trial_started`: No-card trial started server-side, no redirect needed
+ * - `existing`: Workspace already has a matching subscription
+ */
+type CheckoutResult = (ICheckoutSessionResponse & {
+    type: 'checkout';
+}) | ICheckoutTrialResult | ICheckoutExistingResult;
+/** Request body for PATCH .../workspaces/:id/subscription. Only these fields are allowed. */
+interface ISubscriptionUpdateRequest {
+    planVersionId: string;
+    billingInterval?: BillingInterval;
+    successUrl?: string;
+    cancelUrl?: string;
+}
+interface ISubscriptionUpdateResponse {
+    _id: string;
+    subscriptionStatus: string;
+    workspace: string;
+    planVersion: string;
+    plan: string;
+    planGroup?: string;
+    planGroupVersion?: string;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface IPublicPlanItemCategory {
+    name: string;
+    slug: string;
+}
+interface IPublicPlanItem {
+    _id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    type: 'feature' | 'limit' | 'quota';
+    category: IPublicPlanItemCategory;
+}
+/**
+ * Public plan version (e.g. from GET /api/v1/public/:orgId/plans/:slug).
+ * Each plan has _id, name (plan display name), version, status, pricingVariants, quotas, features, limits.
+ * Pricing is in cents (see response.notes).
+ */
+interface IPublicPlanVersion {
+    _id: string;
+    /** Plan display name (e.g. "Pro", "Base Plan"). */
+    name: string;
+    /** Whether this is a free ($0) plan with no seat billing or trial. */
+    isFreemium: boolean;
+    version: number;
+    status: 'draft' | 'published';
+    /** Multi-currency pricing. Use getBasePriceCents(plan, currency, interval) and getQuotaDisplayWithVariant for display. */
+    pricingVariants?: IPricingVariant[];
+    /** Keyed by item slug. Per-interval: included, unitSize; overage from pricingVariant.quotaOverages. */
+    quotas: Record<string, IQuotaByInterval>;
+    features: Record<string, boolean>;
+    limits: Record<string, number>;
+    /** Trial config. Only present when the plan has trials enabled. */
+    trial?: {
+        enabled: boolean;
+        durationDays: number;
+        requireCard: boolean;
+    };
+    /** Credit grant config. Only present when the plan grants credits. */
+    creditGrant?: {
+        enabled: boolean;
+        creditAmount: number | null;
+        packageName: string | null;
+        mode: 'reset' | 'topup';
+        /** true = credits given fresh every month, false = one-time lifetime grant. */
+        renewOnPeriod: boolean;
+    };
+}
+interface IPublicPlansResponse {
+    items: IPublicPlanItem[];
+    plans: IPublicPlanVersion[];
+    /** Optional note from API (e.g. "Pricing is in cents. Please convert to dollars for display."). */
+    notes?: string;
+}
+type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
+interface IInvoice {
+    id: string;
+    amount_due: number;
+    number: string | null;
+    amount_paid: number;
+    currency: string;
+    status: InvoiceStatus;
+    created: number;
+    due_date: number | null;
+    hosted_invoice_url: string;
+    invoice_pdf: string | null;
+    description: string | null;
+    subscription: string;
+}
+interface IInvoiceListResponse {
+    invoices: IInvoice[];
+    has_more: boolean;
+}
+interface IInvoiceResponse {
+    invoice: IInvoice;
+}
+/** Request body for POST .../workspaces/:id/subscription/usage */
+interface IRecordUsageRequest {
+    quotaSlug: string;
+    quantity: number;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+}
+/** Response from POST .../workspaces/:id/subscription/usage */
+interface IRecordUsageResponse {
+    used: number;
+    consumed: number;
+    included: number;
+    available: number;
+    overage: number;
+    billedAsync: boolean;
+}
+/** Single quota usage status (shared between status and all endpoints). */
+interface IQuotaUsageStatus {
+    consumed: number;
+    included: number;
+    available: number;
+    overage: number;
+    hasOverage: boolean;
+    /** Whether over-usage is allowed (billed as overage). When false, usage is hard-capped. Default true. */
+    allowOverage?: boolean;
+}
+/** Response from GET .../workspaces/:id/subscription/usage/status?quotaSlug=X */
+interface IQuotaUsageStatusResponse extends IQuotaUsageStatus {
+    quotaSlug: string;
+}
+/** Response from GET .../workspaces/:id/subscription/usage/all */
+interface IAllQuotaUsageResponse {
+    quotas: Record<string, IQuotaUsageStatus>;
+}
+/** Single usage log entry from GET .../usage/logs */
+interface IUsageLogEntry {
+    _id: string;
+    quotaSlug: string;
+    quantity: number;
+    source?: string;
+    workspace: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Query parameters for GET .../workspaces/:id/subscription/usage/logs */
+interface IUsageLogsQuery {
+    quotaSlug?: string;
+    from?: string;
+    to?: string;
+    source?: string;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../workspaces/:id/subscription/usage/logs */
+interface IUsageLogsResponse {
+    docs: IUsageLogEntry[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/** Credit bucket source (how credits entered the workspace) */
+declare const CreditBucketSource: {
+    readonly PlanGrant: "plan_grant";
+    readonly CreditPackPurchase: "credit_pack_purchase";
+    readonly AdminGrant: "admin_grant";
+    readonly Refund: "refund";
+};
+type CreditBucketSourceType = (typeof CreditBucketSource)[keyof typeof CreditBucketSource];
+/** Credit bucket status */
+declare const CreditBucketStatus: {
+    readonly Pending: "pending";
+    readonly Active: "active";
+    readonly Expired: "expired";
+    readonly Consumed: "consumed";
+};
+type CreditBucketStatusType = (typeof CreditBucketStatus)[keyof typeof CreditBucketStatus];
+/** Credit transaction type */
+declare const CreditTransactionType: {
+    readonly PlanGrant: "plan_grant";
+    readonly PackPurchased: "pack_purchased";
+    readonly Consumed: "consumed";
+    readonly Expired: "expired";
+    readonly AdminGrant: "admin_grant";
+    readonly AdminRevoke: "admin_revoke";
+    readonly Refund: "refund";
+};
+type CreditTransactionTypeValue = (typeof CreditTransactionType)[keyof typeof CreditTransactionType];
+/** Credit balance for a workspace */
+interface ICreditBalance {
+    available: number;
+    totalGranted: number;
+    totalConsumed: number;
+    totalExpired: number;
+    totalRefunded: number;
+}
+/** Pricing variant for a credit package */
+interface ICreditPackagePricingVariant {
+    currency: string;
+    /** Price in smallest currency unit (cents) */
+    amount: number;
+    stripePriceId?: string;
+}
+/** Admin-defined purchasable credit package */
+interface ICreditPackage extends IDocument {
+    name: string;
+    slug: string;
+    description?: string;
+    creditAmount: number;
+    pricingVariants: ICreditPackagePricingVariant[];
+    validityDays?: number;
+    isActive: boolean;
+    sortOrder: number;
+    archived: boolean;
+}
+/** A single credit transaction (user-facing event history) */
+interface ICreditTransaction extends IDocument {
+    workspace: string;
+    type: CreditTransactionTypeValue;
+    /** Positive for grants, negative for consume/expire/revoke */
+    amount: number;
+    balanceAfter: number;
+    description?: string;
+    bucket?: string;
+    creditPackage?: string;
+    actor?: string;
+    metadata?: Record<string, any>;
+}
+/** A credit bucket (per-grant allocation with expiry) */
+interface ICreditBucket extends IDocument {
+    workspace: string;
+    source: CreditBucketSourceType;
+    status: CreditBucketStatusType;
+    creditAmount: number;
+    remaining: number;
+    expiresAt?: string;
+    activatedAt?: string;
+    creditPackage?: string | ICreditPackage;
+    grantedBy?: string;
+    metadata?: Record<string, any>;
+}
+/** Request body for POST .../credits/consume */
+interface IConsumeCreditsRequest {
+    amount: number;
+    description?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, any>;
+}
+/** Response from POST .../credits/consume */
+interface IConsumeCreditsResponse {
+    success: boolean;
+    consumed: number;
+    balanceAfter: number;
+}
+/** Request body for POST .../credits/purchase */
+interface ICreditPurchaseRequest {
+    creditPackageId: string;
+    currency?: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+/** Response from POST .../credits/purchase */
+interface ICreditPurchaseResponse {
+    sessionId: string;
+    url: string;
+}
+/** Query params for GET .../credits/transactions */
+interface ICreditTransactionsQuery {
+    type?: CreditTransactionTypeValue;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../credits/transactions */
+interface ICreditTransactionsResponse {
+    docs: ICreditTransaction[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/** Query params for GET .../credits/buckets */
+interface ICreditBucketsQuery {
+    status?: CreditBucketStatusType;
+    source?: CreditBucketSourceType;
+    page?: number;
+    limit?: number;
+}
+/** Paginated response from GET .../credits/buckets */
+interface ICreditBucketsResponse {
+    docs: ICreditBucket[];
+    totalDocs: number;
+    limit: number;
+    page: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/** Response from GET .../credits/expiring */
+interface IExpiringCreditsResponse {
+    days: number;
+    expiringCredits: number;
+    buckets: ICreditBucket[];
+}
+/** Public credit package (from public endpoint, no auth) */
+interface IPublicCreditPackage {
+    _id: string;
+    name: string;
+    slug: string;
+    description: string;
+    creditAmount: number;
+    pricingVariants: ICreditPackagePricingVariant[];
+    validityDays: number | null;
+    sortOrder: number;
+}
+/** Response from GET /:orgId/credit-packages (public, no auth) */
+interface IPublicCreditPackagesResponse {
+    packages: IPublicCreditPackage[];
+    notes?: string;
+}
+
+interface IWorkspace {
+    _id: string;
+    name: string;
+    image?: string;
+    workspaceId: string;
+    users: IUser[];
+    roles: string[];
+    createdBy: string | IUser;
+    features: Record<string, boolean>;
+    /**
+     * Quota usage tracking: { [quotaSlug]: number } – how much of each quota has been used.
+     */
+    quotas?: Record<string, number>;
+    /**
+     * Subscription limits snapshot: { [limitSlug]: number | null } – synced from subscription plan.
+     * Limits are maximum values (e.g. max-users, max-workspaces). Updated when subscription is assigned/updated.
+     */
+    limits?: Record<string, number | null>;
+    subscription?: ISubscription | string | null;
+    /** Stripe Customer ID for this workspace. */
+    stripeCustomerId?: string;
+    /**
+     * Billing currency locked for this workspace (set on first subscription).
+     * Stripe allows one currency per customer; all future subscriptions must use this currency.
+     * When set, subscription UI only shows/uses this currency.
+     */
+    billingCurrency?: string | null;
+    /** Per-workspace permission overrides. Takes priority over org-level settings.permissions. */
+    permissions?: Record<string, string[]>;
+    /** Set when workspace first uses a trial. Blocks trial from being used again on the same workspace. */
+    trialUsedAt?: string | null;
+}
+interface IWorkspaceFeature {
+    _id: string;
+    name: string;
+    description: string;
+    userManaged: boolean;
+    defaultValue: boolean;
+    slug: string;
+    category: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface IWorkspaceUser {
+    _id: string;
+    workspace: string | IWorkspace;
+    user: string | IUser;
+    role: string;
+}
+
+type WorkspaceMode = 'personal' | 'platform';
+interface ISettings {
+    workspace: {
+        roles: string[];
+        defaultRole: string;
+        maxWorkspaces: number;
+        maxWorkspaceUsers: number;
+        /** Workspace mode: 'personal' (solo) or 'platform' (multi-user, default) */
+        mode: WorkspaceMode;
+        /** Whether users can create workspaces. false = disabled, 'owner-only' = restricted */
+        canCreateWorkspace: boolean | 'owner-only';
+        /** Whether members can invite others. false = disabled, 'admin-only' = restricted */
+        canInviteMembers: boolean | 'admin-only';
+        /** Custom role→permission mapping. Overrides SDK defaults when provided by backend. */
+        permissions?: Record<string, string[]>;
+        /** Show workspace switcher in the UI */
+        showSwitcher: boolean;
+        /** Max workspaces a user can own. 0 = unlimited */
+        maxWorkspacesPerUser: number;
+        /** Auto-create workspace on first login */
+        autoCreateFirst: boolean;
+    };
+    [key: string]: any;
+}
+
+/** Data passed to a notification template for merge tag replacement. */
+interface NotificationData {
+    /** Push notification title. Falls back to the event name if not provided. */
+    title?: string;
+    /** Primary message — used in email body and as push notification body. */
+    message?: string;
+    /** Custom icon URL for the push notification. Falls back to the org icon. */
+    icon?: string;
+    /** Large image URL displayed in the push notification body. */
+    image?: string;
+    /** Small monochrome icon for the status bar (Android/ChromeOS). */
+    badge?: string;
+    /** URL to open when the user clicks the push notification. Also available as {{url}} in email template. */
+    url?: string;
+    /** Tag to group/replace notifications. New notification with same tag replaces the previous one instead of stacking. */
+    tag?: string;
+    /** Action buttons displayed on the notification (max 2). */
+    actions?: Array<{
+        action: string;
+        title: string;
+        icon?: string;
+    }>;
+    /** Show notification without sound or vibration. */
+    silent?: boolean;
+    /** Keep notification visible until user interacts (no auto-dismiss). Useful for critical alerts. */
+    requireInteraction?: boolean;
+    /** Vibrate/sound again when replacing a notification with the same tag. Only works with `tag`. */
+    renotify?: boolean;
+    /** Custom timestamp (ms since epoch) displayed on the notification. */
+    timestamp?: number;
+    /** Text direction for title/body. */
+    dir?: 'ltr' | 'rtl' | 'auto';
+    /** Time-to-live in seconds. Push service discards the message if not delivered within this time. Default: 86400 (24h). */
+    ttl?: number;
+    /** Delivery urgency hint. Affects battery/delivery priority on mobile. */
+    urgency?: 'very-low' | 'low' | 'normal' | 'high';
+    /** ISO 8601 date string. Delays delivery until the specified time. */
+    scheduledAt?: string;
+    /**
+     * Which channels to send on. Overrides the event's default channel config.
+     * Omit to use the event's configured channels.
+     *
+     * @example
+     * ```ts
+     * // Only push, no email
+     * { channels: { push: true } }
+     *
+     * // Only email, no push
+     * { channels: { email: true } }
+     * ```
+     */
+    channels?: {
+        email?: boolean;
+        push?: boolean;
+    };
+    /** Any additional merge tags available as {{key}} in the email template. */
+    [key: string]: any;
+}
+/** Result of sending a notification. */
+interface NotificationResult {
+    sent: boolean;
+    /** Which channels were actually used. false = blocked by settings or missing template. */
+    channels: {
+        email: boolean;
+        push: boolean;
+    };
+    /** Number of users notified. 1 for single user, N for whole workspace. */
+    notifiedCount?: number;
+    /** Reason if not sent (e.g., 'event_disabled'). Only present when sent=false. */
+    reason?: string;
+}
+
+interface WorkspaceActions {
+    list(): Promise<IWorkspace[]>;
+    get(workspaceId: string): Promise<IWorkspace>;
+    create(data: {
+        name: string;
+        image?: string;
+    }): Promise<IWorkspace>;
+    update(workspaceId: string, data: Partial<IWorkspace>): Promise<IWorkspace>;
+    delete(workspaceId: string): Promise<{
+        success: boolean;
+    }>;
+}
+interface UserActions {
+    list(workspaceId: string): Promise<IWorkspaceUser[]>;
+    invite(workspaceId: string, email: string, role: string): Promise<{
+        userId: string;
+        workspace: IWorkspace;
+        message: string;
+    }>;
+    remove(workspaceId: string, userId: string): Promise<{
+        userId: string;
+        workspace: IWorkspace;
+        message: string;
+    }>;
+    updateRole(workspaceId: string, userId: string, role: string): Promise<{
+        userId: string;
+        workspace: IWorkspace;
+        message: string;
+    }>;
+    getProfile(): Promise<IUser>;
+    updateProfile(data: Partial<IUser>): Promise<IUser>;
+}
+interface SubscriptionActions {
+    get(workspaceId: string): Promise<ISubscriptionResponse>;
+    checkout(workspaceId: string, request: ICheckoutSessionRequest): Promise<CheckoutResult | ICheckoutSessionResponse>;
+    update(workspaceId: string, request: ISubscriptionUpdateRequest): Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
+    cancel(workspaceId: string): Promise<ISubscriptionResponse>;
+    resume(workspaceId: string): Promise<ISubscriptionResponse>;
+    getBillingPortalUrl(workspaceId: string, returnUrl?: string): Promise<{
+        url: string;
+    }>;
+}
+interface PlanActions {
+    getGroup(workspaceId: string): Promise<IPlanGroupResponse>;
+    getVersions(workspaceId: string): Promise<IPlanGroupVersionsResponse>;
+    /** No auth required */
+    getPublic(slug: string): Promise<IPublicPlansResponse>;
+    /** No auth required */
+    getVersion(groupVersionId: string): Promise<IPlanGroupVersion>;
+}
+interface InvoiceActions {
+    list(workspaceId: string, limit?: number, startingAfter?: string): Promise<IInvoiceListResponse>;
+    get(workspaceId: string, invoiceId: string): Promise<IInvoiceResponse>;
+}
+interface UsageBatchRequest {
+    items: Array<{
+        quotaSlug: string;
+        quantity: number;
+        metadata?: Record<string, any>;
+        source?: string;
+        idempotencyKey?: string;
+    }>;
+}
+interface UsageBatchResponse {
+    success: boolean;
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: Array<{
+        success: boolean;
+        quotaSlug: string;
+        quantity: number;
+        error?: string;
+    }>;
+}
+interface UsageActions {
+    record(workspaceId: string, request: IRecordUsageRequest): Promise<IRecordUsageResponse>;
+    /** Record multiple usage entries in one request. Max 100 items. For bulk/batch operations. */
+    recordBatch(workspaceId: string, request: UsageBatchRequest): Promise<UsageBatchResponse>;
+    getQuota(workspaceId: string, quotaSlug: string): Promise<IQuotaUsageStatusResponse>;
+    getAll(workspaceId: string): Promise<IAllQuotaUsageResponse>;
+    getLogs(workspaceId: string, query?: IUsageLogsQuery): Promise<IUsageLogsResponse>;
+}
+interface SettingsActions {
+    get(): Promise<ISettings>;
+}
+interface FeatureActions {
+    list(): Promise<IWorkspaceFeature[]>;
+    update(workspaceId: string, key: string, value: boolean): Promise<IWorkspace>;
+}
+interface PermissionActions {
+    /** Check if a user has a permission (or all of an array) in a workspace. Works with both platform permissions (Permission.*) and app permissions (custom strings). */
+    check(workspaceId: string, userId: string, permission: string | string[]): Promise<boolean>;
+    /** Resolve all permissions for a user in a workspace. Returns both platform and app permissions. */
+    resolve(workspaceId: string, userId: string): Promise<Set<string>>;
+}
+interface NotificationActions {
+    /**
+     * Send a notification to a user or all workspace members.
+     * Respects all notification gates (org settings, event config, workspace preferences).
+     *
+     * @param workspaceId - The workspace context
+     * @param event - The event slug (e.g., 'comment_added')
+     * @param userId - The user to notify. Omit to notify all workspace members.
+     * @param data - Template merge data. `message` is used as push body.
+     *
+     * @example
+     * ```ts
+     * // Notify one user
+     * await notification.send(workspaceId, 'comment_added', userId, {
+     *   message: 'Alice commented on your project',
+     * })
+     *
+     * // Notify all workspace members
+     * await notification.send(workspaceId, 'new_release', undefined, {
+     *   message: 'Version 2.0 is now available!',
+     * })
+     * ```
+     */
+    send(workspaceId: string, event: string, userId?: string, data?: NotificationData): Promise<NotificationResult>;
+}
+interface CreditActions {
+    /** Get workspace credit balance */
+    getBalance(workspaceId: string): Promise<ICreditBalance>;
+    /** Consume credits from workspace. Throws with code 'INSUFFICIENT_CREDITS' on 402. */
+    consume(workspaceId: string, request: IConsumeCreditsRequest): Promise<IConsumeCreditsResponse>;
+    /** Create Stripe checkout session for purchasing a credit package */
+    purchase(workspaceId: string, request: ICreditPurchaseRequest): Promise<ICreditPurchaseResponse>;
+    /** List available credit packages for purchase */
+    getPackages(workspaceId: string): Promise<ICreditPackage[]>;
+    /** Get paginated credit transaction history */
+    getTransactions(workspaceId: string, query?: ICreditTransactionsQuery): Promise<ICreditTransactionsResponse>;
+    /** Get paginated credit buckets */
+    getBuckets(workspaceId: string, query?: ICreditBucketsQuery): Promise<ICreditBucketsResponse>;
+    /** Get credits expiring within N days (default 7) */
+    getExpiring(workspaceId: string, days?: number): Promise<IExpiringCreditsResponse>;
+    /** Get credit packages publicly (no auth required) */
+    getPublicPackages(): Promise<IPublicCreditPackagesResponse>;
+}
+/** All action modules bound to a specific session. Returned by `withSession()`. */
+interface ScopedActions {
+    workspace: WorkspaceActions;
+    users: UserActions;
+    subscription: SubscriptionActions;
+    plans: PlanActions;
+    invoices: InvoiceActions;
+    usage: UsageActions;
+    settings: SettingsActions;
+    features: FeatureActions;
+    permissions: PermissionActions;
+    notification: NotificationActions;
+    credits: CreditActions;
+}
+
+/**
+ * MCP server toolkit (server-side, framework-agnostic).
+ *
+ * Turns a consuming app into a live MCP (Model Context Protocol) server so AI
+ * agents can operate its BuildBase capabilities — workspaces, subscriptions,
+ * quotas, credits, feature flags, permissions — plus any custom tools the app
+ * defines. The transport is stateless Streamable HTTP: a single JSON-RPC
+ * message per POST, no sessions and no SSE, which keeps the handler pure and
+ * identical on Node 18+, edge, Deno, and Bun.
+ *
+ * Zero framework types: the core `handle()` takes a plain
+ * `{ method, headers, body }` and returns `{ status, headers, body }` (wire it
+ * into Express/Fastify/Hono yourself), while `fetch()` adapts Web-standard
+ * `Request` → `Response` for Next.js App Router and edge runtimes.
+ *
+ * Agents authenticate with the Bearer tokens the app mints via the OAuth2
+ * app-bridge (`handleAppTokenRequest` + `signClientJwt`); the `auth.verify`
+ * callback maps a verified token to the BuildBase session the tools run under.
+ *
+ * @example Next.js App Router — the entire integration:
+ * ```ts
+ * // lib/mcp.ts
+ * import BuildBase from '@buildbase/sdk';
+ * import { createMcpHandler, verifyClientJwt } from '@buildbase/sdk/mcp';
+ *
+ * const buildbase = BuildBase({
+ *   serverUrl: process.env.BUILDBASE_URL!,
+ *   orgId: process.env.BUILDBASE_ORG_ID!,
+ * });
+ *
+ * export const mcp = createMcpHandler({
+ *   buildbase,
+ *   serverInfo: { name: 'imejis', 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 };
+ *     },
+ *     resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
+ *   },
+ * });
+ *
+ * // app/api/mcp/route.ts
+ * import { mcp } from '@/lib/mcp';
+ * export const POST = (req: Request) => mcp.fetch(req);
+ * export const GET = (req: Request) => mcp.fetch(req);    // 405 per spec (no SSE)
+ * export const DELETE = (req: Request) => mcp.fetch(req); // 405 (stateless)
+ * ```
+ */
+
+/**
+ * The slice of the `BuildBase()` client the MCP handler needs. Structural on
+ * purpose (instead of the full `BuildBaseResult`) so the type stays assignable
+ * across the SDK's separately-bundled entry points.
+ */
+interface McpBuildBaseClient {
+    withSession(sessionId: string): ScopedActions;
+}
+/** A transport-agnostic HTTP request (mirror of the DiscoveryDocument idea). */
+interface McpHttpRequest {
+    /** HTTP method, e.g. `'POST'`. */
+    method: string;
+    /** Header map. Keys are matched case-insensitively. */
+    headers: Record<string, string | undefined>;
+    /** Raw JSON body string, or an already-parsed value (e.g. Express req.body). */
+    body?: string | unknown;
+}
+/** A rendered HTTP response ready to hand to any framework. */
+interface McpHttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/** The identity a verified Bearer token resolves to. */
+interface McpAuthInfo {
+    /** BuildBase session all tool calls run under (`buildbase.withSession(...)`). */
+    sessionId: string;
+    /** The acting BuildBase user id — default subject for permission checks. */
+    userId?: string;
+    /** Pin tools to one workspace; used when the agent omits `workspaceId`. */
+    workspaceId?: string;
+    /** OAuth scopes granted to the agent; filters tools with `requiredScopes`. */
+    scopes?: string[];
+    /** Raw verified claims, passed through to tool context. */
+    claims?: Record<string, unknown>;
+}
+/** Context passed to every tool execution. */
+interface McpToolContext<TCustom = unknown> {
+    /**
+     * Session-scoped BuildBase actions (`workspace`, `usage`, `credits`, …).
+     * Only usable when a `buildbase` client was configured — otherwise any
+     * access throws a clear error (tools that don't touch BuildBase never
+     * notice).
+     */
+    bb: ScopedActions;
+    auth: McpAuthInfo;
+    /** Default workspace (from `auth.workspaceId`), if any. */
+    workspaceId?: string;
+    /**
+     * Whatever your `context` factory returned for this request — your own
+     * database handles, services, request info. `undefined` when no factory is
+     * configured.
+     */
+    custom: TCustom;
+}
+/** MCP tool annotations (behavior hints for agents). */
+interface McpToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** 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. */
+    name: string;
+    description: string;
+    /**
+     * Input schema: a zod schema (validated, converted to JSON Schema for
+     * `tools/list`) or a raw JSON Schema object (served as-is, not validated).
+     */
+    inputSchema: S | Record<string, unknown>;
+    annotations?: McpToolAnnotations;
+    /**
+     * 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
+     * with no scopes sees only tools that declare none. Built-in tools declare
+     * no scopes and are governed by `builtinTools` + the user's own permissions.
+     */
+    requiredScopes?: string[];
+    execute: (input: z.output<S>, ctx: McpToolContext<TCustom>) => unknown | Promise<unknown>;
+}
+/** Configuration for {@link createMcpHandler}. */
+interface CreateMcpHandlerConfig {
+    /**
+     * The `BuildBase()` instance the built-in tools run against (via
+     * `withSession`). Optional — omit it to run a standalone MCP server with
+     * only your own tools (built-ins are then disabled and `ctx.bb` throws a
+     * clear error if a tool touches it).
+     */
+    buildbase?: McpBuildBaseClient;
+    /** Advertised in `initialize`. Defaults to `buildbase-mcp`. */
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Optional usage instructions surfaced to agents on `initialize`. */
+    instructions?: string;
+    /**
+     * Per-request context factory for YOUR tools: whatever it returns (your
+     * database, services, request info) is available as `ctx.custom` in every
+     * `execute`. Runs once per `tools/call`, after auth.
+     */
+    context?: (auth: McpAuthInfo | null, req: McpHttpRequest) => unknown | Promise<unknown>;
+    /**
+     * Bearer-token verification. Return null to reject (401). Set `false` to
+     * disable auth entirely — local development only.
+     */
+    auth: {
+        verify: (token: string, req: McpHttpRequest) => McpAuthInfo | null | Promise<McpAuthInfo | null>;
+        /** When set, 401s carry the RFC 9728 `WWW-Authenticate` challenge. */
+        resourceMetadataUrl?: string;
+    } | false;
+    /**
+     * App-defined tools. A custom tool with a built-in's name REPLACES the
+     * built-in (your definition wins); duplicate custom names or invalid names
+     * throw at create time.
+     */
+    tools?: McpToolDefinition<any, any>[];
+    /**
+     * Which built-in BuildBase tools to expose. **Defaults to `'readonly'`**
+     * when a `buildbase` client is configured (`false` otherwise) — reads only,
+     * so no agent can mutate, bill, or delete anything unless you opt in. Set
+     * `'all'` to expose the full surface (reads + writes + destructive/billing
+     * ops like workspace delete, subscription cancel, credit purchase); `false`
+     * for none; or an `{ include, exclude }` selection to hand-pick. Every tool
+     * still runs under the user's session, so the platform enforces the user's
+     * real permissions on top — but least privilege starts here.
+     */
+    builtinTools?: 'all' | 'readonly' | false | {
+        include?: BuiltinMcpToolName[];
+        exclude?: BuiltinMcpToolName[];
+    };
+    /**
+     * Allowed `Origin` header values (DNS-rebinding protection). When set, a
+     * request with a non-matching Origin is rejected with 403. Requests without
+     * an Origin header (curl, server-to-server) always pass.
+     */
+    allowedOrigins?: string[];
+    /**
+     * CORS for browser-based MCP clients. Default **true**: emit
+     * `Access-Control-Allow-Origin: *` (safe for a Bearer-token API — no
+     * cookies are ever involved), or reflect the matching origin when
+     * `allowedOrigins` is set. Pass an origin array to allow only those, or
+     * `false` to emit no CORS headers at all. Preflight (OPTIONS) is answered
+     * automatically either way — no wrapper needed in your route.
+     */
+    cors?: boolean | string[];
+    /**
+     * Hard cap on the raw request-body size in bytes (DoS protection). Bodies
+     * larger than this are rejected with 413 before parsing. Defaults to
+     * 1 MiB (`1_048_576`); set `0` to disable the check.
+     */
+    maxRequestBytes?: number;
+    /**
+     * Optional rate-limit gate, called after authentication and before the
+     * JSON-RPC message is dispatched. Return `false` (or a `{ retryAfter }`
+     * object) to reject the request with 429. The SDK is stateless and holds no
+     * counters itself — back this with your own store (KV, Redis, edge limiter),
+     * keyed by `auth.userId`/`auth.sessionId`. Recommended in production; also
+     * apply platform/edge rate limiting in front of the endpoint.
+     */
+    rateLimit?: (auth: McpAuthInfo | null, req: McpHttpRequest) => boolean | {
+        ok: boolean;
+        retryAfter?: number;
+    } | Promise<boolean | {
+        ok: boolean;
+        retryAfter?: number;
+    }>;
+    /** Called on tool-execution and auth-callback errors (for logging). */
+    onError?: (error: Error, ctx: {
+        method: string;
+        tool?: string;
+    }) => void;
+    /**
+     * Map a thrown tool error to the message returned to the agent. Use it to
+     * redact internal details in production (the full error still reaches
+     * `onError`). Defaults to the raw `error.message`. Return a generic string
+     * — e.g. `() => 'Tool execution failed'` — to leak nothing.
+     */
+    formatToolError?: (error: Error, ctx: {
+        tool: string;
+    }) => string;
+}
+/** The handler returned by {@link createMcpHandler}. */
+interface McpHandler {
+    /** Pure, framework-agnostic core (Express, Fastify, Hono, tests). */
+    handle(req: McpHttpRequest): Promise<McpHttpResponse>;
+    /** Web-standard adapter (Next.js App Router route handlers, edge). */
+    fetch(request: Request): Promise<Response>;
+    /** Metadata for the exposed tools (before per-request scope filtering). */
+    listTools(): Array<{
+        name: string;
+        description: string;
+        annotations?: McpToolAnnotations;
+    }>;
+    /** A ready-to-assign `AgentReadyConfig.mcpServerCard` for this server. */
+    serverCard(options: {
+        endpoint: string;
+        description?: string;
+        documentationUrl?: string;
+    }): McpServerCard;
+}
+/**
+ * Create a stateless MCP server handler exposing BuildBase capabilities (and
+ * any custom tools) over Streamable HTTP. See the module docs for wiring.
+ */
+declare function createMcpHandler(config: CreateMcpHandlerConfig): McpHandler;
+/**
+ * Identity helper that infers the tool's input type from its zod schema.
+ * Pass a second type argument to type `ctx.custom` from your `context`
+ * factory: `defineMcpTool<typeof schema, MyContext>({ ... })`.
+ */
+declare function defineMcpTool<S extends z.ZodType, TCustom = any>(tool: McpToolDefinition<S, TCustom>): McpToolDefinition<S, TCustom>;
+
+/**
+ * OAuth2 app-bridge toolkit (server-side).
+ *
+ * BuildBase runs the OAuth2 authorization flow (login, consent, code, PKCE,
+ * refresh rotation) but it never mints the access token itself — on the token
+ * grant it calls the org's own backend to mint the token the agent will carry.
+ * Concretely, the platform makes signed webhook-style calls to two endpoints an
+ * OAuth2 client registers:
+ *
+ *   • applicationTokenUrl   — mint an access token for a user (required)
+ *   • applicationRevokeUrl  — invalidate a user's token on revocation (optional)
+ *
+ * Both requests carry an `Authorization: Bearer <JWT>` where the JWT is HS256,
+ * signed with the client's secret (so possession of the secret authenticates
+ * the platform). This module verifies those requests and shapes the responses,
+ * so an implementor writes only the part that is theirs: minting/invalidating a
+ * token in their own format.
+ *
+ * HMAC verification uses the SDK's dependency-free pure-JS HMAC-SHA256 (no Web
+ * Crypto, no Node `crypto`, no `require`), so it behaves identically whether the
+ * bundle is loaded as ESM or CJS, under a bundler or on bare Node.
+ *
+ * @example applicationTokenUrl handler (Next.js Pages Router):
+ * ```ts
+ * import { handleAppTokenRequest } from "@buildbase/sdk";
+ * export default async function handler(req, res) {
+ *   const { status, body } = await handleAppTokenRequest({
+ *     authorization: req.headers.authorization,
+ *     clientSecret: process.env.BUILDBASE_CLIENT_SECRET!,
+ *     mintToken: (user) => ({
+ *       token: signMyAccessToken(user, { aud: user.resource }), // your token, your format
+ *       expiresIn: 3600,
+ *     }),
+ *   });
+ *   res.status(status).json(body);
+ * }
+ * ```
+ */
+/** Thrown when an incoming platform request fails verification. */
+declare class AppBridgeError extends Error {
+    /** Machine-readable reason, e.g. `invalid_signature`, `token_expired`. */
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * The user + grant context BuildBase sends to `applicationTokenUrl`. The app
+ * mints a token for this user; `resource` is the RFC 8707 audience(s) the token
+ * should be bound to (stamp them as `aud`), and `scope` is what the user granted.
+ * Unknown claims are preserved for forward-compatibility.
+ */
+interface AppTokenRequestClaims {
+    /** The user's id in the org. */
+    id: string;
+    email: string;
+    name?: string;
+    role?: string;
+    emailVerified?: boolean;
+    image?: string;
+    blocked?: boolean;
+    blockedReason?: string;
+    blockedAt?: string;
+    /** Which grant triggered this mint. */
+    grantType?: 'authorization_code' | 'refresh_token';
+    /** Scopes granted at authorization time. */
+    scope?: string[];
+    /** RFC 8707 resource indicator(s) — bind the minted token's `aud` to these. */
+    resource?: string[];
+    /** The OAuth2 client's display title. */
+    clientTitle?: string;
+    /**
+     * Per-user BuildBase session bound to this grant. Embed it ENCRYPTED in the
+     * token you mint (JWTs are signed, not encrypted) and never store it — your
+     * MCP/agent endpoints decrypt it per request to call BuildBase as this user
+     * (`buildbase.withSession(...)`). Fresh on every grant, including refresh.
+     */
+    sessionId?: string;
+    [claim: string]: unknown;
+}
+/** Options for {@link verifyClientJwt} (all optional; secure defaults). */
+interface VerifyClientJwtOptions {
+    /** Allowed clock skew in seconds for `exp`/`nbf`. Default 60. */
+    clockToleranceSec?: number;
+    /**
+     * Require a numeric `exp` claim. Default **true** — a JWT with no expiry
+     * would never expire, so a leaked token stays valid forever. Set `false`
+     * only for a token type you know is intentionally non-expiring.
+     */
+    requireExp?: boolean;
+    /** If set, `iss` must equal this value (RFC 7519 issuer check). */
+    issuer?: string;
+    /** If set, `aud` must equal (or, for an array `aud`, include) this value. */
+    audience?: string;
+}
+/**
+ * Verify a BuildBase-issued HS256 JWT (signed with the client secret) and return
+ * its payload. Checks the signature (timing-safe), the algorithm, `exp`/`nbf`,
+ * 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>;
+/** Extract the token from an `Authorization: Bearer <token>` header. */
+declare function extractBearerToken(authorization: string | null | undefined): string | null;
+/**
+ * Sign an HS256 JWT — the symmetric counterpart of {@link verifyClientJwt}.
+ * Sets `iat` and `exp` (from `expiresInSec`, default 3600) unless the payload
+ * already carries them. The intended use is minting the app's own agent access
+ * tokens in an `applicationTokenUrl` handler, embedding whatever claims the
+ * MCP/API layer needs to verify later (e.g. `sub`, `scope`, a session id).
+ */
+declare function signClientJwt(payload: Record<string, unknown>, secret: string, options?: {
+    expiresInSec?: number;
+}): string;
+declare function bearerChallenge(options: {
+    resourceMetadataUrl: string;
+    error?: 'invalid_token' | 'insufficient_scope' | string;
+    errorDescription?: string;
+}): {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+};
+
+/**
+ * createAgentStack — the whole agent-readiness + MCP surface from ONE config.
+ *
+ * Everything the SDK can derive, it derives: the MCP endpoint, the server
+ * card, the RFC 9728 protected-resource metadata, the API-catalog entry, the
+ * BuildBase client, token verification (via `buildbaseAuth`), CORS, and the
+ * discovery `Link` header — so a consumer configures identity once and wires
+ * two routes. Every derived value stays overridable ("accelerate, never
+ * gate").
+ *
+ * @example Next.js App Router — complete agent support:
+ * ```ts
+ * // lib/agent.ts
+ * import { createAgentStack } from "@buildbase/sdk/mcp";
+ * export const agent = createAgentStack({
+ *   serverUrl: process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL!,
+ *   orgId: process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!,
+ *   siteUrl: "https://app.example.com",
+ *   site: { name: "My App" },
+ *   secret: process.env.SYSTEM_SECRET!,
+ * });
+ *
+ * // app/api/mcp/route.ts
+ * import { agent } from "@/lib/agent";
+ * export const { GET, POST, DELETE, OPTIONS } = agent.routes;
+ *
+ * // app/.well-known/[...path]/route.ts — and identical one-liners at
+ * // app/robots.txt/route.ts, app/auth.md/route.ts, app/security.txt/route.ts
+ * import { agent } from "@/lib/agent";
+ * export const GET = agent.serveAgentPath;
+ * ```
+ *
+ * @example Express / Hono / Bun — same stack, `handle`/`fetch` style:
+ * ```ts
+ * app.all("/api/mcp", async (req, res) => {
+ *   const r = await agent.mcp.handle({ method: req.method, headers: req.headers, body: req.body });
+ *   res.status(r.status).set(r.headers).send(r.body);
+ * });
+ * app.use(async (req, res, next) => {
+ *   const doc = await agent.resolvePath(req.path);
+ *   if (!doc) return next();
+ *   res.status(doc.status).set("Content-Type", doc.contentType).send(doc.body);
+ * });
+ * ```
+ */
+
+/** Configuration for {@link createAgentStack}. */
+interface AgentStackConfig {
+    /** BuildBase server base URL. */
+    serverUrl: string;
+    /** The org id. */
+    orgId: string;
+    /** This app's public origin, e.g. `https://app.example.com`. */
+    siteUrl: string;
+    /** Site identity for every discovery document. */
+    site: AgentReadyConfig['site'];
+    /**
+     * The app's token-signing secret — wires `buildbaseAuth` (verify + audience
+     * binding + `sid` decryption) automatically. Never sent anywhere. Omit only
+     * when supplying `mcp.auth` yourself.
+     */
+    secret?: string;
+    /**
+     * The app's OAuth scope catalog (see `AgentReadyConfig.scopes`) —
+     * `scopes_supported` in the protected-resource metadata reads from it.
+     */
+    scopes?: AppScope[];
+    /** MCP server options. All optional — omit the whole block for defaults. */
+    mcp?: {
+        /** Endpoint path on `siteUrl`. Default `/api/mcp`. */
+        path?: string;
+        /** Advertised server identity. Defaults to the site name, v1.0.0. */
+        serverInfo?: {
+            name: string;
+            version: string;
+        };
+        /** Your custom tools. */
+        tools?: McpToolDefinition<any, any>[];
+        /** Built-in tool selection. Default `'readonly'`. */
+        builtinTools?: CreateMcpHandlerConfig['builtinTools'];
+        /** Scopes advertised on the protected-resource metadata. */
+        scopes?: string[];
+        /** Your own BuildBase client; auto-created from serverUrl/orgId if omitted. */
+        buildbase?: McpBuildBaseClient;
+        /** Override the derived auth (e.g. `false` for local dev). */
+        auth?: CreateMcpHandlerConfig['auth'];
+        /** Any remaining `createMcpHandler` option, merged last. */
+        handler?: Partial<CreateMcpHandlerConfig>;
+    };
+    /**
+     * Any {@link AgentReadyConfig} field (robots, skills, llms.txt, security,
+     * a2aCard, extraPaths, …) — merged over the derived discovery config, so
+     * every derived value can be replaced.
+     */
+    discovery?: Partial<AgentReadyConfig>;
+}
+/** What {@link createAgentStack} returns. */
+interface AgentStack {
+    /** The MCP handler (`handle`/`fetch`/`listTools`/`serverCard`). */
+    mcp: McpHandler;
+    /** Absolute MCP endpoint URL. */
+    mcpEndpoint: string;
+    /** The fully derived discovery config (inspect or reuse in middleware). */
+    config: AgentReadyConfig;
+    /** Discovery `Link` header value for your middleware / edge responses. */
+    linkHeader: string;
+    /** Resolve any agent-facing path to a document (framework-agnostic). */
+    resolvePath(path: string): Promise<DiscoveryDocument | null>;
+    /** Web-standard discovery route: hand it any `Request`, get a `Response`. */
+    serveAgentPath(request: Request): Promise<Response>;
+    /**
+     * Web-standard MCP route handlers, ready to re-export from a route file:
+     * `export const { GET, POST, DELETE, OPTIONS } = agent.routes`.
+     */
+    routes: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+        DELETE: (request: Request) => Promise<Response>;
+        OPTIONS: (request: Request) => Promise<Response>;
+    };
+}
+/**
+ * Build the complete agent stack — MCP server + discovery surface — from one
+ * config object. See the module doc for full wiring examples.
+ */
+declare function createAgentStack(stack: AgentStackConfig): AgentStack;
+
+/**
+ * BuildBase agent-auth presets (server-side, framework-agnostic).
+ *
+ * The BuildBase security model: the platform runs the OAuth2 flow (login,
+ * consent, PKCE, refresh) but the APP mints and verifies its own user tokens,
+ * signed with the app's own secret. The platform only relays the minted token
+ * to the agent — it never sees the secret, so it can neither forge nor decode
+ * an app token. The per-user BuildBase session travels inside the token only
+ * as an AES-256-GCM-encrypted `sid` claim, so it is never stored and never
+ * plaintext anywhere; access to it expires with the token.
+ *
+ * These presets make that model a one-liner on each side of the flow, and run
+ * entirely in the app's process — pure local crypto, zero platform calls:
+ *
+ *   • {@link mintAgentToken}  — inside your `applicationTokenUrl` handler:
+ *     signs the app JWT (HS256) with your secret, stamps `aud` from the RFC
+ *     8707 resource, and embeds the encrypted `sid` automatically.
+ *   • {@link buildbaseAuth}   — the `auth` config for `createMcpHandler`:
+ *     verifies the JWT, enforces audience binding, decrypts the `sid`, and
+ *     maps the claims to `McpAuthInfo`.
+ *
+ * @example The full loop:
+ * ```ts
+ * // applicationTokenUrl route — the platform calls this on every grant
+ * const { status, body } = await handleAppTokenRequest({
+ *   authorization: req.headers.get("authorization"),
+ *   clientSecret: process.env.BUILDBASE_CLIENT_SECRET!,
+ *   mintToken: (claims) => mintAgentToken({ claims, secret: process.env.SYSTEM_SECRET! }),
+ * });
+ *
+ * // MCP server — verifies what the route above minted
+ * const mcp = createMcpHandler({
+ *   buildbase,
+ *   auth: buildbaseAuth({ secret: process.env.SYSTEM_SECRET!, resource: "https://app.example.com/api/mcp" }),
+ * });
+ * ```
+ *
+ * AES-GCM comes from WebCrypto (`globalThis.crypto.subtle`) — Node 18+, Bun,
+ * Deno, edge runtimes, browsers. The wire format is
+ * `base64url(iv(12) || authTag(16) || ciphertext)` with the key derived as
+ * `SHA-256(secret + ":bb-session")`, byte-compatible with Node
+ * `createCipheriv("aes-256-gcm", ...)` implementations of the same layout.
+ */
+
+/** Encrypt/decrypt pair for the `sid` claim, bound to one app secret. */
+interface SessionRefCrypto {
+    /** Encrypt a BuildBase session id for embedding in an app JWT. */
+    encryptSessionRef(sessionId: string): Promise<string>;
+    /** Decrypt a `sid` claim. Returns null on any failure (wrong key, garbage). */
+    decryptSessionRef(ref: string): Promise<string | null>;
+}
+/**
+ * Session-ref crypto derived from the app's secret. Both sides of the loop
+ * ({@link mintAgentToken}, {@link buildbaseAuth}) use this internally — reach
+ * for it directly only when minting or verifying tokens by hand.
+ */
+declare function createSessionRefCrypto(secret: string): SessionRefCrypto;
+/** Options for {@link mintAgentToken}. */
+interface MintAgentTokenOptions {
+    /** The verified platform claims (from `handleAppTokenRequest`'s callback). */
+    claims: AppTokenRequestClaims;
+    /** The APP's token-signing secret. Never leaves this process. */
+    secret: string;
+    /** Token lifetime in seconds. Default 3600 — keep agent tokens short-lived. */
+    expiresInSec?: number;
+    /**
+     * App-specific claims merged into the token — e.g. a `workspaceId` resolved
+     * by your own user sync. Merged last, so they can override the defaults.
+     */
+    extraClaims?: Record<string, unknown>;
+}
+/**
+ * Mint the app's agent access token from a platform grant: HS256-signed with
+ * YOUR secret, `aud` bound to the granted RFC 8707 resource(s), scopes carried
+ * through, and the per-user BuildBase session embedded as an encrypted `sid`
+ * claim. The result plugs straight into `handleAppTokenRequest`'s `mintToken`.
+ */
+declare function mintAgentToken(options: MintAgentTokenOptions): Promise<{
+    token: string;
+    expiresIn: number;
+}>;
+/** Options for {@link buildbaseAuth}. */
+interface BuildBaseAuthOptions {
+    /** The APP's token-signing secret — the same one `mintAgentToken` used. */
+    secret: string;
+    /**
+     * The protected resource(s) this server IS. Enforces RFC 8707 audience
+     * binding — the token's `aud` must include one of these URIs. Pass an array
+     * when the server is addressable under more than one resource identifier
+     * (e.g. the canonical `<host>/mcp` plus the literal endpoint URL); the
+     * FIRST entry is the canonical one used to derive `resourceMetadataUrl`.
+     */
+    resource?: string | string[];
+    /**
+     * Explicit RFC 9728 metadata URL for the 401 challenge. Defaults to the
+     * path-derived `/.well-known/oauth-protected-resource<path>` of the first
+     * `resource`.
+     */
+    resourceMetadataUrl?: string;
+    /**
+     * Reject tokens that carry no `aud` claim at all. Default false: audience is
+     * enforced when present, and legacy audience-less tokens still work. Turn
+     * this on once every minted token is audience-bound.
+     */
+    requireAudience?: boolean;
+    /** Extra JWT verification options (clock tolerance, issuer pinning). */
+    verify?: Pick<VerifyClientJwtOptions, 'clockToleranceSec' | 'issuer'>;
+}
+/**
+ * The `auth` config for `createMcpHandler`, prewired for BuildBase-minted app
+ * tokens: HS256 verification with your secret, RFC 8707 audience binding,
+ * `sid` decryption to the BuildBase session, claim mapping to `McpAuthInfo`,
+ * and the derived RFC 9728 `resourceMetadataUrl`. Entirely local — the token
+ * and secret never leave this process.
+ */
+declare function buildbaseAuth(options: BuildBaseAuthOptions): {
+    verify: (token: string, req: McpHttpRequest) => Promise<McpAuthInfo | null>;
+    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 };