@buildbase/sdk 0.0.50 → 0.0.53

package/dist/mcp/index.d.ts

@@ -0,0 +1,1402 @@
+import { z } from 'zod';
+
+/** MCP Server Card (SEP-1649 / SEP-2127), 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;
+    /** Capabilities object, e.g. `{ tools: {}, resources: {} }`. */
+    capabilities?: Record<string, unknown>;
+    /** Optional human description. */
+    description?: string;
+    /** Documentation URL. */
+    documentationUrl?: 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[];
+    /**
+     * 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);
+}
+/** 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.
+ *
+ * The third argument accepts either the legacy `clockToleranceSec` number or a
+ * {@link VerifyClientJwtOptions} object.
+ */
+declare function verifyClientJwt(token: string, clientSecret: string, optionsOrTolerance?: number | 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;
+};
+
+export { AppBridgeError, bearerChallenge, builtinMcpTools, createMcpHandler, defineMcpTool, extractBearerToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
+export type { BuiltinMcpToolName, CreateMcpHandlerConfig, McpAuthInfo, McpBuildBaseClient, McpHandler, McpHttpRequest, McpHttpResponse, McpServerCard, McpToolAnnotations, McpToolContext, McpToolDefinition, ScopedActions };