@buildbase/sdk 0.0.51 → 0.0.53

package/dist/index.d.ts

@@ -2186,8 +2186,9 @@ interface PermissionContext {
  * 3. settings.workspace.permissions[role] (org-level template)
  * 4. DEFAULT_ROLE_PERMISSIONS[role] (SDK built-in defaults)
  * 5. Merge in appPermissions (developer-defined) for the role
- * 6. If role not found → use defaultRole from settings, then 'member'
- * 7. Apply setting restrictions (canInviteMembers, canCreateWorkspace)
+ * 6. If role not found → use an explicitly-configured, known `defaultRole`;
+ *    otherwise deny (no silent 'member' fallback for unknown roles)
+ * 7. Apply setting restrictions (canInviteMembers)
  */
 declare function resolvePermissions(ctx: PermissionContext): Set<string>;
 /**
@@ -2222,6 +2223,652 @@ interface BetaFormResponse {
     message: string;
 }
 
+/**
+ * Type-safe translation keys for the BuildBase SDK.
+ * All user-facing strings are defined here.
+ */
+interface SDKMessages {
+    security: {
+        connectedAgentsTitle: string;
+        connectedAgentsDescription: string;
+        connectedAgentsDisconnect: string;
+        connectedAgentsEmpty: string;
+        connectedAgentsAccess: string;
+        connectedAgentsGranted: string;
+        inactive: string;
+        inactiveHint: string;
+        passkeysTitle: string;
+        passkeysDescription: string;
+        noPasskeys: string;
+        addHint: string;
+        rename: string;
+        remove: string;
+        removeTitle: string;
+        removeDescription: string;
+        renamePlaceholder: string;
+        lastUsed: string;
+        added: string;
+    };
+    settings: {
+        titles: {
+            profile: string;
+            security: string;
+            general: string;
+            users: string;
+            subscription: string;
+            usage: string;
+            credits: string;
+            features: string;
+            notifications: string;
+            permissions: string;
+            danger: string;
+        };
+        sidebar: {
+            account: string;
+            workspace: string;
+            profile: string;
+            security: string;
+            general: string;
+            users: string;
+            subscription: string;
+            usage: string;
+            credits: string;
+            features: string;
+            notifications: string;
+            permissions: string;
+            danger: string;
+        };
+        common: {
+            refresh: string;
+            refreshing: string;
+            retry: string;
+            retrying: string;
+            save: string;
+            saving: string;
+            cancel: string;
+            delete: string;
+            dismiss: string;
+            loading: string;
+            success: string;
+            error: string;
+            refreshAction: string;
+            retryAction: string;
+            noPermissionTitle: string;
+            noPermissionDescription: string;
+            billingManageOnly: string;
+            openSettings: string;
+            back: string;
+        };
+    };
+    subscription: {
+        managePlan: string;
+        changePlan: string;
+        viewPricingPlans: string;
+        viewPlans: string;
+        upgradePlan: string;
+        subscribe: string;
+        currentPlan: string;
+        noSubscription: string;
+        choosePlan: string;
+        choosePlanDescription: string;
+        forWorkspace: string;
+        planUpdateAvailable: string;
+        updateSuccess: string;
+        updateFailed: string;
+        cancelTitle: string;
+        cancelConfirm: string;
+        cancelKeep: string;
+        cancelButton: string;
+        canceling: string;
+        cancelSuccess: string;
+        cancelNotCharged: string;
+        cancelResumeAnytime: string;
+        cancelTrialTitle: string;
+        cancelTrialConfirm: string;
+        cancelTrialAccess: string;
+        cancelTrialNoCharge: string;
+        cancelTrialResume: string;
+        cancelTrialKeep: string;
+        cancelTrialButton: string;
+        resumeTitle: string;
+        resumeTrial: string;
+        resumeConfirm: string;
+        resumeKeep: string;
+        resumeButton: string;
+        resuming: string;
+        resumeSuccess: string;
+        managePayment: string;
+        openingPortal: string;
+        viewAllPlans: string;
+        scheduledCancellation: string;
+        scheduledTrialCancellation: string;
+        paymentPastDue: string;
+        paymentPastDueDescription: string;
+        subscriptionPaused: string;
+        subscriptionPausedDescription: string;
+        errorLoading: string;
+        errorLoadingDescription: string;
+        errorProcessing: string;
+        errorCanceling: string;
+        errorResuming: string;
+        invalidWorkspace: string;
+        billingInterval: {
+            monthly: string;
+            quarterly: string;
+            yearly: string;
+            perMonth: string;
+            perQuarter: string;
+            perYear: string;
+        };
+        seats: {
+            title: string;
+            members: string;
+            included: string;
+            billable: string;
+            perExtraSeat: string;
+            limit: string;
+            includedSeats: string;
+            maxSeats: string;
+            freeWithBase: string;
+            allIncluded: string;
+            extra: string;
+            unlimited: string;
+        };
+        items: {
+            features: string;
+            limits: string;
+            quotas: string;
+            credits: string;
+            creditsPerMonth: string;
+            creditsOneTime: string;
+            creditRenewal: string;
+            creditModeReset: string;
+            creditModeTopup: string;
+            creditModeLifetime: string;
+            /** @deprecated */
+            creditsPerPeriod: string;
+            /** @deprecated */
+            creditRollover: string;
+        };
+        checkout: {
+            upgrade: string;
+            downgrade: string;
+            switchTo: string;
+            select: string;
+        };
+        status: {
+            active: string;
+            canceling: string;
+            trial: string;
+            canceled: string;
+            pastDue: string;
+            paused: string;
+            deprecated: string;
+            unknown: string;
+        };
+        plan: string;
+        invoicesTab: string;
+        tabsLabel: string;
+        endsOn: string;
+        versionLabel: string;
+        changePlanButton: string;
+        noPlanAssigned: string;
+        free: string;
+        perSeatDisplay: string;
+        estTotalDisplay: string;
+        nextBillingDisplay: string;
+        membersInWorkspace: string;
+        billingInCurrency: string;
+        savingsPercent: string;
+        switchToInterval: string;
+        seatPriceDisplay: string;
+        trialEnded: string;
+        trialEndsIn: string;
+        onTrial: string;
+        upgradeToKeepAccess: string;
+        viewInvoices: string;
+        cancelTrial: string;
+        dunningFinal: string;
+        dunningSuspended: string;
+        dunningRecovery: string;
+        dunningSuspendedDescription: string;
+        dunningRecoveryDescription: string;
+        cancelEndDescription: string;
+        trialEndDescription: string;
+        cancelEndFallback: string;
+        resumeChargeDate: string;
+        resumeChargeFallback: string;
+        resumeContinue: string;
+        resumeCancelAnytime: string;
+        retainAccess: string;
+        retainAccessFallback: string;
+        noPlansAvailable: string;
+        noPlansAvailableHint: string;
+        startTrialDescription: string;
+        noSubscriptionDescription: string;
+        startFreeTrial: string;
+        startTrialDays: string;
+        trialBadge: string;
+    };
+    users: {
+        emailPlaceholder: string;
+        title: string;
+        adminOnly: string;
+        inviteByEmail: string;
+        inviteButton: string;
+        inviting: string;
+        inviteSuccess: string;
+        emailRequired: string;
+        invalidEmail: string;
+        inviteFailed: string;
+        seatLimitReached: string;
+        memberLimitReached: string;
+        role: string;
+        you: string;
+        owner: string;
+        noMembers: string;
+        extraSeatCost: string;
+        unknownUser: string;
+        seats: string;
+        members: string;
+        included: string;
+        perExtraSeat: string;
+        maxMembers: string;
+        available: string;
+        noMemberLimit: string;
+        seatHeading: string;
+        limitReached: string;
+        memberCount: string;
+        subscriptionRequired: string;
+        seatLimitMessage: string;
+        settingsLimitMessage: string;
+        memberLimitMessage: string;
+        selectRole: string;
+        inviteAs: string;
+    };
+    invoices: {
+        title: string;
+        description: string;
+        pay: string;
+        view: string;
+        viewDetails: string;
+        download: string;
+        errorLoading: string;
+        noInvoices: string;
+        noInvoicesWithSub: string;
+        paidAmount: string;
+        na: string;
+        status: {
+            draft: string;
+            open: string;
+            paid: string;
+            uncollectible: string;
+            void: string;
+        };
+    };
+    usage: {
+        title: string;
+        description: string;
+        totalResources: string;
+        overallUsage: string;
+        inOverage: string;
+        estOverageCost: string;
+        overageDetected: string;
+        overageDescription: string;
+        overageUnits: string;
+        rate: string;
+        billableBlocks: string;
+        estimatedCharge: string;
+        noData: string;
+        noDataHint: string;
+        used: string;
+        remaining: string;
+        overLimit: string;
+        percentUsed: string;
+        availableRemaining: string;
+        overLimitCount: string;
+        overageWarning: string;
+        fullyUsed: string;
+        renewingSoon: string;
+        almostFull: string;
+        overage: string;
+        errorLoading: string;
+        perUnit: string;
+        perUnits: string;
+        rateDisplay: string;
+        resourcesExceeded: string;
+        estOverageCharges: string;
+        overageRateDisplay: string;
+        resetDateDisplay: string;
+        daysRemainingDisplay: string;
+    };
+    profile: {
+        email: string;
+        name: string;
+        language: string;
+        country: string;
+        currency: string;
+        timezone: string;
+        profileImage: string;
+        success: string;
+        nameMinLength: string;
+        save: string;
+        reset: string;
+    };
+    general: {
+        ownerOnly: string;
+        name: string;
+        namePlaceholder: string;
+        nameMinLength: string;
+        billingCurrency: string;
+        icon: string;
+        iconDescription: string;
+        imageUrl: string;
+        imageUrlPlaceholder: string;
+        imageUrlDescription: string;
+        previewLabel: string;
+        previewImageAlt: string;
+        success: string;
+        chooseEmoji: string;
+        customImageUrl: string;
+        updateWorkspace: string;
+    };
+    features: {
+        title: string;
+        ownerOnly: string;
+        noFeatures: string;
+        enabled: string;
+        disabled: string;
+        enabling: string;
+        disabling: string;
+        featureSuccess: string;
+        updateSuccess: string;
+        actionStatus: string;
+    };
+    danger: {
+        title: string;
+        adminOnly: string;
+        deleteWorkspace: string;
+        deleteConfirm: string;
+        deleteWarning: string;
+        deleting: string;
+        deleteDescription: string;
+        deleteConfirmDescription: string;
+        failedToDelete: string;
+    };
+    notifications: {
+        title: string;
+        permissionDenied: string;
+        notSupported: string;
+        manageDescription: string;
+        blocked: string;
+        blockedDescription: string;
+        pushTitle: string;
+        pushEnabledDescription: string;
+        pushDisabledDescription: string;
+        enabling: string;
+        disabling: string;
+        enable: string;
+        disable: string;
+        toggleAction: string;
+        pushDescription: string;
+        deviceNote: string;
+        prefsSaved: string;
+        loadingPrefs: string;
+        categories: {
+            workspace: string;
+            billing: string;
+        };
+        events: {
+            workspace_invite: string;
+            workspace_invite_desc: string;
+            workspace_removed: string;
+            workspace_removed_desc: string;
+            workspace_role_changed: string;
+            workspace_role_changed_desc: string;
+            subscription_created: string;
+            subscription_created_desc: string;
+            subscription_upgraded: string;
+            subscription_upgraded_desc: string;
+            subscription_canceled: string;
+            subscription_canceled_desc: string;
+            subscription_suspended: string;
+            subscription_suspended_desc: string;
+            trial_ending: string;
+            trial_ending_desc: string;
+            trial_expired: string;
+            trial_expired_desc: string;
+            payment_failed: string;
+            payment_failed_desc: string;
+            payment_action_required: string;
+            payment_action_required_desc: string;
+            payment_succeeded: string;
+            payment_succeeded_desc: string;
+        };
+        unblock: {
+            firefox: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+            safari: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+            edge: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+            chrome: {
+                step1: string;
+                step2: string;
+                step3: string;
+                step4: string;
+            };
+        };
+    };
+    quota: {
+        includedOnly: string;
+        includedWithOverage: string;
+        includedHardLimit: string;
+        unitFallback: string;
+    };
+    pricing: {
+        title: string;
+        description: string;
+        currency: string;
+        billingIn: string;
+        noPlansCurrency: string;
+        noPlansCurrencyHint: string;
+        noPlans: string;
+        free: string;
+        included: string;
+        save: string;
+        current: string;
+        processing: string;
+        unavailable: string;
+        selectCurrency: string;
+        billingInterval: string;
+    };
+    beta: {
+        logoAlt: string;
+        nameLabel: string;
+        emailLabel: string;
+        submitText: string;
+        submittingText: string;
+        errorMessage: string;
+        tryAgain: string;
+        privacyConsent: string;
+        privacyPolicy: string;
+        and: string;
+        termsOfService: string;
+    };
+    workspace: {
+        switchTitle: string;
+        switchDescription: string;
+        notLoggedIn: string;
+        availableWorkspaces: string;
+        loadingWorkspaces: string;
+        searchPlaceholder: string;
+        noWorkspacesFound: string;
+        noWorkspacesAvailable: string;
+        switchTo: string;
+        membersCount: string;
+        createNew: string;
+        createTitle: string;
+        createDescription: string;
+        workspaceName: string;
+        workspaceNamePlaceholder: string;
+        workspaceNameMinLength: string;
+        workspaceIcon: string;
+        iconDescription: string;
+        chooseEmoji: string;
+        customImageUrl: string;
+        imageUrl: string;
+        imageUrlPlaceholder: string;
+        imageUrlDescription: string;
+        invalidUrl: string;
+        creating: string;
+        createWorkspace: string;
+    };
+    dropdowns: {
+        search: string;
+        chooseOption: string;
+        chooseCountry: string;
+        searchCountry: string;
+        chooseLanguage: string;
+        searchLanguage: string;
+        chooseCurrency: string;
+        searchCurrency: string;
+        chooseTimezone: string;
+        searchTimezone: string;
+        noResults: string;
+    };
+    push: {
+        failedToSubscribe: string;
+        failedToUnsubscribe: string;
+    };
+    permissions: {
+        title: string;
+        description: string;
+        ownerOnly: string;
+        save: string;
+        saving: string;
+        saveSuccess: string;
+    };
+    credits: {
+        title: string;
+        description: string;
+        balance: string;
+        available: string;
+        totalGranted: string;
+        totalConsumed: string;
+        totalExpired: string;
+        noCredits: string;
+        noCreditsHint: string;
+        buyCredits: string;
+        buyAmount: string;
+        purchasing: string;
+        packages: string;
+        noPackages: string;
+        creditsAmount: string;
+        validityDays: string;
+        validityUnlimited: string;
+        transactions: string;
+        noTransactions: string;
+        loadMore: string;
+        viewAll: string;
+        expiringSoon: string;
+        expiringInDays: string;
+        noExpiring: string;
+        type: {
+            plan_grant: string;
+            pack_purchased: string;
+            consumed: string;
+            expired: string;
+            admin_grant: string;
+            admin_revoke: string;
+            refund: string;
+        };
+        dialogTitle: string;
+        dialogDescription: string;
+        dialogDescriptionWorkspace: string;
+        perCredit: string;
+        purchaseSuccess: string;
+        purchaseCanceled: string;
+        purchaseFailed: string;
+        errorLoading: string;
+        insufficientCredits: string;
+    };
+    loading: {
+        restoringSession: string;
+        redirecting: string;
+        signingIn: string;
+        verifyingAccount: string;
+        almostThere: string;
+    };
+    errors: {
+        networkError: string;
+        unauthorized: string;
+        notFound: string;
+        generic: string;
+        fetchPlans: string;
+        fetchPlanGroup: string;
+        fetchPlanGroupVersion: string;
+        fetchPlanGroupVersions: string;
+        fetchSubscription: string;
+        createCheckout: string;
+        updateSubscription: string;
+        fetchInvoices: string;
+        fetchInvoice: string;
+        openBillingPortal: string;
+        cancelSubscription: string;
+        resumeSubscription: string;
+        recordUsage: string;
+        fetchQuotaUsage: string;
+        fetchAllQuotaUsage: string;
+        fetchUsageLogs: string;
+        fetchCreditBalance: string;
+        consumeCredits: string;
+        purchaseCredits: string;
+        fetchCreditPackages: string;
+        fetchCreditTransactions: string;
+        fetchExpiringCredits: string;
+    };
+}
+/**
+ * Generates a union of all valid dot-separated key paths from SDKMessages.
+ * Supports up to 4 levels of nesting (covers all current keys, e.g.
+ * "notifications.unblock.firefox.step1").
+ * Used to make `t()` calls compile-time safe with autocomplete.
+ *
+ * @example
+ * TranslationKey → "settings.titles.profile" | "settings.common.refresh" | ...
+ */
+type Level1 = keyof SDKMessages & string;
+type Level2 = {
+    [K1 in Level1]: SDKMessages[K1] extends Record<string, unknown> ? `${K1}.${keyof SDKMessages[K1] & string}` : never;
+}[Level1];
+type Level3 = {
+    [K1 in Level1]: SDKMessages[K1] extends Record<string, unknown> ? {
+        [K2 in keyof SDKMessages[K1] & string]: SDKMessages[K1][K2] extends Record<string, unknown> ? `${K1}.${K2}.${keyof SDKMessages[K1][K2] & string}` : never;
+    }[keyof SDKMessages[K1] & string] : never;
+}[Level1];
+type Level4 = {
+    [K1 in Level1]: SDKMessages[K1] extends Record<string, unknown> ? {
+        [K2 in keyof SDKMessages[K1] & string]: SDKMessages[K1][K2] extends Record<string, unknown> ? {
+            [K3 in keyof SDKMessages[K1][K2] & string]: SDKMessages[K1][K2][K3] extends Record<string, unknown> ? `${K1}.${K2}.${K3}.${keyof SDKMessages[K1][K2][K3] & string}` : never;
+        }[keyof SDKMessages[K1][K2] & string] : never;
+    }[keyof SDKMessages[K1] & string] : never;
+}[Level1];
+/** Union of all valid translation key paths (e.g. "settings.titles.profile") */
+type TranslationKey = Level2 | Level3 | Level4;
+
 /**
  * Verify that a webhook request came from BuildBase.
  *
@@ -2332,34 +2979,31 @@ declare function parseWebhookEvent(options: {
  * @example Next.js App Router — the entire integration:
  * ```ts
  * // lib/agent-ready.ts
- * import type { AgentReadyConfig } from "@buildbase/sdk";
+ * import { resolveAgentPath, type AgentReadyConfig } from "@buildbase/sdk";
  * export const agentConfig: AgentReadyConfig = {
  *   serverUrl: process.env.BUILDBASE_URL!,
  *   orgId: process.env.BUILDBASE_ORG_ID!,
  *   siteUrl: "https://imejis.io",
  *   site: { name: "Imejis", description: "Generate images from templates via API." },
+ *   robots: { contentSignals: { search: true, aiInput: true, aiTrain: false } },
  * };
- *
- * // app/.well-known/[...path]/route.ts
- * import { resolveWellKnown } from "@buildbase/sdk";
- * import { agentConfig } from "@/lib/agent-ready";
- * export async function GET(req: Request) {
- *   const doc = await resolveWellKnown(new URL(req.url).pathname, agentConfig);
+ * export async function serveAgentPath(req: Request): Promise<Response> {
+ *   const doc = await resolveAgentPath(new URL(req.url).pathname, agentConfig);
  *   if (!doc) return new Response('{"error":"not_found"}', { status: 404 });
  *   return new Response(doc.body, {
  *     status: doc.status,
- *     headers: { "Content-Type": doc.contentType, "Cache-Control": doc.cacheControl },
+ *     headers: {
+ *       "Content-Type": doc.contentType,
+ *       "Cache-Control": doc.cacheControl,
+ *       ...(doc.vary ? { Vary: doc.vary } : {}),
+ *     },
  *   });
  * }
  *
- * // app/llms.txt/route.ts
- * import { buildLlmsTxt, fetchAgentReadiness } from "@buildbase/sdk";
- * import { agentConfig } from "@/lib/agent-ready";
- * export async function GET() {
- *   const doc = buildLlmsTxt(agentConfig, await fetchAgentReadiness(agentConfig));
- *   if (!doc) return new Response("Not found", { status: 404 });
- *   return new Response(doc.body, { headers: { "Content-Type": doc.contentType } });
- * }
+ * // app/.well-known/[...path]/route.ts — plus identical two-liners at
+ * // app/robots.txt/route.ts, app/llms.txt/route.ts, app/auth.md/route.ts, …
+ * import { serveAgentPath } from "@/lib/agent-ready";
+ * export const GET = serveAgentPath;
  * ```
  */
 /**
@@ -2370,21 +3014,16 @@ declare function parseWebhookEvent(options: {
 interface AgentReadinessBundle {
     /** False when the org has not enabled agent readiness — everything else absent. */
     enabled: boolean;
-    /** Pointer to the org's RFC 8414 authorization-server metadata. */
+    /**
+     * Pointer to the org's RFC 8414 authorization-server metadata. This is the
+     * ONLY thing the platform owns and serves — discovery content (protected
+     * resources, llms.txt, sitemap, API catalog, skills) is app-owned and
+     * defined locally in {@link AgentReadyConfig}.
+     */
     authorizationServer?: {
         issuer: string;
         metadataUrl: string;
     };
-    /**
-     * RFC 9728 protected-resource metadata objects, ready to serve. Each `metadata`
-     * is a complete document; `resource` is the canonical resource URI it describes.
-     */
-    protectedResources?: Array<{
-        resource: string;
-        metadata: Record<string, unknown>;
-    }>;
-    /** Org-authored llms.txt content, or null when unset. */
-    llmsTxt?: string | null;
 }
 /** An Agent Skill (Agent Skills Discovery RFC v0.2.0) published by this app. */
 interface AgentSkill {
@@ -2432,6 +3071,59 @@ interface McpServerCard {
     /** Documentation URL. */
     documentationUrl?: string;
 }
+/** 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). */
@@ -2484,8 +3176,46 @@ interface AgentReadyConfig {
      * `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;
+    /** 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;
 }
@@ -2495,7 +3225,15 @@ interface DiscoveryDocument {
     contentType: string;
     body: string;
     cacheControl: string;
+    /** Value for a `Vary` response header, when the body is negotiated. */
+    vary?: string;
 }
+/**
+ * User-agent strings of the known AI crawlers/agents that agent-readiness
+ * checkers look for in robots.txt (`buildRobotsTxt` emits a policy group per
+ * entry when `robots.aiBots` is `'allow'`/`'deny'`).
+ */
+declare const AI_BOT_USER_AGENTS: readonly string[];
 /**
  * SHA-256 of `content` as `sha256:<hex>`, via the shared pure-JS hash (no Web
  * Crypto / Node `crypto`), so output is identical on every runtime.
@@ -2509,7 +3247,7 @@ declare function sha256Digest(content: string): string;
  * simply see the app as not (yet) agent-ready.
  */
 declare function fetchAgentReadiness(config: AgentReadyConfig): Promise<AgentReadinessBundle>;
-/** Clear the in-memory agent-readiness cache (mainly for tests). */
+/** Clear the in-memory agent-readiness caches (mainly for tests). */
 declare function clearAgentReadinessCache(): void;
 /**
  * The Agent Card served at `/.well-known/agent.json`. A stable, machine-readable
@@ -2519,16 +3257,24 @@ declare function buildAgentCard(config: AgentReadyConfig, bundle: AgentReadiness
 /**
  * Resolve the RFC 9728 protected-resource metadata for a request path, or null
  * if no configured resource maps to it.
+ *
+ * App-owned and local: built entirely from `config.protectedResources`, with
+ * `authorization_servers` derived from `serverUrl`/`orgId` (the BuildBase
+ * issuer). No platform round-trip.
  */
-declare function buildProtectedResourceMetadata(requestPath: string, config: AgentReadyConfig, bundle: AgentReadinessBundle): DiscoveryDocument | null;
+declare function buildProtectedResourceMetadata(requestPath: string, config: AgentReadyConfig): DiscoveryDocument | null;
 /** Agent Skills discovery index (Agent Skills Discovery RFC v0.2.0). */
 declare function buildAgentSkillsIndex(config: AgentReadyConfig): DiscoveryDocument | null;
 /** Serve a single skill's SKILL.md by request path, or null if none matches. */
 declare function buildSkillMd(requestPath: string, config: AgentReadyConfig): DiscoveryDocument | null;
 /** security.txt (RFC 9116), or null when not configured. */
 declare function buildSecurityTxt(config: AgentReadyConfig): DiscoveryDocument | null;
-/** The org-authored llms.txt, or null when the org hasn't set one. */
-declare function buildLlmsTxt(config: AgentReadyConfig, bundle: AgentReadinessBundle): DiscoveryDocument | null;
+/**
+ * The `/llms.txt` document from `config.llmsTxt` (app-authored). Returns null
+ * when not set — serve your own static file instead. llms.txt is app content,
+ * not platform-managed.
+ */
+declare function buildLlmsTxt(config: AgentReadyConfig): DiscoveryDocument | null;
 /**
  * API Catalog (RFC 9727) as a `linkset+json` document for
  * `/.well-known/api-catalog`. Returns null when no APIs are configured.
@@ -2546,6 +3292,42 @@ declare function buildMcpServerCard(config: AgentReadyConfig): DiscoveryDocument
  * there is nothing to describe (no authorizationServer and no override).
  */
 declare function buildAuthMd(config: AgentReadyConfig, bundle: AgentReadinessBundle): DiscoveryDocument | null;
+/**
+ * robots.txt with AI-bot policy groups, Content Signals, and sitemap
+ * references. Always returns a document — with no `config.robots` it emits an
+ * allow-all default policy plus an explicit `Allow: /` group per known AI bot.
+ */
+declare function buildRobotsTxt(config: AgentReadyConfig): DiscoveryDocument;
+/**
+ * A minimal sitemap.xml from `config.sitemap.urls`, or null when not
+ * configured. Meant for API-first apps that would otherwise have no sitemap —
+ * apps with real content pipelines (e.g. next-sitemap) should keep those and
+ * omit `config.sitemap`.
+ */
+declare function buildSitemap(config: AgentReadyConfig): DiscoveryDocument | null;
+/**
+ * True when an `Accept` header prefers markdown (`text/markdown` /
+ * `text/x-markdown`) over `text/html` — q-value aware, so
+ * `text/html;q=0.5, text/markdown` is markdown but `text/markdown;q=0.1,
+ * text/html` is not. A bare wildcard does not count as a markdown preference.
+ */
+declare function wantsMarkdown(acceptHeader: string | null | undefined): boolean;
+/**
+ * Markdown content negotiation: pick the markdown or HTML variant of a page
+ * per the `Accept` header. The returned document carries `vary: 'Accept'` —
+ * forward it so caches key on the header.
+ */
+declare function negotiateMarkdown(acceptHeader: string | null | undefined, variants: {
+    html: string;
+    markdown: string;
+}, config?: Pick<AgentReadyConfig, 'cacheTtlSeconds'>): DiscoveryDocument;
+/**
+ * Value for a `Link` response header advertising this app's discovery
+ * documents (llms.txt, Agent Card, and — when configured — sitemap, API
+ * catalog, MCP server card). Sync and pure (no platform fetch), so it's safe
+ * in edge middleware.
+ */
+declare function buildDiscoveryLinkHeader(config: AgentReadyConfig): string;
 /**
  * Resolve any `.well-known` request path to its discovery document, or null if
  * this app serves nothing there (caller should 404).
@@ -2554,10 +3336,18 @@ declare function buildAuthMd(config: AgentReadyConfig, bundle: AgentReadinessBun
  * oauth-authorization-server (pointer), agent-skills index + SKILL.md,
  * security.txt, api-catalog (RFC 9727), and the MCP server card.
  *
- * Root-level docs are served via their own builders (they aren't under
- * `.well-known`): `buildLlmsTxt` for `/llms.txt` and `buildAuthMd` for `/auth.md`.
+ * Root-level docs (`/robots.txt`, `/llms.txt`, `/auth.md`, …) are not handled
+ * here — use {@link resolveAgentPath}, which covers both, for new wiring.
  */
 declare function resolveWellKnown(requestPath: string, config: AgentReadyConfig): Promise<DiscoveryDocument | null>;
+/**
+ * Superset of {@link resolveWellKnown}: resolves ANY agent-facing path — the
+ * root-level documents (`/robots.txt`, `/sitemap.xml`, `/llms.txt`,
+ * `/auth.md`, `/security.txt`) plus everything under `/.well-known/*`. One
+ * catch-all (or middleware) wired to this function covers the app's entire
+ * agent-readiness surface. Returns null for paths this app doesn't serve.
+ */
+declare function resolveAgentPath(requestPath: string, config: AgentReadyConfig): Promise<DiscoveryDocument | null>;
 /** A WebMCP tool definition exposed to in-page agents via `navigator.modelContext`. */
 interface WebMcpTool {
     name: string;
@@ -2644,6 +3434,13 @@ interface AppTokenRequestClaims {
     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;
 }
 /** The payload BuildBase sends to `applicationRevokeUrl`. */
@@ -2653,14 +3450,43 @@ interface AppRevokeRequestClaims {
     reason: 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, and `exp`/`nbf`.
+ * 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, clockToleranceSec?: number): Record<string, any>;
+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;
 interface VerifyOptions {
     /** The `Authorization` header value from the incoming request. */
     authorization: string | null | undefined;
@@ -2735,20 +3561,6 @@ declare function handleAppRevokeRequest(options: {
     success: boolean;
     message?: string;
 }>>;
-/**
- * Build the 401 an agent should receive when it calls your protected API without
- * a valid token. The `WWW-Authenticate: Bearer resource_metadata=...` header
- * points the agent at your `/.well-known/oauth-protected-resource` document,
- * bootstrapping the OAuth discovery flow (RFC 9728 §5.1, RFC 6750 §3).
- *
- * @example
- * ```ts
- * if (!isValid(token)) {
- *   const c = bearerChallenge({ resourceMetadataUrl: "https://imejis.io/.well-known/oauth-protected-resource" });
- *   res.writeHead(c.status, c.headers).end(c.body);
- * }
- * ```
- */
 declare function bearerChallenge(options: {
     resourceMetadataUrl: string;
     error?: 'invalid_token' | 'insufficient_scope' | string;
@@ -3043,5 +3855,5 @@ interface BuildBaseResult extends ScopedActions {
 }
 declare function BuildBase(config: BuildBaseConfig): BuildBaseResult;
 
-export { ApiVersion, AppBridgeError, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, BuildBase, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditBucketSource, CreditBucketStatus, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, appTokenFailure, appTokenSuccess, bearerChallenge, buildAgentCard, buildAgentSkillsIndex, buildApiCatalog, buildAuthMd, buildLlmsTxt, buildMcpServerCard, buildProtectedResourceMetadata, buildSecurityTxt, buildSkillMd, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAgentReadinessCache, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, BuildBase as default, eventEmitter, extractBearerToken, fetchAgentReadiness, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, handleAppRevokeRequest, handleAppTokenRequest, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, parseWebhookEvent, provideWebMcpTools, readBBParams, resolveMaxUsers, resolvePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature };
-export type { AgentReadinessBundle, AgentReadyConfig, AgentSkill, ApiCatalogApi, AppRevokeRequestClaims, AppTokenRequestClaims, AppTokenResponseBody, AppTokenResult, BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, CreditActions, CreditBucketSourceType, CreditBucketStatusType, CreditTransactionTypeValue, DiscoveryDocument, DunningStateType, EventData, EventType, FeatureActions, FormatQuotaWithPriceOptions, GetCheckoutStripeParams, HandlerResult, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IConsumeCreditsRequest, IConsumeCreditsResponse, ICreditBalance, ICreditBucket, ICreditBucketsQuery, ICreditBucketsResponse, ICreditPackage, ICreditPackagePricingVariant, ICreditPurchaseRequest, ICreditPurchaseResponse, ICreditTransaction, ICreditTransactionsQuery, ICreditTransactionsResponse, IEventCallbacks, IExpiringCreditsResponse, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicCreditPackage, IPublicCreditPackagesResponse, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RolePermissionMap, ScopedActions, SettingsActions, SubscriptionActions, SubscriptionItemTypeValue, SubscriptionStatusType, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WebMcpTool, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { AI_BOT_USER_AGENTS, ApiVersion, AppBridgeError, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, BuildBase, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditBucketSource, CreditBucketStatus, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, appTokenFailure, appTokenSuccess, bearerChallenge, buildAgentCard, buildAgentSkillsIndex, buildApiCatalog, buildAuthMd, buildDiscoveryLinkHeader, buildLlmsTxt, buildMcpServerCard, buildProtectedResourceMetadata, buildRobotsTxt, buildSecurityTxt, buildSitemap, buildSkillMd, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAgentReadinessCache, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, BuildBase as default, eventEmitter, extractBearerToken, fetchAgentReadiness, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, handleAppRevokeRequest, handleAppTokenRequest, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, negotiateMarkdown, parseWebhookEvent, provideWebMcpTools, readBBParams, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown };
+export type { AgentReadinessBundle, AgentReadyConfig, AgentSkill, ApiCatalogApi, AppRevokeRequestClaims, AppTokenRequestClaims, AppTokenResponseBody, AppTokenResult, BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, ContentSignals, CreditActions, CreditBucketSourceType, CreditBucketStatusType, CreditTransactionTypeValue, DiscoveryDocument, DunningStateType, EventData, EventType, FeatureActions, FormatQuotaWithPriceOptions, GetCheckoutStripeParams, HandlerResult, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IConsumeCreditsRequest, IConsumeCreditsResponse, ICreditBalance, ICreditBucket, ICreditBucketsQuery, ICreditBucketsResponse, ICreditPackage, ICreditPackagePricingVariant, ICreditPurchaseRequest, ICreditPurchaseResponse, ICreditTransaction, ICreditTransactionsQuery, ICreditTransactionsResponse, IEventCallbacks, IExpiringCreditsResponse, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicCreditPackage, IPublicCreditPackagesResponse, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, ISettings, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, IUser, IWorkspace, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RobotsConfig, RobotsPolicy, RolePermissionMap, ScopedActions, SettingsActions, SitemapUrl, SubscriptionActions, SubscriptionItemTypeValue, SubscriptionStatusType, TranslationKey, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WebMcpTool, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };