@buildbase/sdk 0.0.70 → 0.0.73

package/AGENTS.md

@@ -83,13 +83,15 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
 - **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`.
 - **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`.
+- **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`.
+- **State hooks:** `useSaaSAuth`, `useSaaSWorkspaces`, `useSaaSOs`, `useSaaSSettings`, `useUserAttributes`, `useUserFeatures`, `useTranslation`, `usePermissions`, `useSeatStatus`, `useTrialStatus`, `useFullScreenLoader`, `useMyInvitations`, `useWorkspaceInvitations`, `useNotifications`.
 - **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`.
@@ -102,7 +104,8 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
   - Trial: `WhenTrialing`, `WhenNotTrialing`, `WhenTrialEnding`
   - Quota: `WhenQuotaAvailable`, `WhenQuotaExhausted`, `WhenQuotaOverage`, `WhenQuotaThreshold`
   - Credits: `WhenCreditsAvailable`, `WhenCreditsExhausted`, `WhenCreditsLow`
-- **UI components:** `WorkspaceSwitcher`, `PricingPage`, `CreditStorePage`, `CreditBalance`, `CreditActionsProvider`, `BetaForm`, `FullScreenLoader`.
+  - Invitations: `WhenPendingInvitations`
+- **UI components:** `WorkspaceSwitcher`, `PricingPage`, `CreditStorePage`, `CreditBalance`, `CreditActionsProvider`, `BetaForm`, `FullScreenLoader`, `PendingInvitations`, `NotificationBell`, `NotificationInbox`.
 - **Misc:** `SUPPORTED_LOCALES`, `SETTINGS_SCREENS`, `SettingsScreen`, `workspaceSettingsManager`.
 
 ### `@buildbase/sdk/data`

package/CHANGELOG.md

@@ -7,6 +7,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.73] - 2026-09-28
+
+### Added
+
+- **An organization's own permissions.** Keys defined in the BuildBase console
+  (`app:reports:export`) arrive in `settings.workspace.customPermissions` and
+  resolve per role exactly like the platform's own, so `can('app:reports:export')`
+  answers from what the organization granted rather than from a prop the app
+  shipped. `usePermissions()` returns `appPermissionDefinitions` for rendering
+  them, and `appPermissionCatalogue(settings, appPermissions)` is exported for
+  the same list outside React. Needs a server from release 23.
+- **Your backend can ask what a member may do.** The server client gains
+  `workspace.permissions(workspaceId)`, the server's own answer
+  (`{ role, isOwner, permissions }`), and `workspace.can(workspaceId, key)` for
+  one key or every key of a list. Check before acting rather than trusting the
+  browser.
+- The workspace permissions screen lists the organization's catalogue with its
+  labels. Before, it could only infer keys from the `defaultPermissions` prop,
+  so a permission nobody had granted yet was invisible and ungrantable.
+  Keys passed through `defaultPermissions` keep working and are listed too.
+- `Permission.WORKSPACE_USAGE_RECORD` (`workspace:usage:record`): recording usage
+  and spending credits. Editors hold it, viewers do not.
+- **Enhanced conversions.** New `setIdentity({ email, phone })` on `useTracking()`: normalised per Google's spec (trimmed, lower case, dots removed from Gmail local parts; phones in E.164) and hashed with SHA-256 in the browser (WebCrypto, with the SDK's pure fallback). Only the hashes are kept. They are set as `gtag('set', 'user_data', { sha256_email_address, sha256_phone_number })` before each conversion and as Meta advanced matching (`fbq('init', id, { em, ph })`), and only when the app's console setting has enhanced conversions on and the visitor granted marketing consent. `SaaSOSProvider` supplies the signed-in user's email automatically. An `email` or `phone` passed in `setUser` traits is now routed here instead of reaching vendors raw.
+- **Consent records.** `consent.set(state, { source?, consentString? })` also sends a record to `POST /api/v1/public/:orgId/consent` (choices, manifest version, a `bb_cid` visitor id, and the session when signed in), so the app can answer a data-subject request. The same answer restored on every page load is recorded once.
+- **Attribution reaches the server, not only the vendors.** The `bb_attr` cookie now records when the landing was captured and its origin and path (never the query). `signIn()` sends it with the auth request as `trackingAttribution`, workspace creation sends it with the create call, and checkout metadata carries `bb_attr_ts`. The server stores it on the user and the workspace, so a trial that converts a week later from a Stripe webhook can be joined to the ad click. New `getAttributionRecord()` and `attributionPayload()`. Against an older server that rejects the new fields, sign-in and workspace creation retry without them.
+- **Regional consent defaults.** `consent` also takes `{ default: 'granted', regions: { denied: ['EEA', 'GB', 'CH'] } }`; `'EEA'` expands to the 30 member states. The country comes from the tracking-config response (the edge's country header), never from the browser; an unknown country resolves to denied. With `consent: 'auto'` the client's regional default from the console applies when one is set. The rule is also sent to Google in its own `region` syntax. New `consent.effective`, `consent.default` and `consent.country` on `useTracking()`; `consent.state` is still only the visitor's answer. Checkout metadata now carries `consent.effective`, so a server-side send sees a granted regional default as granted. `EEA_COUNTRIES`, `SAFE_REGIONAL_CONSENT`, `expandRegions` and `resolveConsentDefault` are exported from `@buildbase/sdk/tracking`. Needs a server that returns `country`; against an older one every visitor resolves to denied, as before.
+
+- **`@buildbase/sdk/server`: content from your server.** A client for blogs, docs, FAQs, testimonials, rich content and collection data that authenticates with an org API token and so only runs on a server: the package's `browser` export condition resolves to a module that throws at load, and `createServerClient` refuses to construct in a browser. It uses only standard `fetch`, so it runs on Node 18+, Bun, Deno, Cloudflare Workers and edge runtimes. Every read is cached (`memoryCache` by default, `redisCache` for ioredis or node-redis, `kvCache` for Workers KV or Upstash, or your own `CacheStore`) and revalidated with `If-None-Match`, so an unchanged resource costs one `304`. Identical concurrent reads share a request, and the last good copy is served if BuildBase is unreachable. Lists return published content unless asked otherwise. See `docs/SERVER-CONTENT.md`.
+- **Content webhooks.** `handleContentWebhook(request, { secret, cache })` verifies a BuildBase webhook and drops the cached reads its event names (`blog.published`, `doc.updated`, `faq.updated`, `rich_content.updated`, `collection.record_created` and the rest in `CONTENT_WEBHOOK_EVENTS`), using the tag vocabulary in `contentTags`. `toNodeHandler()` adapts it to Express, Fastify and NestJS. Needs a server that sends content events; against an older one reads still revalidate on their TTL.
+- **`@buildbase/sdk/server/next`.** `withNextCache()` hands caching to Next's data cache (`{ next: { tags, revalidate } }` on every read) and `createNextWebhookHandler()` calls `revalidateTag`. `next` is an optional peer.
+- **Stale content is served while it refreshes.** A read past `max-age` but inside the response's `stale-while-revalidate` returns the cached copy at once and revalidates in the background, one request however many reads arrive. BuildBase sends `private, max-age=60, stale-while-revalidate=300`; `private` does not stop the client caching, since the cache is on your server.
+- FAQ collections and their questions are read by slug through `GET /api/faqs/collections/slug/:slug` (and `/faqs`), a testimonial by id through `GET /api/testimonials/:id`, and live collection data with `latest=true` alone. These need the server release that ships content delivery.
+- **`buildbase content pull`.** A CLI (`npx buildbase content pull --out content.json`) that writes all published content to one JSON file, for static sites and single-page apps with no backend. Reads the token from `BUILDBASE_API_TOKEN` only. `pullContent()` does the same from a build script.
+
+### Changed
+
+- **⚠️ Tags that honour Google Consent Mode now load before a consent answer, whatever their category.** Google Ads is a `marketing` tag, so it used to stay off the page until `consent.set({ marketing: true })`, which meant no cookieless pings and nothing for Google to model the unobserved conversions from. A vendor with `supportsConsentMode: true` (GTM, GA4, Google Ads) now loads in the denied state and stays after a refusal; every other vendor still waits for a yes in its category. `consent: 'denied'` still loads nothing at all.
+- With a Google tag configured, the SDK sets `url_passthrough: true`, and `ads_data_redaction: true` while `ad_storage` is denied (cleared on a grant).
+
+### Fixed
+
+- **A grant made in the console reaches the member.** A role's app permissions
+  were read from the workspace override or the `defaultPermissions` prop only,
+  never from the organization's matrix, so a custom permission granted to a role
+  in the console answered `false` in the app while the server said yes. The SDK
+  now resolves in the server's order: workspace override, then the organization,
+  then the SDK defaults. A key the console does not catalogue keeps the prop's
+  default.
+- **Admin holds every permission**, a custom one added after admin's list was
+  saved included, as the server and both settings screens say.
+- **The Permissions screen appears for a console-only catalogue.** It was shown
+  only when the app passed `defaultPermissions`.
+- **Saving the Permissions screen no longer strips platform permissions.** A
+  role the workspace had no override for was saved with its app keys only, so
+  an editor lost settings, members and usage access in that workspace. The
+  screen also starts from what each role resolves to now, the console's grants
+  included, and groups rows as the console does.
+- `ISettings['workspace']` declares `customPermissions`, which the server already
+  sent but the type did not name.
+- New helper `resolveRolePermissions(role, ctx)`: what one role may do, by the
+  same rules as `resolvePermissions`.
+
+- **Inviting a member never preselects `admin`.** The invite form preselects the
+  org's default role, but not when that is `admin`: an invite sent with one click
+  handed over settings, members and billing. It falls back to `viewer`, then to
+  any other role. New helper `pickDefaultRole(roles, defaultRole)`.
+- **Custom roles appear in the role dropdown.** Changing a member's role listed
+  the workspace's copy of the roles, made when it was created and never updated,
+  so a role added later in the console was missing. It lists the org's roles.
+- **`DEFAULT_ROLE_PERMISSIONS` matches the server.** It had a `member` entry,
+  which no one can hold, and no `editor`, so an editor was shown nothing the
+  server allowed. It now names `admin`, `editor` and `viewer`. Servers from this
+  release send every role's effective permissions, so these defaults apply only
+  to older servers.
+- An unknown role never falls back to `admin`, even when that is the org's
+  default role.
+- **`useSeatStatus` applies the org's member ceiling by default.** It used the
+  org's `maxWorkspaceUsers` only when the caller passed it, so an app page that
+  did not showed no limit beside the SDK's own members screen showing 1/50 for
+  the same workspace. An explicit `settingsMaxUsers` still wins.
+
+## [0.0.71] - 2026-09-25
+
+Ships with BuildBase server release 22. Every item below that says it needs a
+server from this release is listed in the README's server compatibility table,
+with what an older server answers instead.
+
+### Added
+
+- **The inbox updates live.** `useNotifications`, `<NotificationBell />` and `<NotificationInbox />` hear about new and changed items the moment they happen, over one connection per tab however many are mounted, and refetch. The connection carries no notification content, only "your inbox changed"; reads still go through the inbox routes. Reads made in another tab or on another device show at once. The one-minute poll still runs as the fallback. `live: false` turns it off. Adds `socket.io-client` as a dependency, loaded only when an inbox is shown. Requires a server that ships live inbox updates; against an older one the connection is refused and the poll carries on.
+- **A notification inbox.** Everything the app sends a user, by email, push or both, is now a record they can come back to: one item per notification, however it was delivered, with what each channel did (email opened or clicked, push clicked). New `<NotificationBell />` (unread count, inbox in a panel) and `<NotificationInbox />` (a full list with All / Unread, mark read or unread, archive, mark all read, load more), both on the new `useNotifications({ workspaceId })` hook; `workspaceId` takes an id, `'current'`, `'none'` for account notices, or nothing for everything. An item is read when opened in the inbox or when its email or push link is clicked, never by an email open. Consumers of the same scope share one list and one poll. Core `NotificationsApi` for the same outside React. Requires a server that ships the notification center.
+- **Workspace invitations.** `inviteMember(workspaceId, email, role)` reaches an address that has no account yet: the person gets an email whose link lands on the app's own auth redirect URL, signs in or registers, and accepts. The SDK handles the landing end to end (`?bb=action:invite,token:…` is read, parked for a day so the hosted sign-in's ten-minute return window cannot lose it, and resolved to an accept dialog). New on `useSaaSWorkspaces()`: `listInvitations`, `inviteMember`, `resendInvitation`, `revokeInvitation`, `myInvitations`, `acceptInvitation`, `declineInvitation`, `previewInvitation`. New hooks `useMyInvitations()` and `useWorkspaceInvitations(workspaceId)`; new `<PendingInvitations />` and `<WhenPendingInvitations>`; the workspace switcher's empty state shows the user's pending invitations, so an invite-only app's new user is no longer stuck on "No workspaces available". New SDK events `workspace:invitation-sent|accepted|declined|revoked`; new server-factory namespace `invitations` (`list`, `create`, `resend`, `revoke`); new UI switch `settings.users.invitations`.
+- **An invitee does not have to verify their email before accepting.** Following the invitation link is the proof: the token was mailed to that address and to nowhere else, so `acceptInvitation(id, { token })` lets a just-registered account in and marks it verified, the same standard a magic link sets. The SDK's own landing passes the token for you. Accepting from the in-app list carries no token, so there a verified email is still required and a stolen invitation id proves nothing.
+- Invitation errors carry `status`, a `code` and the server's fields (`currentUserCount`/`limit` on a seat limit, `retryAfterSeconds` on a resend cooldown, the scrambled `invitedEmail` on a mismatch). See `docs/ERROR_CODES.md`.
+- **The workspace `mode` no longer restricts any UI.** Settings screens, the settings sidebar and the seat-pricing displays keyed off `mode === 'personal'`, but the mode is a preset: choosing it seeds the individual settings and an admin can then change any of them and leave the mode alone. Two rules read the fields instead. `canInviteMembers` decides whether the invite surfaces show - the members screen's invite form, Resend, and the invitee's own list of invitations - and nothing else: with it off, the members already in a workspace stay listed, their roles stay editable and Remove still works, pending rows sent earlier keep Revoke, and seat pricing shows wherever the plan prices seats. `maxWorkspacesPerUser` decides whether deleting a workspace can be offered at all. Nothing changes for an app that has not overridden the preset.
+- `IWorkspaceInvitationPreview.joinable`: `false` when the organization has switched invitations off, so the landing says so before the invitee signs up rather than after. An older server omits it, which reads as joinable.
+- `useSeatStatus(workspace, { pendingInvitations })` counts live pending invitations against the ceiling, the way the server does, so an invite form at the limit gives way to the limit message instead of an invite that can only answer 402.
+- **A slug you never set up registers itself on its first send** (server release 22). `notification.send(workspaceId, 'deploy_failed', …)` with an event the console has not seen still delivers, and now also creates the event: it appears under Notifications > Custom, where the owner can rename it, attach an email template or switch it off, and members can mute it from their own settings. It counts toward the plan's custom-event limit like one made in the console; at that limit a new slug answers 403 `NOTIFICATION_EVENT_NOT_SET_UP` with a message written for the end user, and slugs the org already has keep sending. Event slugs keep `.`, `_` and `:`, so `comment_added` is stored as `comment_added` (older servers stored it as `commentadded`, which is why a slug sent from code never matched the event made in the console; those events are still found).
+- The Resend button counts down to `resendAvailableAt`, the instant the server puts on every pending invitation, rather than to a copy of the cooldown kept here. The rule stays on the server beside the 429 that enforces it, so the button cannot unlock a second early; a server that does not send the field leaves the button enabled and the 429 answers.
+
+### Changed
+
+- **⚠️ Notification toggles are each member's own.** The Notifications settings screen used to change the workspace's settings for everyone, so one member turning an email off turned it off for the whole workspace. Every member now sets their own under "Your notifications", and a member who may edit workspace settings also sets "Workspace defaults": what everyone gets until they choose otherwise, plus a Required switch that stops members changing an event. Existing workspace settings become those defaults, so nothing changes for anyone until they choose. New `getMyNotificationPreferences` and `updateMyNotificationPreferences` on `WorkspaceApi` (`null` for a channel goes back to the default; a required event answers 409 `NOTIFICATION_PREFERENCE_REQUIRED`). Turning both channels off does not remove an event from the inbox: the toggles choose how you are interrupted, not whether it is recorded.
+- **⚠️ The members screen's invite form now sends an invitation instead of adding an existing account.** The address no longer needs an account, and the row appears under the form as pending (with Resend and Revoke) until accepted. `addUser` is unchanged and still adds an existing account at once; code that calls it keeps its behaviour.
+- **A pending invitation is billed as a seat** until it is accepted, declined, revoked or expires. The seat block on the members screen counts pending invitations and says so.
+- Requires a server that ships workspace invitations; on an older server the invite form answers 404.
+
+### Fixed
+
+- **A member who is refused something is no longer signed out.** Server release 22 answers a signed-in member's forbidden request with 403 rather than 401; the SDK signs out only on 401, so a viewer opening the members or billing screens now sees "Access Restricted" and keeps their session. On an older server the 401 still ends the session, which is why those screens are not requested for roles that cannot read them.
+- Seat-limit refusals carry `SEAT_LIMIT_REACHED` from every door on server release 22, including a direct `addUser` into a full workspace and an accept that finds the workspace full, so the seat block renders from the code rather than the status.
+- **⚠️ `invalidateCreditBalance()`, `invalidateSubscription()` and `invalidateQuotaUsage()` imported from `@buildbase/sdk` now refresh the UI.** The root entry and `@buildbase/sdk/react` are separate bundles, and each had its own listener set, so a call from the root entry notified nobody: a credits badge kept its old number after every spend and purchase, with no error. The listener sets now live in a `Symbol.for` registry shared by every copy of the SDK in the page, as the tracking context already does.
+- **`useCreditBalance(workspaceId)`, `useSubscription(workspaceId)` and `useAllQuotaUsage(workspaceId)` refetch on invalidation wherever they are used.** Only the copies inside the built-in context providers listened before, so a component using the hook directly, as the `useCreditBalance` docs example does, never refreshed. The providers no longer subscribe separately, so nothing refetches twice.
+
 ## [0.0.70] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -21,6 +21,7 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - [Trial Gates](#-trial-gates)
 - [Push Notifications](#-push-notifications)
 - [Notifications](#-notifications)
+- [Content from your server](#️-content-from-your-server)
 - [Connected Agents](#-connected-agents)
 - [Devices & Sessions](#-devices--sessions)
 - [User Management](#-user-management)
@@ -106,6 +107,28 @@ Everything the SDK lets you configure, override, or extend — one row per knob,
 npm install @buildbase/sdk react@^19.0.0 react-dom@^19.0.0
 ```
 
+### Server compatibility
+
+The SDK talks to a BuildBase server, and a few features need a server release
+that has them. Everything else works on any server. Where a feature needs a
+newer server than yours, the SDK degrades the way the table says rather than
+breaking.
+
+| Feature                                                                                  | SDK    | Server           | On an older server                                              |
+| ---------------------------------------------------------------------------------------- | ------ | ---------------- | --------------------------------------------------------------- |
+| Workspace invitations (`inviteMember`, `<PendingInvitations />`, the landing)            | 0.0.71 | release 22       | The invite form answers 404                                     |
+| Notification inbox (`useNotifications`, `<NotificationBell />`, `<NotificationInbox />`) | 0.0.71 | release 22       | The inbox routes answer 404                                     |
+| Live inbox updates                                                                       | 0.0.71 | release 22       | The socket is refused; the one-minute poll carries on           |
+| Per-member notification preferences                                                      | 0.0.71 | release 22       | The screen edits the workspace defaults, as before              |
+| A slug not set up registers itself on first send                                         | any    | release 22       | The notification is sent unregistered, push and inbox only      |
+| Forbidden requests answer 403, so a viewer stays signed in                               | any    | release 22       | A 401 ends the session                                          |
+| Content from your server (`@buildbase/sdk/server`: blogs, docs, rich content, lists)     | next   | any              |                                                                 |
+| FAQ collections by slug, `testimonials.get(id)`, collection data without a `version`     | next   | content delivery | 404 (FAQ, testimonial) or 400 (collection data)                 |
+| Content reads answered `304` from BuildBase's cache, with `stale-while-revalidate`       | next   | content delivery | Every read gets the full body; the client caches on its own TTL |
+| Content webhooks (`handleContentWebhook`, `createNextWebhookHandler`)                    | next   | content delivery | No events arrive; cached reads expire on their TTL              |
+| Tracking (`tracking` prop, `/tracking` entry)                                            | 0.0.68 | any              |                                                                 |
+| `signOut()` revokes the session on the server                                            | 0.0.70 | any              |                                                                 |
+
 ## Quick Start
 
 ### 1. Import CSS
@@ -870,7 +893,7 @@ Send email and push notifications to workspace members. The system has three lay
 
 - **System notifications** — Automatically triggered by platform events (workspace invite, payment failed, trial ending, etc.). Managed by the developer in the admin dashboard.
 - **Custom notifications** — Defined by the developer, triggered from app code via SDK. Can be made user-configurable.
-- **Ad-hoc notifications** — Send push notifications with any event slug without pre-registering it. No event setup needed — just pass `title`, `message`, and optionally `icon`, `image`, `url`. Email requires a registered event with a linked template.
+- **Ad-hoc notifications** — Send with any event slug without setting it up first: pass `title`, `message`, and optionally `icon`, `image`, `url`. On server release 22 the first send registers the event, so it shows in the console and counts toward the plan's custom events. Email requires an event with a linked template.
 
 ### Sending Notifications (Server-Side)
 
@@ -910,7 +933,9 @@ await notification.send(workspaceId, 'deployment_success', userId, {
 });
 ```
 
-> **Note:** Ad-hoc events support push only. Email requires a registered event with a linked email template.
+> **Note:** An ad-hoc send delivers push and the inbox item. Email starts once an email template is attached to the event in the console.
+>
+> On server release 22 the first send registers the event: it appears under **Notifications > Custom** for the owner to configure and for members to mute, and it counts toward the plan's custom-event limit. At that limit a new slug answers `403 NOTIFICATION_EVENT_NOT_SET_UP` with a message meant for the end user; slugs the org already has keep sending. Slugs keep `.`, `_` and `:` (`comment_added` stays `comment_added`).
 
 ### Push Options
 
@@ -1124,6 +1149,34 @@ interface NotificationEvent {
 }
 ```
 
+## 🗂️ Content from your server
+
+Blogs, docs, FAQs, testimonials, rich content and collection data are read with an
+**org API token**, so they are read on your server or at build time, never in a browser.
+`@buildbase/sdk/server` reads them, caches every read, revalidates with ETags, and
+drops what changed when BuildBase sends a content webhook. It runs on Node 18+, Bun,
+Deno, Cloudflare Workers and edge runtimes, and refuses to load in a browser.
+
+```ts
+import { createServerClient } from '@buildbase/sdk/server';
+
+const content = createServerClient({
+  serverUrl: 'https://api.console.buildbase.app',
+  apiToken: process.env.BUILDBASE_API_TOKEN!, // <orgId>:<secret>, read-only content-reader role
+});
+
+const posts = await content.blogs.list({ limit: 20 });
+const refund = await content.richContent.get('refund-policy');
+const releases = await content.collections.data('release-notes');
+```
+
+- **A server (any framework):** the client above, plus `handleContentWebhook` (standard `Request`/`Response`) or `toNodeHandler(...)` for Express, Fastify and NestJS.
+- **No backend (static sites, single-page apps):** `npx buildbase content pull --out content.json` in CI; the token never leaves CI.
+- **Next.js:** `withNextCache()` and `createNextWebhookHandler()` from `@buildbase/sdk/server/next` hand caching to Next's tag cache.
+- **Another language:** the same HTTP rules (`If-None-Match`, bracket-encoded filters, HMAC-signed webhooks).
+
+The full guide, with Express, Hono/Workers, Next and Python examples, is [`docs/SERVER-CONTENT.md`](docs/SERVER-CONTENT.md).
+
 ## 🌐 Internationalization (i18n)
 
 The SDK supports 8 locales with ICU MessageFormat for plurals, selects, and number formatting.
@@ -1407,7 +1460,14 @@ function WorkspaceManager() {
     updateWorkspace, // Update workspace
     deleteWorkspace, // Delete workspace
     getUsers, // Get workspace users
-    addUser, // Add user to workspace
+    addUser, // Add an EXISTING account to the workspace (404 when the address has none)
+    inviteMember, // Invite an email address that may have no account yet
+    listInvitations, // The workspace's invitations, pending first
+    resendInvitation, // Send one again (five-minute cooldown)
+    revokeInvitation, // Withdraw a pending invitation
+    myInvitations, // The signed-in user's own pending invitations
+    acceptInvitation, // Accept one (joins the workspace)
+    declineInvitation, // Decline one
     removeUser, // Remove user from workspace
     updateUser, // Update user role/permissions
     getFeatures, // Get all available features
@@ -1423,15 +1483,92 @@ function WorkspaceManager() {
     await createWorkspace('My Workspace', 'https://example.com/logo.png');
   };
 
-  // Example: Add user to workspace
+  // Example: Add an existing account to the workspace
   const handleAddUser = async () => {
     await addUser(currentWorkspace._id, 'user@example.com', 'member');
   };
 
+  // Example: Invite someone who may not have an account yet
+  const handleInvite = async () => {
+    await inviteMember(currentWorkspace._id, 'teammate@example.com', 'editor');
+  };
+
   return <div>{/* Your workspace UI */}</div>;
 }
 ```
 
+### Workspace invitations
+
+`inviteMember` reaches an address that has no account yet. The person gets an
+email whose link lands on your app's auth redirect URL (the same one the app
+returns to after login), signs in or registers, and accepts. A pending
+invitation holds a seat until it is accepted, declined, revoked or expires
+(after 14 days). The members settings screen sends invitations and lists the
+pending ones with Resend and Revoke; nothing else is needed for the admin's
+side.
+
+The invitee's side is handled for you too: the SDK reads the link, shows what
+it resolves to, offers sign-in when needed, and accepts on the user's behalf.
+A brand-new invitee is not asked to verify their email first, because arriving
+with the link already proves the address.
+An invite-only app (workspace settings with `autoCreateFirst: false`) shows the
+user's pending invitations in the workspace switcher's empty state instead of
+"No workspaces available". To place them on your own screen:
+
+```tsx
+import { PendingInvitations, WhenPendingInvitations } from '@buildbase/sdk/react';
+
+function NoWorkspaceScreen() {
+  return (
+    <WhenPendingInvitations fallbackComponent={<p>Ask your team for an invitation.</p>}>
+      <PendingInvitations onAccepted={ws => console.log('joined', ws.name)} />
+    </WhenPendingInvitations>
+  );
+}
+```
+
+`useMyInvitations()` and `useWorkspaceInvitations(workspaceId)` are the hooks
+behind those. Errors from every invitation call carry `status` and a `code`
+(`SEAT_LIMIT_REACHED` with `currentUserCount` and `limit`,
+`INVITATION_RATE_LIMITED` with `retryAfterSeconds`,
+`INVITATION_EMAIL_MISMATCH` with the scrambled `invitedEmail`,
+`EMAIL_NOT_VERIFIED`, `INVITATION_EXPIRED`, `INVITATION_ALREADY_HANDLED`); see
+`docs/ERROR_CODES.md`.
+
+### Notification inbox
+
+Everything your app sends a user, by email, push or both, is kept for them as
+an inbox they can come back to. One notification is one item however it was
+delivered, and the item says what each channel did (email opened or clicked,
+push clicked). Opening an email does not mark the item read; opening it in the
+inbox or clicking its email or push link does. Sign-in codes, magic links and
+password resets are never in it.
+
+```tsx
+import { NotificationBell, NotificationInbox } from '@buildbase/sdk/react';
+
+function Header() {
+  // Unread count on a bell, the inbox in a panel. Opening it marks the items
+  // seen, which clears the highlight without reading anything.
+  return <NotificationBell />;
+}
+
+function NotificationsPage() {
+  // A full page, for the current workspace only. Omit workspaceId for every
+  // workspace, or pass 'none' for account notices that belong to none.
+  return <NotificationInbox workspaceId="current" />;
+}
+```
+
+`useNotifications(options)` is the hook behind both, for your own UI: items,
+`counts.unread` and `counts.unseen`, `markRead`, `markUnread`, `archive`,
+`markAllRead`, `markSeen` and `loadMore`. Every consumer of the same scope
+shares one list, so a bell and an inbox page make one request and a read in
+either updates both. New items are picked up by polling the count every
+minute while the tab is visible (`pollIntervalMs`, 0 to turn it off). A user
+only ever sees their own notifications; the whole workspace's history is in
+the console.
+
 ## 💰 Public Pricing (No Login)
 
 Display subscription plans and pricing on public pages (e.g. marketing site, pricing page) without requiring users to log in.

package/dist/cli.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{mkdir as e,writeFile as t}from"node:fs/promises";import{resolve as o,dirname as n}from"node:path";const s=["blogs","docs","faqs","testimonials","richContent","collections"];async function r(e){const t=[];for(let o=1;o<=1e4;o++){const n=await e(o);t.push(...n.docs);if(!(n.hasNextPage??(void 0!==n.totalPages&&o<n.totalPages))||0===n.docs.length)break}return t}const a=`Usage: buildbase content pull --out <file> [options]\n\nFetch published content once and write it to a JSON file (run it in CI or at build time).\n\nOptions:\n  --out <file>               where to write the JSON (required)\n  --modules <list>           comma-separated: ${s.join(",")} (default: all)\n  --collections <slugs>      collection slugs to pull records for (default: every live collection)\n  --server-url <url>         overrides BUILDBASE_SERVER_URL\n  --page-size <n>            page size while paging lists (default 100)\n\nEnvironment:\n  BUILDBASE_API_TOKEN        org API token, <orgId>:<secret> (required)\n  BUILDBASE_SERVER_URL       e.g. https://api.console.buildbase.app`;function i(e){return(e??"").split(",").map(e=>e.trim()).filter(Boolean)}function l(e={}){const t=Math.max(1,e.maxEntries??1e3),o=new Map,n=new Map,s=e=>{const t=o.get(e);t&&(o.delete(e),((e,t)=>{for(const o of t.tags){const t=n.get(o);t&&(t.delete(e),0===t.size&&n.delete(o))}})(e,t.entry))};return{async get(e){const t=o.get(e);if(t){if(!(t.expiresAt<=Date.now()))return o.delete(e),o.set(e,t),t.entry;s(e)}},async set(e,r,a){s(e),o.set(e,{entry:r,expiresAt:Date.now()+1e3*a});for(const t of r.tags){let o=n.get(t);o||n.set(t,o=new Set),o.add(e)}for(;o.size>t;){const e=o.keys().next().value;if(void 0===e)break;s(e)}},async delete(e){s(e)},async deleteByTag(e){const t=n.get(e);if(t)for(const e of[...t])s(e)}}}function c(e,t,o){if(null!=o)if(Array.isArray(o))o.forEach((o,n)=>c(e,`${t}[${n}]`,o));else if("object"!=typeof o)e.append(t,String(o));else for(const[n,s]of Object.entries(o))c(e,`${t}[${n}]`,s)}const u="buildbase:all",d=e=>`buildbase:${e}`,f=(e,t)=>`buildbase:${e}:${t}`,p=(e,t)=>`buildbase:${e}:id:${t}`,h=e=>`buildbase:collection:${e}`;new Set(["blog.published","blog.updated","blog.unpublished","blog.deleted","doc.published","doc.updated","doc.unpublished","doc.deleted","faq.updated","faq_collection.updated","testimonial.updated","testimonial.deleted","rich_content.updated","rich_content.deleted","collection.version_published","collection.record_created","collection.record_updated","collection.record_deleted"]);class g extends Error{constructor(e,t,o,n){super(e),this.status=t,this.url=o,this.body=n,this.name="BuildBaseContentError"}}const m=/^[0-9a-f]{24}$/i,w=new WeakMap;function b(e){return Array.isArray(e)?e:e&&"object"==typeof e&&Array.isArray(e.docs)?e.docs:[]}function y(e){const t=e.split("/").filter(Boolean);return t[t.length-1]??e}function v(e={},t={}){const o={...t,...e.filter};return{$page:e.page,$limit:e.limit,filter:Object.keys(o).length>0?o:void 0,sort:e.sort}}function $(e){if("undefined"!=typeof window&&"undefined"!=typeof document)throw new Error("@buildbase/sdk/server holds your org API token and must only run on a server. Import it from server code (an API route, a server component, a build script), never from code that ships to the browser.");if(!e||"string"!=typeof e.serverUrl||!e.serverUrl)throw new Error("createServerClient: `serverUrl` is required");if("string"!=typeof e.apiToken||!e.apiToken.includes(":"))throw new Error("createServerClient: `apiToken` must be an org API token of the form <orgId>:<secret> (console, Settings, API tokens)");const t=e.serverUrl.replace(/\/+$/,""),o=e.apiToken,n=o.slice(0,o.indexOf(":")),s=!1===e.cache?null:e.cache??l(),r=e.fetch??((e,t)=>globalThis.fetch(e,t)),a=e.timeoutMs??1e4,i=e.defaultTtlSeconds??60,$=Math.max(e.retainSeconds??86400,1),q=e.staleOnError??!0,U=new Map,E=(e,t)=>(e&&"object"==typeof e&&w.set(e,t),e);async function I(n,s,i){const l="function"==typeof e.requestInit?e.requestInit({path:n,tags:s}):e.requestInit??{},c=new Headers(l.headers);c.set("Authorization",`Bearer ${o}`),c.set("Accept","application/json"),i&&c.set("If-None-Match",i);const u=new AbortController,d=setTimeout(()=>u.abort(),a);try{return await r(`${t}${n}`,{...l,method:"GET",headers:c,signal:l.signal??u.signal})}finally{clearTimeout(d)}}async function _(e){const o=`${e.path}${function(e){if(!e)return"";const t=new URLSearchParams;for(const o of Object.keys(e).sort())c(t,o,e[o]);t.sort();const o=t.toString();return o?`?${o}`:""}(e.query)}`,r=`${n}:${o}`,a=s?await s.get(r):void 0,l=Date.now();if(a&&a.freshUntil>l)return E(a.data,a.tags);const d=()=>{const n=async function(){let n;try{n=await I(o,e.tags,a?.etag),304!==n.status||a||(n=await I(o,e.tags))}catch(e){if(q&&a)return E(a.data,a.tags);throw new g(`BuildBase request failed: ${e instanceof Error?e.message:String(e)}`,0,`${t}${o}`)}const l=function(e,t){const o=e.headers.get("cache-control");if(!o)return t;const n=o.toLowerCase().split(",").map(e=>e.trim());if(n.includes("no-store"))return null;if(n.includes("no-cache"))return 0;const s=n.find(e=>e.startsWith("max-age="));if(s){const e=Number(s.slice(8));if(Number.isFinite(e)&&e>=0)return e}return t}(n,i),c=function(e){const t=e.headers.get("cache-control");if(!t)return 0;const o=t.toLowerCase().split(",").map(e=>e.trim()).find(e=>e.startsWith("stale-while-revalidate=")),n=o?Number(o.slice(23)):0;return Number.isFinite(n)&&n>0?n:0}(n);if(304===n.status&&a){const e={...a,etag:n.headers.get("etag")??a.etag,freshUntil:Date.now()+1e3*(l??0),staleUntil:c>0?Date.now()+1e3*((l??0)+c):void 0};return s&&await s.set(r,e,$),E(a.data,a.tags)}if(404===n.status&&e.nullOnNotFound)return null;if(!n.ok){const s=await n.text().catch(()=>"");let r=s;try{r=s?JSON.parse(s):void 0}catch{}if(q&&a&&401!==n.status&&403!==n.status)return E(a.data,a.tags);const i=r?.message??`BuildBase responded ${n.status} for ${e.path}`;throw new g(i,n.status,`${t}${o}`,r)}const d=(f=await n.json().catch(()=>null),f&&"object"==typeof f&&!Array.isArray(f)&&"data"in f&&"success"in f&&!("docs"in f)?f.data:f);var f;if(null==d&&e.nullOnNotFound)return null;const p=e.transform?e.transform(d):d,h=[...new Set([...e.tags,...e.tagsFrom?e.tagsFrom(p):[],u])];s&&null!==l&&await s.set(r,{data:p,etag:n.headers.get("etag")??void 0,freshUntil:Date.now()+1e3*l,staleUntil:c>0?Date.now()+1e3*(l+c):void 0,tags:h},Math.max($,l));return E(p,h)}();return U.set(r,n),n.then(()=>U.delete(r),()=>U.delete(r)),n};if(a&&void 0!==a.staleUntil&&a.staleUntil>l)return U.has(r)||d().catch(()=>{}),E(a.data,a.tags);const f=U.get(r);return f||d()}const A=e=>t=>{const o=[];return t?._id&&o.push(p(e,t._id)),t?.slug&&o.push(f(e,t.slug)),o};function S(e,t){const o=d(t);return{list:(t={})=>_({path:`/api/${e}`,query:v(t,t.includeDrafts?{}:{published:!0}),tags:[o]}),get:o=>_({path:`/api/${e}/${encodeURIComponent(o)}`,tags:[p(t,o)],tagsFrom:A(t),nullOnNotFound:!0}),byPath:(o,n={})=>_({path:`/api/${e}/path`,query:{path:o,draftPreview:!!n.draftPreview||void 0},tags:[f(t,y(o))],tagsFrom:A(t),nullOnNotFound:!0}),tree:(t={})=>_({path:`/api/${e}/folders/tree`,query:{folder:t.folder},tags:[o]}),tags:(t={})=>_({path:`/api/${e}/tags`,query:v(t),tags:[o]}),authors:(t={})=>_({path:`/api/${e}/authors`,query:v(t),tags:[o]})}}const B=d("faq_collection");async function O(e){const t=m.test(e);return _({path:t?`/api/faqs/collections/${encodeURIComponent(e)}`:`/api/faqs/collections/slug/${encodeURIComponent(e)}`,tags:[t?p("faq_collection",e):f("faq_collection",e)],tagsFrom:A("faq_collection"),nullOnNotFound:!0})}return{blogs:S("blogs","blog"),docs:S("docs","doc"),faqs:{collections:(e={})=>_({path:"/api/faqs/collections",query:v(e,{archived:!1}),tags:[B]}),collection:O,async questions(e){const t=m.test(e);if(t&&!await O(e))return[];return await _({path:t?`/api/faqs/collections/${encodeURIComponent(e)}/faqs`:`/api/faqs/collections/slug/${encodeURIComponent(e)}/faqs`,query:{pagination:!1},tags:[d("faq"),t?p("faq_collection",e):f("faq_collection",e)],transform:e=>b(e).filter(e=>!e.archived),nullOnNotFound:!0})??[]}},testimonials:{list:(e={})=>_({path:"/api/testimonials",query:v(e,e.includeUnpublished?{archived:!1}:{published:!0,archived:!1}),tags:[d("testimonial")]}),get:e=>_({path:`/api/testimonials/${encodeURIComponent(e)}`,tags:[p("testimonial",e)],nullOnNotFound:!0})},richContent:{get:e=>_({path:`/api/rich-content/slug/${encodeURIComponent(e)}`,tags:[f("rich_content",e)],tagsFrom:A("rich_content"),nullOnNotFound:!0}),list:(e={})=>_({path:"/api/rich-content",query:v(e,{archived:!1}),tags:[d("rich_content")]})},collections:{list:(e={})=>_({path:"/api/collections",query:v(e,{archived:!1}),tags:[d("collection")]}),data(e,t={}){const o=void 0===t.version;return _({path:`/api/collections/data/${encodeURIComponent(e)}`,query:o?{latest:!0}:{version:t.version},tags:[h(e)],transform:e=>b(e).filter(e=>!e.archived)})}},async revalidate(e){s&&await s.deleteByTag(e)},async revalidateAll(){s&&await s.deleteByTag(u)},cache:s}}(async function(l){let c;try{c=function(e){const[t,o,...n]=e;if(!t||"--help"===t||"-h"===t||"help"===t)return{command:"help"};if("content"!==t||"pull"!==o)throw new Error(`Unknown command: ${[t,o].filter(Boolean).join(" ")}`);const r=new Map;for(let e=0;e<n.length;e++){const t=n[e];if("--help"===t||"-h"===t)return{command:"help"};if(!t.startsWith("--"))throw new Error(`Unexpected argument: ${t}`);const o=t.indexOf("=");if(o>-1)r.set(t.slice(2,o),t.slice(o+1));else{const o=n[e+1];if(void 0===o||o.startsWith("--"))throw new Error(`Missing value for ${t}`);r.set(t.slice(2),o),e++}}const a=new Set(["out","modules","collections","server-url","page-size"]);for(const e of r.keys())if(!a.has(e))throw new Error(`Unknown option: --${e}`);const l=r.get("out");if(!l)throw new Error("--out <file> is required");let c,u;if(r.has("modules")){const e=i(r.get("modules")),t=e.filter(e=>!s.includes(e));if(t.length)throw new Error(`Unknown module(s): ${t.join(", ")}. Use: ${s.join(", ")}`);c=e}if(r.has("page-size")&&(u=Number(r.get("page-size")),!Number.isInteger(u)||u<1))throw new Error("--page-size must be a positive integer");return{command:"content-pull",out:l,modules:c,collections:r.has("collections")?i(r.get("collections")):void 0,serverUrl:r.get("server-url"),pageSize:u}}(l)}catch(e){return console.error(`buildbase: ${e.message}\n\n${a}`),2}if("help"===c.command)return console.log(a),0;const u=process.env.BUILDBASE_API_TOKEN,d=c.serverUrl??process.env.BUILDBASE_SERVER_URL??process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL;if(!u)return console.error("buildbase: set BUILDBASE_API_TOKEN to an org API token (<orgId>:<secret>)"),2;if(!d)return console.error("buildbase: set BUILDBASE_SERVER_URL (for example https://api.console.buildbase.app)"),2;try{const a=$({serverUrl:d,apiToken:u,cache:!1}),i=await async function(e,t={}){const o=new Set(t.modules??s),n=t.pageSize??100,a={generatedAt:(new Date).toISOString()};if(o.has("blogs")&&(a.blogs=await r(t=>e.blogs.list({page:t,limit:n}))),o.has("docs")&&(a.docs=await r(t=>e.docs.list({page:t,limit:n}))),o.has("faqs")){const t=await r(t=>e.faqs.collections({page:t,limit:n}));a.faqs=[];for(const o of t)a.faqs.push({...o,questions:await e.faqs.questions(o._id)})}if(o.has("testimonials")&&(a.testimonials=await r(t=>e.testimonials.list({page:t,limit:n}))),o.has("richContent")&&(a.richContent=await r(t=>e.richContent.list({page:t,limit:n}))),o.has("collections")){const o=t.collections??(await r(t=>e.collections.list({page:t,limit:n}))).map(e=>e.slug);a.collections={};for(const t of o)a.collections[t]=await e.collections.data(t)}return a}(a,{modules:c.modules,collections:c.collections,pageSize:c.pageSize}),l=o(process.cwd(),c.out);await e(n(l),{recursive:!0}),await t(l,`${JSON.stringify(i,null,2)}\n`,"utf8");const f=Object.entries(i).filter(([e])=>"generatedAt"!==e).map(([e,t])=>`${e}: ${Array.isArray(t)?t.length:Object.keys(t).length}`).join(", ");return console.log(`buildbase: wrote ${c.out} (${f})`),0}catch(e){return e instanceof g&&(401===e.status||403===e.status)?(console.error(`buildbase: the API token was refused (${e.status}). Check BUILDBASE_API_TOKEN and that its role can read content.`),1):(console.error(`buildbase: ${e.message}`),1)}})(process.argv.slice(2)).then(e=>process.exit(e),e=>{console.error(e),process.exit(1)});