@buildbase/sdk 0.0.82 → 0.0.84

package/AGENTS.md

@@ -82,7 +82,7 @@ export const {
 ```
 
 Express / no cookie context: omit `getSessionId`, call `withSession(sessionId)` per request.
-Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err, ctx)`, `fetch`.
+Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err, ctx)`, `fetch`, `region` (informational, read back as `client.region`; type `Region`).
 
 ## Export map (what lives where)
 
@@ -92,7 +92,7 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
 - **API classes:** `BaseApi` (extend for custom APIs), `AuthApi`, `UserApi`, `WorkspaceApi`, `SettingsApi`, `PushApi`.
 - **Webhook verification (runtime-agnostic — Node, edge, Deno, Bun, browsers):** `verifyWebhookSignature`, `parseWebhookEvent`. Verify against the **raw** request body (`await req.text()`), not the parsed JSON. Headers: `x-buildbase-signature` (`sha256=` HMAC over `{timestamp}.{body}`), `x-buildbase-timestamp` (Unix seconds), `x-buildbase-event`.
 - **Webhook events:** `WEBHOOK_EVENTS` (112 `domain.action` names), `WEBHOOK_EVENTS_BY_CATEGORY`, `WebhookEventName`, `isWebhookEvent(name)`, vendored from the platform catalog. A failed payment is `payment.failed`, with `workspaceId, subscriptionId, invoiceId, dunningState, amount, currency, failedAt, nextRetryAt`. Full list: https://docs.buildbase.app/webhooks/overview. Never invent an event name; narrow with `isWebhookEvent` instead.
-- **Agent readiness (framework-agnostic, returns plain `DiscoveryDocument`):** **App owns discovery content, platform owns auth.** All content — `llms.txt`, `robots.txt`, `sitemap`, `protectedResources` (RFC 9728), API catalog, skills — is defined locally in `AgentReadyConfig` and served with no platform round-trip. The platform bundle (`fetchAgentReadiness`, fail-soft/cached) supplies ONLY `{ enabled, authorizationServer }` (the OAuth AS pointer). Functions: `resolveAgentPath` (dispatch ALL agent paths — root docs + `.well-known/*`; prefer for new wiring), `resolveWellKnown` (`.well-known/*` only), `clearAgentReadinessCache`, `buildAgentCard`, `buildA2AAgentCard` (A2A card at `/.well-known/agent-card.json`; served by DEFAULT, derived from `site`+`skills`; `a2aCard: false` disables, object overrides), `buildProtectedResourceMetadata(path, config)` (local), `buildAgentSkillsIndex`, `buildSkillMd`, `buildSecurityTxt`, `buildLlmsTxt(config)` (from `config.llmsTxt`), `buildLlmsFullTxt` (from `config.llmsFullTxt`), `buildRobotsTxt`, `buildSitemap`, `buildApiCatalog`, `buildMcpServerCard`, `buildAuthMd`, `buildWebBotAuthDirectory` (JWKS at `/.well-known/http-message-signatures-directory` from `config.webBotAuth.keys`; opt-in), `buildDnsAidRecords` (suggested `_agents` DNS records — publish at your DNS provider, can't be served over HTTP), `buildDiscoveryLinkHeader`, `wantsMarkdown`/`negotiateMarkdown`, `sha256Digest`, `AI_BOT_USER_AGENTS`. `config.extraPaths` serves ANY literal document by exact path (commerce discovery: x402/UCP/ACP/MPP, `/openapi.json`, future `.well-known` docs) and takes precedence over built-ins. Types: `AgentReadyConfig`, `AgentReadinessBundle`, `AgentSkill`, `ApiCatalogApi`, `A2ACardConfig`, `A2ACardSkill`, `DnsAidRecord`, `McpServerCard`, `RobotsConfig`, `RobotsPolicy`, `ContentSignals`, `SitemapUrl`, `DiscoveryDocument`.
+- **Agent readiness (framework-agnostic, returns plain `DiscoveryDocument`):** **App owns discovery content, platform owns auth.** All content — `llms.txt`, `robots.txt`, `sitemap`, `protectedResources` (RFC 9728), API catalog, skills — is defined locally in `AgentReadyConfig` and served with no platform round-trip. The platform bundle (`fetchAgentReadiness`, fail-soft/cached) supplies ONLY `{ enabled, authorizationServer }` (the OAuth AS pointer). Functions: `resolveAgentPath` (dispatch ALL agent paths — root docs + `.well-known/*`; prefer for new wiring), `resolveWellKnown` (`.well-known/*` only), `clearAgentReadinessCache`, `buildAgentCard`, `buildA2AAgentCard` (A2A card at `/.well-known/agent-card.json`; served by DEFAULT, derived from `site`+`skills`; `a2aCard: false` disables, object overrides), `buildProtectedResourceMetadata(path, config)` (local), `buildAgentSkillsIndex`, `buildSkillMd`, `buildSecurityTxt`, `buildLlmsTxt(config)` (from `config.llmsTxt`), `buildLlmsFullTxt` (from `config.llmsFullTxt`), `buildRobotsTxt`, `buildSitemap`, `buildApiCatalog`, `buildMcpServerCard`, `buildAuthMd`, `buildWebBotAuthDirectory` (JWKS at `/.well-known/http-message-signatures-directory` from `config.webBotAuth.keys`; opt-in), `buildDnsAidRecords` (suggested `_agents` DNS records — publish at your DNS provider, can't be served over HTTP), `buildDiscoveryLinkHeader`, `wantsMarkdown`/`negotiateMarkdown`, `sha256Digest`, `AI_BOT_USER_AGENTS`, `DISCOVERY_CACHE_TIMEOUT_MS`. `config.extraPaths` serves ANY literal document by exact path (commerce discovery: x402/UCP/ACP/MPP, `/openapi.json`, future `.well-known` docs) and takes precedence over built-ins. `config.cache` (a `DiscoveryCacheStore`: string `get`/`set`, optional `delete`) shares the platform fetches across replicas instead of caching per process; the default is process memory. Types: `AgentReadyConfig`, `AgentReadinessBundle`, `AgentSkill`, `DiscoveryCacheStore`, `ApiCatalogApi`, `A2ACardConfig`, `A2ACardSkill`, `DnsAidRecord`, `McpServerCard`, `RobotsConfig`, `RobotsPolicy`, `ContentSignals`, `SitemapUrl`, `DiscoveryDocument`.
 - **OAuth2 app-bridge:** `handleAppTokenRequest`, `handleAppRevokeRequest` (one-call handlers), `bearerChallenge` (RFC 9728/6750 401; header values are quoted-string-escaped + CR/LF-stripped), `verifyAppTokenRequest`, `verifyAppRevokeRequest`, `verifyClientJwt`, `signClientJwt` (HS256 mint — symmetric counterpart of verify), `extractBearerToken`, `appTokenSuccess`, `appTokenFailure`, `AppBridgeError`. Types: `AppTokenRequestClaims`, `AppRevokeRequestClaims`, `AppTokenResult`, `AppTokenResponseBody`, `HandlerResult`, `VerifyClientJwtOptions`. `verifyClientJwt(token, secret, opts?: VerifyClientJwtOptions)` **requires a numeric `exp` by default** (`requireExp: false` to allow non-expiring tokens); optional `clockToleranceSec` / `issuer` / `audience`. **Presets** (also in core): `mintAgentToken` (the whole mint in one call — HS256 with the app's secret, `aud` from the grant's resource, encrypted `sid`) + `buildbaseAuth` (the whole verify) + `createSessionRefCrypto`. Security invariant: the platform relays the minted token but never sees the app secret — it can neither forge nor decode app tokens, and the BuildBase session is never stored and never plaintext in a token.
 - **Currency & pricing utils (pure):** `formatCents`, `formatOverageRate`, `formatOverageRateWithLabel`, `formatQuotaIncludedOverage`, `formatQuotaWithPrice`, `getCurrencySymbol`, `getCurrencyFlag`, `getQuotaUnitLabelFromName`, `getQuotaDisplayValue`, `CURRENCY_DISPLAY`, `CURRENCY_FLAG`, `PLAN_CURRENCY_CODES`, `PLAN_CURRENCY_OPTIONS`.
 - **Pricing variants (multi-currency):** `getPricingVariant`, `getBasePriceCents`, `getStripePriceIdForInterval`, `getQuotaOverageCents`, `getQuotaDisplayWithVariant`, `getAvailableCurrenciesFromPlans`, `getDisplayCurrency`, `getBillingIntervalAndCurrencyFromPriceId`.
@@ -100,16 +100,19 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
 - **RBAC (pure):** `hasPermission`, `resolvePermissions`, `resolveMaxUsers`, `validateInvite`, `DEFAULT_ROLE_PERMISSIONS`, `Permission` (enum).
 - **URL / auth-intent / redirects:** `BB_PARAM`, `BBAction`, `BBScreen`, `BBStatus`, `createBBUrl`, `readBBParams`, `cleanBBParams`, `createCheckoutRedirectUrls`, `createCreditPurchaseRedirectUrls`, `safeRedirect`, `validateRedirectUrl`, `saveAuthIntent`, `consumeAuthIntent`, `clearAuthIntent`.
 - **Context invalidation (call after server mutations to refetch client contexts):** `invalidateSubscription`, `invalidateQuotaUsage`, `invalidateCreditBalance`.
+- **Regional resolution (server-side, for apps hosting many orgs):** `resolveServerUrl({ orgId, centralUrl, apiKey, cache? })` asks central which cell an organisation lives in and caches the answer for central's own `max-age`; `clearResolvedServerUrl({ orgId, centralUrl, cache? })` forgets it, which is the documented recovery from a `421 misdirected_request`. Types: `RegionAnswer`, `ResolveServerUrlOptions`, `ResolveCacheStore`. Throws on failure rather than falling back to the default cell, because that fallback would send an EU organisation's request to the US. **Pass `apiKey`**: without it central answers the default cell for every id, known or not, on purpose (organisation ids are ObjectIds, so a distinguishable 404 would be an enumeration oracle).
 - **Events:** `EventEmitter`, `eventEmitter` (singleton), `SDKEvent` (enum).
 - **Workspace invitations (pure):** `INVITATION_ERROR_CODE`, `isInvitationError`, `sortInvitations`, `actionableInvitations`, `isInvitationActionable`, `isInvitationLapsed`, `resendCooldownSeconds`, `parkPendingInvite`, `readPendingInvite`, `clearPendingInvite`; server factory namespace `invitations` (`list`, `create`, `resend`, `revoke`).
 - **Push:** `PushApi`, `PUSH_SERVICE_WORKER_SCRIPT`.
+- **Uploads (an end user's image, counted as the org's storage):** `UploadsApi` (`upload(file, { purpose, signal? })`: intent, signed PUT straight to storage with a 2-minute timeout, complete), `UPLOAD_ACCEPT`, `UPLOAD_MAX_BYTES` (the platform's 5 MB; the org may set less), `uploadFailureOf(error)` (a refusal's reason - `tooLarge`, `invalid`, `disabled`, `userLimit`, `unavailable`, `failed` - for translated copy; the thrown message is the server's English sentence), `uploadPolicyOf(settings)` (the org's `{ enabled, maxFileBytes }` from `settings.uploads`), `preflightUpload(file, policy)` (the refusal known before a request), `formatUploadLimit(bytes, locale)`. Types: `IUploadedFile`, `UploadFailure`, `UploadOptions`, `UploadPolicy`, `UploadPurpose` (`'workspace-image' | 'profile-image'`). Server-side: `client.forSession(id).uploads`. A profile picture is saved with `updateUserProfile({ image: file.url })`.
 - **Notification inbox:** `NotificationsApi` (`list`, `counts`, `markRead`, `markUnread`, `archive`, `unarchive`, `markAllRead`, `markSeen`).
 - **Enums:** `ApiVersion`, `AuthStatus`, `BillingIntervals`, `CreditBucketSource`, `CreditBucketStatus`, `CreditTransactionType`, `DunningState`, `InvoiceStatuses`, `SubscriptionItemType`, `SubscriptionStatus`.
 
 ### `@buildbase/sdk/react` — client-only additions (core is re-exported here too)
 
 - **Providers:** `SaaSOSProvider` (root), `SubscriptionContextProvider`, `QuotaUsageContextProvider`, `CreditBalanceContextProvider`, `PushNotificationProvider`.
-- **State hooks:** `useSaaSAuth`, `useSaaSWorkspaces`, `useSaaSOs`, `useSaaSSettings`, `useUserAttributes`, `useUserFeatures`, `useTranslation`, `usePermissions`, `useSeatStatus`, `useTrialStatus`, `useFullScreenLoader`, `useMyInvitations`, `useWorkspaceInvitations`, `useNotifications`.
+- **State hooks:** `useSaaSAuth`, `useSaaSWorkspaces`, `useSaaSOs` (exposes `region` when the app passes it to `SaaSOSProvider`; informational, for badges and support tooling), `useSaaSSettings`, `useUserAttributes`, `useUserFeatures`, `useTranslation`, `usePermissions`, `useSeatStatus`, `useTrialStatus`, `useFullScreenLoader`, `useMyInvitations`, `useWorkspaceInvitations`, `useNotifications`.
+- **Upload hooks:** `useUpload(purpose)` (`{ upload, cancel, loading, error, failure, enabled, maxBytes, maxLabel }`; reads the org's upload settings, refuses a file over its limit before a request, `error` is translated into the active locale and `failure` is the reason; a new upload, `cancel()` or unmount aborts the one in flight), `useUploadsApi`.
 - **Subscription/billing hooks:** `usePublicPlans`, `useSubscription`, `useSubscriptionContext`, `useSubscriptionManagement`, `usePlanGroup`, `usePlanGroupVersions`, `usePublicPlanGroupVersion`, `useCreateCheckoutSession`, `useUpdateSubscription`, `useCancelSubscription`, `useResumeSubscription`, `useBillingPortal`, `useInvoices`, `useInvoice`.
 - **Quota hooks:** `useQuotaUsageContext`, `useRecordUsage`, `useQuotaUsageStatus`, `useAllQuotaUsage`, `useUsageLogs`.
 - **Credit hooks:** `useCreditBalance`, `useCreditBalanceContext`, `useConsumeCredits`, `usePurchaseCredits`, `useCreditPackages`, `usePublicCreditPackages`, `useCreditTransactions`, `useExpiringCredits`.
@@ -167,6 +170,11 @@ Expose a live MCP server (stateless Streamable HTTP; Node 18+/edge) with built-i
 - **Agent-readiness fetches are fail-soft** — a platform outage yields `{ enabled: false }`, never a 500. Don't add your own error handling expecting throws.
 - **New crypto is dependency-free pure JS** (`src/lib/sha256.ts`) so it behaves identically on browser/edge/Node — don't swap in Web Crypto / Node `crypto` without matching outputs.
 - **Prefer SDK hooks** (`useSaaS*`, `useSubscription*`, etc.) over `useAppSelector`/internal context so consumer code stays stable across internal refactors.
+- **Pass `idempotencyKey` on `usage.record`, `usage.recordBatch` and `credits.consume`.** It is optional in the type and should be treated as required in anything that meters or spends. The SDK retries only idempotent requests, so a `POST` that fails mid-flight is not retried for you: the caller retries, and without a key the second attempt bills twice. Use a key derived from the unit of work (`gen-<requestId>`, `email-<messageId>`), not a fresh UUID per attempt. This matters more against a load-balanced API with several replicas than against one server, because a retry landing on a different replica is the normal case.
+- **`serverUrl` must be the organisation's REGIONAL URL.** Today every organisation is on the default cell, `https://api.console.buildbase.app`; an organisation in another region uses the URL central answers for it, never a guessed hostname. There is no auto-discovery in the client bundle and there will not be: resolving in the browser costs a round trip before the first API call on every page load. An app serving one organisation bakes the URL into the build; one serving many resolves per request on the server with `resolveServerUrl`. Sending an organisation's request to the wrong cell returns `421 misdirected_request` with the right `serverUrl`, never a silent cross-region read - treat it as the signal to re-resolve once.
+- **The MCP server card and protected-resource metadata advertise the regional endpoint.** `createAgentStack` derives both from `serverUrl`, so getting `serverUrl` right is the whole of it; there is nothing extra to configure per cell. An agent that discovered a US endpoint for an EU organisation would authenticate against the wrong cell and be refused by the audience check.
+- **`region` is informational.** `BuildBase({ region })`/`client.region` and `SaaSOSProvider region=` are for logs, metrics and UI badges. What decides which cell answers is `serverUrl`, and on the server the audience the token is bound to (`buildbaseAuth({ resource })`). A wrong `region` mislabels a badge; it cannot misroute a request.
+- **Agent-readiness caching is per process by default.** `fetchAgentReadiness` and the authorization-server metadata fetch keep their results in process memory, so N replicas each fetch their own copy and `clearAgentReadinessCache()` clears only the process it runs in. Pass `cache` (a `DiscoveryCacheStore`, same idea as the content client's `CacheStore`) to share one copy across replicas. A store that throws, or takes longer than `DISCOVERY_CACHE_TIMEOUT_MS` (500 ms), degrades to a cache miss, never to a failed or hung discovery response.
 
 ## Working on this repo
 

package/CHANGELOG.md

@@ -5,6 +5,101 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.84] - 2026-10-17
+
+### Fixed
+
+- `docs/SERVER-CONTENT.md` names the console's menus as they read now: **Settings > API keys**, **Settings > Webhooks** and **Settings > Deploy hooks** (it said "API tokens" and "Deployments"). The build-time pull section says how a console deploy starts (from the publish banner or **Deploy** on a hook, not on every publish) and links the deploy hooks setup guide at docs.buildbase.app.
+- The README's tracking section names **Settings > Tracking & tags**.
+
+### Added
+
+- **Uploads.** `useUpload(purpose)` and `UploadsApi` let a signed-in user
+  upload an image - a workspace's or a profile picture - straight to storage
+  on a signed URL: the server checks type, size and the organization's
+  storage before a byte is sent, and the file it stores counts toward the
+  organization's storage like any other. Images only, up to 5 MB, or the
+  lower limit the organization sets.
+  - `useUpload` returns
+    `{ upload, cancel, loading, error, failure, enabled, maxBytes, maxLabel }`.
+  - It reads the organization's upload settings (`settings.uploads`:
+    `{ enabled, maxFileBytes }`) and refuses a file over the limit, or any
+    file while uploads are off, before a request. A server that does not send
+    `uploads` has no end-user uploads, so they are off there, and the upload
+    and picture controls do not show.
+  - `error` is translated into the active locale (`uploads.*` keys in all
+    eight locales, `{max}` filled with the limit); `failure` names the reason.
+  - The upload in flight is aborted on a new one, on `cancel()` and on
+    unmount, and the PUT to storage has its own two-minute timeout.
+  - `uploadFailureOf`, `uploadPolicyOf`, `preflightUpload`,
+    `formatUploadLimit` and the type `UploadPolicy` are exported for an app's
+    own UI. Server-side, `client.forSession(id).uploads` is the same client.
+- **The workspace settings screen gains an Upload image option** next to the
+  emoji and URL ones, shown only when the organization allows uploads and
+  stating its limit; **the profile screen gains a picture**: upload one,
+  remove it, saved with the profile (`updateUserProfile({ image })`, which
+  needs a server that accepts `image` on `PATCH /profile`). New keys
+  `general.uploadImage`, `general.chooseImage`, `profile.changePicture`,
+  `profile.removePicture` and the `uploads` namespace, in all eight locales.
+- **Regional resolution, for apps that host many organisations.**
+  `resolveServerUrl({ orgId, centralUrl, apiKey, cache? })` asks central which
+  cell an organisation lives in and caches the answer for central's own
+  `max-age`; `clearResolvedServerUrl` forgets it, the recovery from a
+  `421 misdirected_request`. It throws rather than falling back to the default
+  cell. Pass `apiKey`: without it central answers the default cell for every
+  id, and that answer (sent `no-store`) is never cached. Types `RegionAnswer`,
+  `ResolveServerUrlOptions`, `ResolveCacheStore`.
+  Needs a central server that serves `GET /api/organizations/orgs/:orgId/region`.
+- **`region` on `BuildBase({ region })`, `client.region` and
+  `SaaSOSProvider region=`** (read back from `useSaaSOs()`). Informational
+  only, for logs and badges: it is never sent and never changes which cell
+  answers; `serverUrl` does.
+- **A shared cache for agent-readiness discovery.** `AgentReadyConfig.cache`
+  takes a `DiscoveryCacheStore` (string `get`/`set`, optional `delete`) so
+  replicas share the platform fetches instead of each caching in process
+  memory, which stays the default. A store that throws, or takes longer than
+  `DISCOVERY_CACHE_TIMEOUT_MS` (500 ms, exported), is treated as a cache
+  miss, so a hung store cannot hang a discovery response.
+
+### Changed
+
+- **Types:** `SDKMessages` gains the `uploads` namespace and
+  `profile.changePicture` / `profile.removePicture`, and `ISettings` gains an
+  optional `uploads`. `messageOverrides` takes `PartialSDKMessages`, so
+  existing overrides keep compiling; only code that builds a complete
+  `SDKMessages` object by hand needs the new keys.
+- `package-lock.json` carries the package's version again.
+
+## [0.0.83] - 2026-10-14
+
+### Fixed
+
+- **⚠️ The push service worker now shows rich notifications, and a `tag`
+  replaces instead of stacking.** `PUSH_SERVICE_WORKER_SCRIPT` showed only a
+  title, body and icon (the icon doubling as the badge), and gave every
+  message its own `buildbase-push-<timestamp>` tag. The server sends image,
+  badge, action buttons, `tag`, `requireInteraction`, `silent`, `renotify`,
+  `timestamp` and `dir`, and the worker dropped all of them, so a notification
+  never kept its image or buttons, never stayed on screen when asked to, and
+  could not replace an earlier one with the same tag. All of them now reach the
+  browser. A sent `badge` is used and the icon is still the fallback,
+  `renotify` is only set with a tag (the browser refuses it without one), and
+  an unknown `dir` or a malformed action is dropped rather than failing the
+  notification. If the browser still refuses an option, the worker shows the
+  notification again with only its title, body, icon, tag and click link. The
+  tracked click URL now wins over a `url` inside `payload.data`, so that `url`
+  can no longer bypass click tracking; a `data.url` is still opened when the
+  payload has no click URL. A click on an action button opens the same link as
+  a click on the notification. Apps that write `public/push-sw.js` from the
+  export at build time get this on upgrade.
+- **The README's push section no longer carries its own copy of the worker.**
+  It now shows the same build step as the docs,
+  `fs.writeFileSync('public/push-sw.js', PUSH_SERVICE_WORKER_SCRIPT)`. The copy
+  had the rich options the shipped script lacked but, like the shipped script,
+  let `payload.data.url` override the tracked click URL. An app that pasted it,
+  or any other hand-made copy of the worker, should switch to writing the
+  export at build time; a copy does not change when the SDK is upgraded.
+
 ## [0.0.82] - 2026-10-12
 
 ### Fixed

package/README.md

@@ -497,7 +497,7 @@ The returned object is merged into the Stripe checkout session. You can return a
 
 ## 📈 Tracking & Tags
 
-The tags you configure in the BuildBase console - under **Settings › Tracking & Tags**, attached to an auth client - installed in your app, with the conversions BuildBase already observes fired for you. No tag ids in your code: a marketing site and a product app carry different tags because they are different auth clients.
+The tags you configure in the BuildBase console - under **Settings > Tracking & tags**, attached to an auth client - installed in your app, with the conversions BuildBase already observes fired for you. No tag ids in your code: a marketing site and a product app carry different tags because they are different auth clients.
 
 ### Turn it on
 
@@ -840,52 +840,29 @@ function TrialInfo() {
 
 ## 🔔 Push Notifications
 
-Browser push notifications — built into the SDK. Users can enable/disable from the **Notifications** tab in workspace settings. Billing events (payment failed, trial ending) auto-send push notifications.
+Browser push notifications - built into the SDK. Users can enable/disable from the **Notifications** tab in workspace settings. Billing events (payment failed, trial ending) auto-send push notifications.
 
-**Only setup required:** Create `public/push-sw.js` in your app:
+**Only setup required:** serve the SDK's service worker at `/push-sw.js`. It ships as the `PUSH_SERVICE_WORKER_SCRIPT` string, exported from both `@buildbase/sdk` and `@buildbase/sdk/react`. Write it into your public directory at build time, so it updates with the SDK:
 
 ```js
-self.addEventListener('push', function (event) {
-  if (!event.data) return;
-  try {
-    var payload = event.data.json();
-    var options = {
-      body: payload.body || '',
-      icon: payload.icon || undefined,
-      badge: payload.badge || payload.icon || undefined,
-      image: payload.image || undefined,
-      tag: payload.tag || undefined,
-      actions: payload.actions || undefined,
-      silent: payload.silent || false,
-      requireInteraction: payload.requireInteraction || false,
-      renotify: payload.renotify || false,
-      timestamp: payload.timestamp || undefined,
-      dir: payload.dir || 'auto',
-      data: { url: payload.url, ...(payload.data || {}) },
-    };
-    event.waitUntil(self.registration.showNotification(payload.title || 'Notification', options));
-  } catch (e) {
-    console.error('[PushSW]', e);
-  }
-});
+// scripts/write-push-sw.mjs
+import fs from 'node:fs';
+import { PUSH_SERVICE_WORKER_SCRIPT } from '@buildbase/sdk';
 
-self.addEventListener('notificationclick', function (event) {
-  event.notification.close();
-  var url = event.notification.data && event.notification.data.url;
-  if (url) {
-    event.waitUntil(
-      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function (list) {
-        for (var i = 0; i < list.length; i++) {
-          if (list[i].url === url && 'focus' in list[i]) return list[i].focus();
-        }
-        if (clients.openWindow) return clients.openWindow(url);
-      })
-    );
+fs.writeFileSync('public/push-sw.js', PUSH_SERVICE_WORKER_SCRIPT);
+```
+
+```json
+{
+  "scripts": {
+    "prebuild": "node scripts/write-push-sw.mjs"
   }
-});
+}
 ```
 
-Everything else is built-in — permission handling, subscribe/unsubscribe, settings UI, billing auto-triggers, and browser-specific unblock instructions.
+The worker shows everything the server sends: title, body, icon, badge, image, action buttons, `requireInteraction`, `silent`, `renotify`, `timestamp` and `dir`. A notification with a `tag` replaces the earlier one with the same tag instead of stacking. A click, on the notification or on one of its buttons, opens the notification's tracked link, so clicks are counted. Do not hand-write a copy of the worker: a copy does not pick up fixes when you upgrade the SDK.
+
+Everything else is built-in - permission handling, subscribe/unsubscribe, settings UI, billing auto-triggers, and browser-specific unblock instructions.
 
 ## 📬 Notifications
 
@@ -1401,6 +1378,83 @@ await bb.sessions.list(); // ISessionView[]
 await bb.sessions.revoke(sessionId); // by the session's public handle
 ```
 
+## 🖼️ Uploads
+
+Your users can upload an image - a workspace's, a profile picture - without
+it touching your server or ours. The SDK asks for an upload, the file goes
+straight to storage on a signed URL sized to that one file, and the server
+checks what landed before it becomes a file. Images only (PNG, JPEG, GIF,
+WebP, SVG), up to 5 MB, or less if you set less.
+
+Every upload counts toward **your organization's storage**, like a file you
+upload in the console, and shows up in your assets with the user as its
+creator. You decide what your users may upload in the BuildBase console
+(Billing settings, Storage, **End-user uploads**): uploads on or off, the
+largest file (100 KB to 5 MB), and optionally a total per user. The SDK reads
+the first two from your organization's settings, so it offers an upload only
+when one can succeed and states your limit.
+
+The built-in settings screens use this: the workspace screen's **Upload image**
+option, and the profile screen's **Upload picture**, which saves the picture
+on the user's profile.
+
+```tsx
+import { UPLOAD_ACCEPT, useSaaSWorkspaces, useUpload } from '@buildbase/sdk/react';
+
+function AvatarPicker() {
+  const { upload, loading, error, enabled, maxLabel } = useUpload('profile-image');
+  const { updateUserProfile } = useSaaSWorkspaces();
+  if (!enabled) return null; // your organization turned uploads off
+  return (
+    <>
+      <input
+        type="file"
+        accept={UPLOAD_ACCEPT}
+        disabled={loading}
+        onChange={async e => {
+          const file = e.target.files?.[0];
+          if (!file) return;
+          // `error` says why, translated, when it rejects.
+          const stored = await upload(file).catch(() => null);
+          if (stored) await updateUserProfile({ image: stored.url });
+        }}
+      />
+      <p>Up to {maxLabel}.</p>
+      {error && <p role="alert">{error}</p>}
+    </>
+  );
+}
+```
+
+`upload` resolves with `{ id, name, size, mimeType, url, width, height }`;
+`url` is public. A file over your limit, or any file while uploads are off, is
+refused before a request is sent. A refusal from the server rejects with its
+`status` and `code`: `413` `UPLOAD_TOO_LARGE`, `403` `UPLOADS_DISABLED` or
+`USER_UPLOAD_LIMIT` (the user's total is full), `429` for too many uploads at
+once, `503` `UPLOADS_UNAVAILABLE` when your organization cannot take files
+right now - its storage is full, say - and `501` when the server has no direct
+uploads configured. See `docs/ERROR_CODES.md`.
+
+- **`useUpload(purpose)`** - `{ upload, cancel, loading, error, failure, enabled, maxBytes, maxLabel }`.
+  `error` is translated into the active locale; `failure` is the reason
+  (`tooLarge`, `invalid`, `disabled`, `userLimit`, `unavailable` or `failed`)
+  for a screen that words it itself. One upload at a time: a new one, `cancel()`
+  or unmounting aborts the one in flight, so a screen left mid-upload does not
+  store a file nobody saves.
+- **`UploadsApi`** (+ `IUploadedFile`, `UploadPurpose`, `UploadOptions` with an
+  optional `signal`) for direct calls, `useUploadsApi()` for a memoized one, and
+  `client.forSession(sessionId).uploads` on the server.
+- **`uploadFailureOf(error)`**, **`uploadPolicyOf(settings)`**,
+  **`preflightUpload(file, policy)`** and **`formatUploadLimit(bytes, locale)`**
+  are the pieces `useUpload` is built from, for your own UI.
+- `UPLOAD_ACCEPT` is the `accept` list the server takes; `UPLOAD_MAX_BYTES` is
+  the platform's 5 MB.
+- `purpose` is `'workspace-image'` or `'profile-image'`.
+
+A workspace image sent as a `data:` URI larger than 16 KB is refused once your
+organization's storage limits are enforced; upload it instead and save its
+`url`.
+
 ## 👤 User Management
 
 ### User Attributes
@@ -2064,6 +2118,47 @@ All endpoints (except `/token/exchange`) require the `x-session-id` header.
 | `source`         | `string` | No       | Source identifier (e.g. `'backend'`, `'worker'`, `'cron'`)     |
 | `idempotencyKey` | `string` | No       | Unique key for deduplication                                   |
 
+> **`serverUrl` is the organisation's regional URL.** Today every organisation
+> is on the default cell, `https://api.console.buildbase.app`. When an
+> organisation lives in another region, its URL is the one central answers for
+> it (below), not one to guess. There is deliberately no auto-discovery
+> in the client bundle, because resolving in the browser would cost a round
+> trip before the first API call on every page load. If your app serves one
+> organisation, bake the URL in. If it serves many, resolve on the server:
+>
+> ```ts
+> import { resolveServerUrl } from '@buildbase/sdk';
+>
+> const { serverUrl } = await resolveServerUrl({
+>   orgId,
+>   centralUrl: process.env.BUILDBASE_CENTRAL_URL!,
+>   apiKey: process.env.BUILDBASE_ORG_API_KEY!, // without it you get the default cell
+> });
+> const bb = BuildBase({ serverUrl, orgId });
+> ```
+>
+> It caches for as long as central says and throws rather than guessing: a
+> silent fallback to the default cell would send an EU organisation's request
+> to the US. A `421 misdirected_request` means the cached answer is stale
+> (usually a migration) - call `clearResolvedServerUrl` and retry once.
+>
+> `region` (`BuildBase({ serverUrl, orgId, region: 'eu' })`, read back as
+> `client.region`, and `SaaSOSProvider region="eu"`, read back from
+> `useSaaSOs().region`) is informational: it labels logs, metrics and badges.
+> `serverUrl` decides which cell answers; a wrong `region` cannot misroute a
+> request.
+
+> **Pass `idempotencyKey` on anything that meters or spends.** It is optional in
+> the type, and you should treat it as required on `usage.record`,
+> `usage.recordBatch` and `credits.consume`. The SDK retries only idempotent
+> requests, so a `POST` that fails in flight is not retried for you: your code
+> retries, and without a key the second attempt bills the customer twice. Derive
+> the key from the unit of work (`gen-<requestId>`, `email-<messageId>`), never a
+> fresh UUID per attempt, or every retry looks like new usage. This matters more
+> once the API runs several replicas behind a load balancer, because a retry
+> landing on a different replica than the first attempt is then the normal case
+> rather than the exception.
+
 **Record usage response:**
 
 | Field         | Type      | Description                                  |
@@ -2578,6 +2673,7 @@ Prefer these SDK hooks for state and operations instead of `useAppSelector`:
 | `useSaaSWorkspaces()`       | Workspaces, currentWorkspace, loading, switching/switchingToId, CRUD and switch actions                                                                                                                                                                                   |
 | `useSaaSOs()`               | OS config (serverUrl, version, orgId, auth, settings) when you need the full config object                                                                                                                                                                                |
 | `useSaaSSettings()`         | Organization settings — `{ settings, loading, error, refetch }` (prefer this when you only need settings)                                                                                                                                                                 |
+| `useUpload(purpose)`        | Upload an image within the organization's upload settings — `{ upload, cancel, loading, error, failure, enabled, maxBytes, maxLabel }` (see Uploads)                                                                                                                      |
 | `useUserAttributes()`       | User attributes — `{ attributes, loading, error, refetch, updateAttribute, updateAttributes }`                                                                                                                                                                            |
 | `useUserFeatures()`         | User feature flags — `{ features, isFeatureEnabled, loading, error, refetch }`                                                                                                                                                                                            |
 | `useConnectedAgents()`      | Authorized AI agents — `{ agents, loading, error, revoking, refresh, revoke }`                                                                                                                                                                                            |
@@ -2619,6 +2715,7 @@ All TypeScript types are exported for type safety. See the [TypeScript definitio
 | `orgId`                   | `string`                   | ✅       | Organization ID (must be valid MongoDB ObjectId - 24 hex characters)                      |
 | `auth`                    | `IAuthConfig`              | ❌       | Authentication configuration                                                              |
 | `locale`                  | `SDKLocale`                | ❌       | SDK UI language (`'en'`, `'es'`, `'fr'`, `'de'`, `'ja'`, `'zh'`, `'hi'`, `'ar'`)          |
+| `region`                  | `Region`                   | ❌       | Informational: the organization's region, for logs and badges (`useSaaSOs().region`)      |
 | `defaultPermissions`      | `Record<string, string[]>` | ❌       | Default app permissions per role                                                          |
 | `getCheckoutStripeParams` | `GetCheckoutStripeParams`  | ❌       | Async callback called before every Stripe checkout to return metadata, referral IDs, etc. |
 | `children`                | `ReactNode`                | ✅       | React children                                                                            |
@@ -3426,7 +3523,7 @@ app.use(async (req, res, next) => {
 
 (`resolveWellKnown` remains available for `.well-known`-only wiring; `resolveAgentPath` is a superset.)
 
-`fetchAgentReadiness` is **fail-soft** — any network/HTTP/parse error resolves to `{ enabled: false }`, so a discovery route never 500s and never leaks that the platform is down; agents simply see the app as not (yet) agent-ready. Results are cached in-memory for `cacheTtlSeconds` (default 300s); call `clearAgentReadinessCache()` to reset (mainly for tests).
+`fetchAgentReadiness` is **fail-soft** — any network/HTTP/parse error resolves to `{ enabled: false }`, so a discovery route never 500s and never leaks that the platform is down; agents simply see the app as not (yet) agent-ready. Results are cached for `cacheTtlSeconds` (default 300s), in process memory unless you pass `cache`: a `DiscoveryCacheStore` (`get`, `set`, optional `delete`, string values) backed by Redis, Cloudflare KV or Upstash, so every replica shares one copy. A store that throws, or takes longer than `DISCOVERY_CACHE_TIMEOUT_MS` (500 ms), counts as a miss, never as a failed or hung response. Call `clearAgentReadinessCache(store?)` to reset (mainly for tests); with a store it deletes the keys this process wrote.
 
 ### robots.txt, Content Signals & AI bots