@buildbase/sdk 0.0.82 → 0.0.84

package/dist/index.d.ts

@@ -6,6 +6,18 @@ interface IDocument {
     updatedAt: string;
     deleted: boolean;
 }
+/**
+ * The data-residency region an organisation's tenant stack runs in.
+ *
+ * `us` is the default cell, served worldwide from a global edge with US data
+ * residency; `eu` is the cell that exists so that EU customer data stays in
+ * the EU. The value is informational on the client: what actually decides
+ * which cell answers a request is the `serverUrl` the client was given, and
+ * on the server the audience the token is bound to. A client that sends an
+ * EU organisation's request to the default cell gets a 421 telling it where
+ * to go, not a silent cross-region read.
+ */
+type Region = 'us' | 'eu';
 interface IUser extends IDocument {
     _id: string;
     name: string;
@@ -1119,6 +1131,16 @@ interface ISettings {
         /** Auto-create workspace on first login */
         autoCreateFirst: boolean;
     };
+    /**
+     * What the organization lets its users upload (`useUpload`): whether they
+     * may, and how large one file may be. Absent on a server from before
+     * end-user uploads, which has no route to take them: `useUpload` then
+     * reports uploads off.
+     */
+    uploads?: {
+        enabled: boolean;
+        maxFileBytes: number;
+    };
     [key: string]: unknown;
 }
 
@@ -1132,6 +1154,13 @@ interface IOsConfig {
     serverUrl: string;
     version: ApiVersion;
     orgId: string;
+    /**
+     * The organisation's data-residency region, for UI badges and support
+     * tooling. Informational: `serverUrl` is what decides which cell answers,
+     * so a wrong value mislabels a badge and cannot misroute a request.
+     * Undefined until the app passes it.
+     */
+    region?: Region;
 }
 /** Lifecycle of the one-time org-settings fetch. */
 type SettingsStatus = 'idle' | 'loading' | 'loaded' | 'error';
@@ -1264,6 +1293,17 @@ declare abstract class BaseApi {
      * Gets the same timeout, retry, header-merge, and error-callback handling as fetchResponse.
      */
     protected fetchAbsoluteUrl(absoluteUrl: string, init?: RequestInit): Promise<Response>;
+    /**
+     * A request to a URL that is not ours - a signed storage URL, say. Sent with
+     * the configured fetch and nothing else: no session, no custom headers, no
+     * retries, because a signed URL must carry exactly the headers its
+     * signature covers and must not learn the session.
+     *
+     * Bound to `globalThis` like every other call here: a browser's (and a
+     * Worker's) `fetch` throws "Illegal invocation" when called as a method of
+     * this object.
+     */
+    protected fetchForeign(absoluteUrl: string, init?: RequestInit): Promise<Response>;
     /**
      * Throw an error from a failed response.
      * Tries to parse JSON error body; falls back to status-based message.
@@ -1706,6 +1746,86 @@ declare class SettingsApi extends BaseApi {
     getSettings(signal?: AbortSignal): Promise<ISettings>;
 }
 
+/**
+ * API client for files the signed-in user uploads: a workspace's image, a
+ * profile picture. Session-authed, like every `/public` route.
+ *
+ * Three steps, the same as BuildBase's own console: an intent the server
+ * checks before a byte moves (type, size, the organization's storage), a PUT
+ * of the file straight to storage on the signed URL it answers, and a
+ * complete that checks what landed and answers the stored file. The file
+ * never passes through the API server, and it counts against the
+ * organization's storage from the moment it is stored.
+ */
+
+/** What an end user may upload for. */
+type UploadPurpose = 'workspace-image' | 'profile-image';
+/** Images only, as the server stores them. */
+declare const UPLOAD_ACCEPT = "image/png,image/jpeg,image/gif,image/webp,image/svg+xml";
+/**
+ * The most one end-user file may ever be. The organization can set less, or
+ * turn uploads off: `useUpload` reads both from its settings.
+ */
+declare const UPLOAD_MAX_BYTES: number;
+/** A stored file. `url` is public: it is meant to be shown. */
+interface IUploadedFile {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    url: string;
+    width: number;
+    height: number;
+}
+interface UploadOptions {
+    purpose: UploadPurpose;
+    signal?: AbortSignal;
+}
+/**
+ * Why an upload did not go through, in terms a screen can translate. The
+ * server's own sentence is English; its `status` and `code` are not.
+ */
+type UploadFailure = 'tooLarge' | 'invalid' | 'disabled' | 'userLimit' | 'unavailable' | 'failed';
+declare function uploadFailureOf(error: unknown): UploadFailure;
+/**
+ * What the organization lets its users upload, as its public settings say
+ * (`settings.uploads`). A server that does not say has no end-user uploads
+ * (the platform sends `uploads` with the route that takes them), and neither
+ * do settings still loading: uploads are off until the server says otherwise,
+ * so an app never offers an upload that cannot succeed.
+ */
+interface UploadPolicy {
+    enabled: boolean;
+    maxFileBytes: number;
+}
+declare function uploadPolicyOf(settings: unknown): UploadPolicy;
+/**
+ * Why a file cannot be uploaded, known before a byte is sent: uploads are
+ * off, or the file is over the organization's limit. Null when it may go.
+ */
+declare function preflightUpload(file: {
+    size: number;
+}, policy: UploadPolicy): UploadFailure | null;
+/** A byte limit as a person reads it, in their locale: "5 MB", "200 kB". */
+declare function formatUploadLimit(bytes: number, locale?: string): string;
+declare class UploadsApi extends BaseApi {
+    constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'> & {
+        sessionId?: string;
+    });
+    /**
+     * Upload one image and answer the stored file. A refusal throws the
+     * server's own sentence with its `status` and `code` - 413
+     * `UPLOAD_TOO_LARGE` for a file over the organization's limit, 403
+     * `UPLOADS_DISABLED` or `USER_UPLOAD_LIMIT`, 429 for too many uploads, 503
+     * `UPLOADS_UNAVAILABLE` when the organization cannot take files right now,
+     * 501 when this server has no direct uploads. `uploadFailureOf` turns any
+     * of them into a reason a screen can translate.
+     */
+    upload(file: Blob & {
+        name?: string;
+    }, options: UploadOptions): Promise<IUploadedFile>;
+}
+
 /**
  * API client for user attributes and features.
  * Extends BaseApi for shared URL/auth/request handling.
@@ -2896,19 +3016,21 @@ declare function appPermissionCatalogue(settings?: SettingsLike | null, appPermi
 
 /**
  * Push notification service worker source code.
- * Export this string and write it to a file in your app's `public/` directory.
+ * Write this string to your app's `public/` directory in a prebuild step, so
+ * the worker updates whenever the SDK does.
  *
  * @example
  * ```ts
- * // scripts/generate-sw.ts
+ * // scripts/write-push-sw.mjs, run as "prebuild" in package.json
  * import { PUSH_SERVICE_WORKER_SCRIPT } from '@buildbase/sdk';
  * import fs from 'fs';
  * fs.writeFileSync('public/push-sw.js', PUSH_SERVICE_WORKER_SCRIPT);
  * ```
  *
- * Or manually create `public/push-sw.js` with this content.
+ * Do not paste a copy into `public/` by hand: a copy never picks up the
+ * fixes a later SDK release makes to the worker.
  */
-declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n  if (!event.data) return;\n\n  try {\n    const payload = event.data.json();\n    // i18n exception: service workers run outside the SDK's translation\n    // provider, so this last-resort fallback stays English. The server should\n    // always send a localized payload.title.\n    const title = payload.title || 'Notification';\n    const options = {\n      body: payload.body || '',\n      icon: payload.icon || undefined,\n      badge: payload.icon || undefined,\n      data: { url: payload.url, ...(payload.data || {}) },\n      tag: 'buildbase-push-' + Date.now(),\n    };\n\n    event.waitUntil(\n      self.registration.showNotification(title, options)\n    );\n  } catch (e) {\n    console.error('[PushSW] Failed to show notification:', e);\n  }\n});\n\nself.addEventListener('notificationclick', function(event) {\n  event.notification.close();\n\n  const url = event.notification.data && event.notification.data.url;\n  if (url) {\n    event.waitUntil(\n      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n        for (let i = 0; i < clientList.length; i++) {\n          const client = clientList[i];\n          if (client.url === url && 'focus' in client) {\n            return client.focus();\n          }\n        }\n        if (clients.openWindow) {\n          return clients.openWindow(url);\n        }\n      })\n    );\n  }\n});\n";
+declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n  if (!event.data) return;\n\n  let payload;\n  try {\n    payload = event.data.json();\n  } catch (e) {\n    console.error('[PushSW] Push payload is not JSON:', e);\n    return;\n  }\n  if (!payload || typeof payload !== 'object') return;\n\n  // i18n exception: service workers run outside the SDK's translation\n  // provider, so this last-resort fallback stays English. The server should\n  // always send a localized payload.title.\n  const title = payload.title || 'Notification';\n  // The tracked click URL (/api/push-track/link/...) wins over any url in\n  // payload.data, so a click is always counted.\n  const data = Object.assign({}, payload.data && typeof payload.data === 'object' ? payload.data : {});\n  if (payload.url) data.url = payload.url;\n  // A notification with the same tag replaces the earlier one instead of\n  // stacking. No tag means every notification is shown on its own.\n  const tag = payload.tag ? String(payload.tag) : undefined;\n  const actions = Array.isArray(payload.actions)\n    ? payload.actions.filter(function(a) {\n        return a && typeof a.action === 'string' && typeof a.title === 'string';\n      })\n    : undefined;\n\n  const options = {\n    body: payload.body || '',\n    icon: payload.icon || undefined,\n    badge: payload.badge || payload.icon || undefined,\n    image: payload.image || undefined,\n    tag: tag,\n    // The browser rejects renotify without a tag.\n    renotify: tag ? !!payload.renotify : false,\n    actions: actions && actions.length ? actions : undefined,\n    silent: !!payload.silent,\n    requireInteraction: !!payload.requireInteraction,\n    timestamp: typeof payload.timestamp === 'number' ? payload.timestamp : undefined,\n    dir: payload.dir === 'ltr' || payload.dir === 'rtl' ? payload.dir : 'auto',\n    data: data,\n  };\n\n  event.waitUntil(\n    Promise.resolve()\n      .then(function() {\n        return self.registration.showNotification(title, options);\n      })\n      .catch(function(e) {\n        // A field this browser refuses must not cost the user the\n        // notification: show it again with the basics only.\n        console.error('[PushSW] Failed to show notification, retrying without rich options:', e);\n        return self.registration.showNotification(title, {\n          body: options.body,\n          icon: options.icon,\n          tag: tag,\n          data: data,\n        });\n      })\n  );\n});\n\nself.addEventListener('notificationclick', function(event) {\n  event.notification.close();\n\n  // A click on an action button (event.action is its id) opens the same\n  // tracked URL as a click on the notification body.\n  const url = event.notification.data && event.notification.data.url;\n  if (url) {\n    event.waitUntil(\n      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n        for (let i = 0; i < clientList.length; i++) {\n          const client = clientList[i];\n          if (client.url === url && 'focus' in client) {\n            return client.focus();\n          }\n        }\n        if (clients.openWindow) {\n          return clients.openWindow(url);\n        }\n      })\n    );\n  }\n});\n";
 
 interface BetaFormData {
     name?: string;
@@ -3354,6 +3476,8 @@ interface SDKMessages {
         currency: string;
         timezone: string;
         profileImage: string;
+        changePicture: string;
+        removePicture: string;
         success: string;
         nameMinLength: string;
         save: string;
@@ -3375,8 +3499,22 @@ interface SDKMessages {
         success: string;
         chooseEmoji: string;
         customImageUrl: string;
+        uploadImage: string;
+        chooseImage: string;
         updateWorkspace: string;
     };
+    uploads: {
+        /** ICU: `{max}` is the organization's per-file limit, e.g. "5 MB". */
+        description: string;
+        uploading: string;
+        /** ICU: `{max}`. */
+        errorTooLarge: string;
+        errorInvalid: string;
+        errorDisabled: string;
+        errorUserLimit: string;
+        errorUnavailable: string;
+        errorFailed: string;
+    };
     features: {
         title: string;
         ownerOnly: string;
@@ -4271,6 +4409,13 @@ interface AgentReadyConfig {
     fetchTimeoutMs?: number;
     /** Injectable fetch, mainly for testing. Defaults to the global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Where the platform fetches are cached. Defaults to process memory, which is
+     * this module's long-standing behaviour. Pass a Redis, KV or Upstash-backed
+     * store so every replica shares one copy instead of each fetching its own.
+     * See `DiscoveryCacheStore`.
+     */
+    cache?: DiscoveryCacheStore;
 }
 /** A rendered discovery document ready to become an HTTP response. */
 interface DiscoveryDocument {
@@ -4292,6 +4437,35 @@ declare const AI_BOT_USER_AGENTS: readonly string[];
  * Crypto / Node `crypto`), so output is identical on every runtime.
  */
 declare function sha256Digest(content: string): string;
+/**
+ * Where the two platform fetches below keep what they fetched.
+ *
+ * The default is process memory, which is what this module has always used and
+ * is correct for one process. It is not wrong across replicas, only wasteful:
+ * every pod fetches the same bundle independently, each honours its own TTL,
+ * and `clearAgentReadinessCache()` clears the process it runs in and no other.
+ * Pass a store backed by Redis, Cloudflare KV or Upstash to share one copy, the
+ * same way `@buildbase/sdk/server`'s content client takes a `CacheStore`.
+ *
+ * Values are JSON strings, so a store needs nothing but string get and set.
+ * Every call is wrapped: a store that throws, or takes longer than
+ * `DISCOVERY_CACHE_TIMEOUT_MS` (500 ms), degrades to a cache miss (one extra
+ * platform fetch), never to a failed or hung discovery response.
+ */
+interface DiscoveryCacheStore {
+    /** The stored string, or `undefined` for a miss. */
+    get(key: string): Promise<string | undefined> | string | undefined;
+    /** Store `value` for at least `ttlSeconds`. */
+    set(key: string, value: string, ttlSeconds: number): Promise<void> | void;
+    /** Optional: drop one key. `clearAgentReadinessCache()` uses it when present. */
+    delete?(key: string): Promise<void> | void;
+}
+/**
+ * How long one store call may take before it counts as failed. A cache that
+ * answers slower than the platform is no cache; without a bound, a hung
+ * Redis would hang every discovery response with it.
+ */
+declare const DISCOVERY_CACHE_TIMEOUT_MS = 500;
 /**
  * Fetch (and cache) an org's agent-readiness bundle from the BuildBase server.
  *
@@ -4300,8 +4474,16 @@ 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 caches (mainly for tests). */
-declare function clearAgentReadinessCache(): void;
+/**
+ * Clear what this module cached.
+ *
+ * Always clears the built-in process-memory store (which is what tests want).
+ * When a custom `cache` store was used, it also deletes the keys this process
+ * wrote through it, if that store implements `delete`; keys written by another
+ * process are not enumerable through the interface, so a shared store stays
+ * the app's to invalidate.
+ */
+declare function clearAgentReadinessCache(store?: DiscoveryCacheStore): void;
 /**
  * The Agent Card served at `/.well-known/agent.json`. A stable, machine-readable
  * entry point advertising who this app is and where agents can discover more.
@@ -4705,6 +4887,16 @@ interface BuildBaseConfig {
     orgId: string;
     /** API version (default: 'v1') */
     version?: ApiVersion;
+    /**
+     * The region this client talks to, for logging, metrics and UI badges.
+     *
+     * Informational only. It is never sent on a request and never changes which
+     * cell answers: `serverUrl` decides that, and on the server the real guard
+     * is the audience the token is bound to (`buildbaseAuth({ resource })`).
+     * Setting it wrong mislabels a log line; it cannot route a request to the
+     * wrong region.
+     */
+    region?: Region;
     /**
      * Async callback to resolve the current session ID.
      * Called automatically before each authenticated API call.
@@ -5005,6 +5197,11 @@ interface ScopedActions {
     sessions: SessionActions;
 }
 interface BuildBaseResult extends ScopedActions {
+    /**
+     * The `region` passed in config, or `undefined` when it was not set.
+     * Informational: see `BuildBaseConfig.region`.
+     */
+    region?: Region;
     /**
      * Check authentication. Returns session or null.
      * Uses the `getSessionId` callback from config.
@@ -5048,6 +5245,7 @@ interface BuildBaseResult extends ScopedActions {
             push: PushApi;
             devices: DevicesApi;
             sessions: SessionsApi;
+            uploads: UploadsApi;
         };
     };
 }
@@ -5253,5 +5451,87 @@ declare function buildbaseAuth(options: BuildBaseAuthOptions): {
     resourceMetadataUrl?: string;
 };
 
-export { AI_BOT_USER_AGENTS, APP_PERMISSION_FALLBACK_GROUP, 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, FALLBACK_WORKSPACE_ROLE, INVITATION_ERROR_CODE, InvoiceStatuses, NotificationsApi, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WEBHOOK_EVENTS, WEBHOOK_EVENTS_BY_CATEGORY, WorkspaceApi, actionableInvitations, appPermissionCatalogue, appTokenFailure, appTokenSuccess, bearerChallenge, buildA2AAgentCard, buildAgentCard, buildAgentSkillsIndex, buildApiCatalog, buildAuthMd, buildDiscoveryLinkHeader, buildDnsAidRecords, buildLlmsFullTxt, buildLlmsTxt, buildMcpDiscoveryManifest, buildMcpServerCard, buildProtectedResourceMetadata, buildRobotsTxt, buildSecurityTxt, buildSitemap, buildSkillMd, buildWebBotAuthDirectory, buildbaseAuth, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAgentReadinessCache, clearAuthIntent, clearPendingInvite, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, createSessionRefCrypto, BuildBase as default, eventEmitter, extractBearerToken, fetchAgentReadiness, formatCents, formatMinorAmountIntl, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableBillingIntervals, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyDecimals, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, handleAppRevokeRequest, handleAppTokenRequest, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, inviterNameOf, isInvitationActionable, isInvitationError, isInvitationLapsed, isWebhookEvent, isZeroDecimalCurrency, minorAmountToDisplay, mintAgentToken, negotiateMarkdown, parkPendingInvite, parseWebhookEvent, pickDefaultRole, provideWebMcpTools, readBBParams, readPendingInvite, resendCooldownSeconds, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveRolePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, sortInvitations, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown, workspaceIdOf, workspaceNameOf };
-export type { A2ACardConfig, A2ACardSkill, AgentReadinessBundle, AgentReadyConfig, AgentSkill, ApiCatalogApi, AppRevokeRequestClaims, AppScope, AppTokenRequestClaims, AppTokenResponseBody, AppTokenResult, BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, BuildBaseAuthOptions, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, ContentSignals, CreditActions, CreditBucketSourceType, CreditBucketStatusType, CreditTransactionTypeValue, DiscoveryDocument, DnsAidRecord, 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, INotificationItem, 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, IWorkspaceInvitation, IWorkspaceInvitationPreview, IWorkspaceInvitationStatus, InvitationActions, InvitationError, InvitationErrorCode, InvitationErrorFields, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, MintAgentTokenOptions, MyNotificationPreferences, NotificationChannelPreference, NotificationCounts, NotificationData, NotificationEvent, NotificationListParams, NotificationPage, NotificationResult, NotificationScope, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RedirectValidationOptions, RobotsConfig, RobotsPolicy, RolePermissionMap, ScopedActions, SessionRefCrypto, SettingsActions, SitemapUrl, SubscriptionActions, SubscriptionItemTypeValue, SubscriptionStatusType, TranslationKey, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WebMcpTool, WebhookEventName, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceInvitationAcceptedEventData, WorkspaceInvitationDeclinedEventData, WorkspaceInvitationRevokedEventData, WorkspaceInvitationSentEventData, WorkspaceMemberPermissions, WorkspaceNotificationDefault, WorkspacePermissionDefinition, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+/**
+ * Resolve an organisation's regional `serverUrl` from central.
+ *
+ * Who needs this. Most apps serve one organisation and bake its `serverUrl`
+ * into the build, which is why `BuildBase({ serverUrl })` takes it directly.
+ * An app that hosts many organisations cannot: the right cell depends on which
+ * organisation the request is for, and that is only known at runtime.
+ *
+ * Server-side only, deliberately. Resolving in the browser would mean a round
+ * trip before the first API call on every page load, and the answer is not
+ * secret but it is not interesting to a browser either: whatever the client
+ * resolves, the server still has to be given the right URL.
+ *
+ * What it is NOT. This is a convenience, not a security boundary. Nothing here
+ * decides which cell answers: `serverUrl` does, and the real guard is the
+ * audience the token is bound to (`buildbaseAuth({ resource })`). A wrong
+ * answer here produces a 421 from the cell that was asked, which is the signal
+ * to re-resolve, not a cross-region read.
+ */
+interface RegionAnswer {
+    orgId: string;
+    region: Region | string;
+    cellId: string;
+    serverUrl: string;
+}
+interface ResolveServerUrlOptions {
+    /** The organisation to resolve. */
+    orgId: string;
+    /** Central's base URL, for example `https://central.console.buildbase.app`. */
+    centralUrl: string;
+    /**
+     * The organisation's API key (`<orgId>:<secret>`).
+     *
+     * Without it central answers the DEFAULT cell for every id, known or not, on
+     * purpose: organisation ids are ObjectIds and an endpoint that distinguished
+     * known from unknown would be an enumeration oracle. So an unauthenticated
+     * call does not fail, it quietly returns the wrong cell for an EU
+     * organisation. Pass the key.
+     */
+    apiKey?: string;
+    /** Request timeout. Default 5000 ms. */
+    timeoutMs?: number;
+    /** Injectable fetch, mainly for testing. */
+    fetch?: typeof fetch;
+    /**
+     * Where to cache answers. Defaults to a process-memory map, which is the
+     * right thing for one process; pass a shared store to let replicas reuse
+     * each other's lookups.
+     */
+    cache?: ResolveCacheStore;
+}
+/** Same shape as the discovery cache: string in, string out. */
+interface ResolveCacheStore {
+    get(key: string): Promise<string | undefined> | string | undefined;
+    set(key: string, value: string, ttlSeconds: number): Promise<void> | void;
+    delete?(key: string): Promise<void> | void;
+}
+/**
+ * Ask central where an organisation lives, with caching.
+ *
+ * Throws on a network or HTTP failure rather than guessing. A silent fallback
+ * to the default cell is the one behaviour that must not be built in here:
+ * for an EU organisation it would mean sending the request to the US, which is
+ * precisely what the cell topology exists to prevent. The caller decides what
+ * to do with the failure.
+ */
+declare function resolveServerUrl(options: ResolveServerUrlOptions): Promise<RegionAnswer>;
+/**
+ * Forget a cached answer.
+ *
+ * Call it on a `421 misdirected_request`: that response is central's previous
+ * answer being proved stale by the cell that received it, usually because the
+ * organisation was migrated. Re-resolving once after a 421 is the documented
+ * recovery; re-resolving in a loop is not, so the caller should retry the
+ * request once and surface the second failure.
+ */
+declare function clearResolvedServerUrl(options: {
+    orgId: string;
+    centralUrl: string;
+    cache?: ResolveCacheStore;
+}): Promise<void>;
+
+export { AI_BOT_USER_AGENTS, APP_PERMISSION_FALLBACK_GROUP, ApiVersion, AppBridgeError, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, BuildBase, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditBucketSource, CreditBucketStatus, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DISCOVERY_CACHE_TIMEOUT_MS, DunningState, EventEmitter, FALLBACK_WORKSPACE_ROLE, INVITATION_ERROR_CODE, InvoiceStatuses, NotificationsApi, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UPLOAD_ACCEPT, UPLOAD_MAX_BYTES, UploadsApi, UserApi, WEBHOOK_EVENTS, WEBHOOK_EVENTS_BY_CATEGORY, WorkspaceApi, actionableInvitations, appPermissionCatalogue, appTokenFailure, appTokenSuccess, bearerChallenge, buildA2AAgentCard, buildAgentCard, buildAgentSkillsIndex, buildApiCatalog, buildAuthMd, buildDiscoveryLinkHeader, buildDnsAidRecords, buildLlmsFullTxt, buildLlmsTxt, buildMcpDiscoveryManifest, buildMcpServerCard, buildProtectedResourceMetadata, buildRobotsTxt, buildSecurityTxt, buildSitemap, buildSkillMd, buildWebBotAuthDirectory, buildbaseAuth, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAgentReadinessCache, clearAuthIntent, clearPendingInvite, clearResolvedServerUrl, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, createSessionRefCrypto, BuildBase as default, eventEmitter, extractBearerToken, fetchAgentReadiness, formatCents, formatMinorAmountIntl, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, formatUploadLimit, getAvailableBillingIntervals, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyDecimals, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, handleAppRevokeRequest, handleAppTokenRequest, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, inviterNameOf, isInvitationActionable, isInvitationError, isInvitationLapsed, isWebhookEvent, isZeroDecimalCurrency, minorAmountToDisplay, mintAgentToken, negotiateMarkdown, parkPendingInvite, parseWebhookEvent, pickDefaultRole, preflightUpload, provideWebMcpTools, readBBParams, readPendingInvite, resendCooldownSeconds, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveRolePermissions, resolveServerUrl, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, sortInvitations, uploadFailureOf, uploadPolicyOf, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown, workspaceIdOf, workspaceNameOf };
+export type { A2ACardConfig, A2ACardSkill, AgentReadinessBundle, AgentReadyConfig, AgentSkill, ApiCatalogApi, AppRevokeRequestClaims, AppScope, AppTokenRequestClaims, AppTokenResponseBody, AppTokenResult, BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, BuildBaseAuthOptions, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, ContentSignals, CreditActions, CreditBucketSourceType, CreditBucketStatusType, CreditTransactionTypeValue, DiscoveryCacheStore, DiscoveryDocument, DnsAidRecord, 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, INotificationItem, 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, IUploadedFile, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, IUser, IWorkspace, IWorkspaceInvitation, IWorkspaceInvitationPreview, IWorkspaceInvitationStatus, InvitationActions, InvitationError, InvitationErrorCode, InvitationErrorFields, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, MintAgentTokenOptions, MyNotificationPreferences, NotificationChannelPreference, NotificationCounts, NotificationData, NotificationEvent, NotificationListParams, NotificationPage, NotificationResult, NotificationScope, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RedirectValidationOptions, Region, RegionAnswer, ResolveCacheStore, ResolveServerUrlOptions, RobotsConfig, RobotsPolicy, RolePermissionMap, ScopedActions, SessionRefCrypto, SettingsActions, SitemapUrl, SubscriptionActions, SubscriptionItemTypeValue, SubscriptionStatusType, TranslationKey, UploadFailure, UploadOptions, UploadPolicy, UploadPurpose, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WebMcpTool, WebhookEventName, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceInvitationAcceptedEventData, WorkspaceInvitationDeclinedEventData, WorkspaceInvitationRevokedEventData, WorkspaceInvitationSentEventData, WorkspaceMemberPermissions, WorkspaceNotificationDefault, WorkspacePermissionDefinition, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };