@buildbase/sdk 0.0.54 → 0.0.56

package/README.md

@@ -7,6 +7,7 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 ## 📑 Table of Contents
 
 - [Features](#-features)
+- [Customization Map](#-customization-map)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [UI Configuration](#️-ui-configuration)
@@ -19,6 +20,8 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - [Trial Gates](#-trial-gates)
 - [Push Notifications](#-push-notifications)
 - [Notifications](#-notifications)
+- [Connected Agents](#-connected-agents)
+- [Devices & Sessions](#-devices--sessions)
 - [User Management](#-user-management)
 - [Workspace Management](#-complete-workspace-management)
 - [Public Pricing (No Login)](#-public-pricing-no-login)
@@ -52,6 +55,8 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - **⏳ Trial Gates** - `WhenTrialing`, `WhenNotTrialing`, `WhenTrialEnding` components + `useTrialStatus` hook
 - **🔔 Push Notifications** - Browser push notifications with `usePushNotifications` hook, auto-triggers for billing events, and campaign management
 - **📬 Notifications** - Email + push notification system with per-event channel control, workspace preferences, and server-side `notification.send()` API
+- **🔌 Connected Agents** - `<ConnectedAgents />` screen to list/revoke authorized AI agents, plus a built-in "Connect an agent" setup guide (ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline) driven by an `mcp` provider prop
+- **📱 Devices & Sessions** - `<Devices />` and `<Sessions />` screens (Browser · OS, location + IP) to rename / sign out / remove devices and revoke sessions; server-side `bb.devices` / `bb.sessions`, per-action show/hide + label overrides
 - **💺 Seat-Based Pricing** - Per-seat billing with included seats, billable seat tracking, and seat limit enforcement
 - **💱 Multi-Currency** - Per-currency pricing variants with workspace billing currency lock
 - **🤝 Affiliate Tracking** - Pass referral data to Stripe checkout via `getCheckoutStripeParams` prop (Rewardful, Endorsely, FirstPromoter, etc.)
@@ -66,6 +71,32 @@ Also works server-side (Next.js API routes, Express, Hono) — see [Server-Side
 - **🌐 Internationalization (i18n)** - 8 locales (en, es, fr, de, ja, zh, hi, ar), ICU MessageFormat, RTL support, native numerals
 - **🏠 Workspace Modes** - Personal (solo B2C) or Platform (multi-user B2B), configured from admin dashboard
 
+## 🎨 Customization Map
+
+Everything the SDK lets you configure, override, or extend — one row per knob, so you can see the whole surface before reading any deep-dive section. The philosophy throughout: **safe defaults, everything overridable, the SDK accelerates but never gates.**
+
+| What you customize                     | How                                                                                                                                                                        | Where to read more                                                                |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Provider setup & workspace behavior    | `<SaaSOSProvider>` / `<BuildBaseProvider>` props (`serverUrl`, `orgId`, `locale`, workspace auto-create, redirects)                                                        | [Configuration Reference](#️-configuration-reference)                              |
+| Which SDK UI renders at all            | `ui` prop: hide/show settings sections, workspace switcher, per-screen toggles                                                                                             | [UI Configuration](#️-ui-configuration) · `docs/UI-CONFIG.md`                      |
+| Every user-facing string               | `ui.messages` deep-override (e.g. rename "Subscription" → "Billing"), per-locale                                                                                           | [UI Configuration](#️-ui-configuration)                                            |
+| Language & number systems              | `locale` prop — 8 locales, ICU plurals, RTL (`ar`), native numerals                                                                                                        | [Internationalization](#-internationalization-i18n)                               |
+| Look & feel                            | CSS custom properties (`--primary`, `--destructive`, …) — semantic tokens, light/dark, no palette lock-in                                                                  | `docs/THEMING.md`                                                                 |
+| Date/number formats                    | `ui.formats` (`Intl` options passed through)                                                                                                                               | `docs/UI-CONFIG.md`                                                               |
+| Conditional UI                         | Gate components: `WhenAuthenticated`, `WhenPermission`, `WhenWorkspaceFeatureEnabled`, `WhenSubscription`, `WhenTrialing`, `WhenQuotaAvailable`, `WhenCreditsAvailable`, … | [Subscription Gates](#-subscription-gates) & siblings                             |
+| Checkout behavior                      | `getCheckoutStripeParams` (affiliate/referral params), plan-picker behavior config                                                                                         | [Affiliate Tracking](#affiliate--referral-tracking)                               |
+| Connect-an-agent guide                 | `mcp` prop (`url`, `name`, `docsUrl`, `clients`, `prompt`) → in-app setup guide + `<ConnectedAgents />` screen                                                             | [Connected Agents](#-connected-agents)                                            |
+| Devices & sessions screens             | `<Devices />` / `<Sessions />` props (`showRename`/`showSignOut`/`showRemove`, `*Label`) or `ui.settings.devices` toggles                                                  | [Devices & Sessions](#-devices--sessions)                                         |
+| Error presentation                     | `ui.errorBoundary`, centralized `handleError` reporting                                                                                                                    | [Error Handling](#️-error-handling)                                                |
+| React-free server access               | `BuildBase()` factory — workspaces, usage, credits, notifications from API routes/jobs                                                                                     | [Server-Side Usage](#server-side-usage)                                           |
+| Agent discovery surface                | `createAgentStack` / `resolveAgentPath`: robots.txt, llms.txt, `.well-known/*`, all documents overridable (e.g. `config.llmsTxt`)                                          | [Agent Readiness](#agent-readiness-discovery) · `docs/MCP-AND-AGENT-READINESS.md` |
+| MCP tools                              | `builtinTools` (`'readonly'`/`'all'`/`false`/include/exclude) + your own via `defineMcpTool` (custom tools override built-ins)                                             | [MCP Server](#mcp-server-buildbasesdkmcp)                                         |
+| MCP resources & prompts                | Opt-in `builtinResources` catalog + `defineMcpResource`/`defineMcpResourceTemplate`/`defineMcpPrompt`                                                                      | [MCP Server](#mcp-server-buildbasesdkmcp)                                         |
+| MCP auth & hardening                   | `auth.verify` (your token format) or `buildbaseAuth` preset; `rateLimit`, `cors`, `allowedOrigins`, `formatToolError`                                                      | `docs/MCP-AND-AGENT-READINESS.md`                                                 |
+| Per-request context for your MCP tools | `context(auth, req)` factory → `ctx.custom` (your DB, services)                                                                                                            | [MCP Server](#mcp-server-buildbasesdkmcp)                                         |
+| Money display                          | `formatMinorAmountIntl`/`formatCents`/`getCurrencyDecimals` — full ISO 4217 (0/2/3-decimal currencies)                                                                     | [Multi-Currency](#-multi-currency--pricing-utilities)                             |
+| Webhooks from the platform             | `verifyWebhookSignature` (HMAC, timing-safe)                                                                                                                               | [Webhook Verification](#webhook-verification)                                     |
+
 ## Installation
 
 ```bash
@@ -87,6 +118,7 @@ import '@buildbase/sdk/css';
 // components/provider.tsx
 'use client';
 
+// BuildBaseProvider is an identical brand-aligned alias — prefer it in new code
 import { SaaSOSProvider } from '@buildbase/sdk/react';
 import { ApiVersion } from '@buildbase/sdk';
 
@@ -224,6 +256,7 @@ The optional `ui` prop on `SaaSOSProvider` controls which parts of the SDK UI ar
       // Per-screen feature toggles
       profile: { currency: false, timezone: false },
       security: { passkeyDelete: false },
+      devices: { forget: false, sessions: false }, // hide "Remove" + the sessions block
       general: { iconEditor: false },
       users: { invite: false, seatPricing: false },
       subscription: { cancel: false, invoicesTab: false, planDetails: false },
@@ -248,13 +281,13 @@ The optional `ui` prop on `SaaSOSProvider` controls which parts of the SDK UI ar
     // Default fallback strings for the top-level error boundary
     errorBoundary: { title: 'Oops!', retryLabel: 'Retry' },
 
-    // Date formatting for SDK-rendered dates (passkeys, connected agents)
+    // Date formatting for SDK-rendered dates (passkeys, connected agents, devices)
     formats: { date: { dateStyle: 'short' } },
   }}
 >
 ```
 
-Section keys match the `SettingsScreen` values: `profile`, `security`, `connected-agents`, `general`, `users`, `subscription`, `usage`, `credits`, `features`, `notifications`, `permissions`, `danger`. Hidden sections are removed from the sidebar (empty groups collapse) and unreachable via deep links or `defaultSection` — the dialog falls back to the first enabled section.
+Section keys match the `SettingsScreen` values: `profile`, `security`, `devices`, `connected-agents`, `general`, `users`, `subscription`, `usage`, `credits`, `features`, `notifications`, `permissions`, `danger`. Hidden sections are removed from the sidebar (empty groups collapse) and unreachable via deep links or `defaultSection` — the dialog falls back to the first enabled section.
 
 **Per-dialog override** — `WorkspaceSettingsDialog` accepts its own `ui` prop, deep-merged over the global config, so one app can render differently-configured dialogs:
 
@@ -283,7 +316,7 @@ function MembersPanel() {
 
 `useUIConfig()` gives you the raw `ui` object if you only need the config values; `mergeUIConfig(base, override)` is the deep-merge used for per-dialog overrides.
 
-📖 **Full guide with the complete toggle reference, precedence rules, and recipes (single-tenant, external billing, white-label, read-only): [docs/UI-CONFIG.md](./docs/UI-CONFIG.md)**
+📖 **Full guide with the complete toggle reference, precedence rules, and recipes (single-tenant, external billing, white-label, read-only): [docs/UI-CONFIG.md](https://unpkg.com/@buildbase/sdk/docs/UI-CONFIG.md)**
 
 ## 🔐 Authentication
 
@@ -346,9 +379,16 @@ openWorkspaceSettings('users'); // Workspace members
 openWorkspaceSettings('subscription'); // Plan & Billing
 openWorkspaceSettings('usage'); // Quota usage dashboard
 openWorkspaceSettings('features'); // Feature toggles
+openWorkspaceSettings('connected-agents'); // Connected AI agents + connect guide
 openWorkspaceSettings('danger'); // Delete workspace (owner only)
 ```
 
+Some sections accept an optional second `action` argument to deep-link past the screen. For connected agents, open the setup guide directly:
+
+```tsx
+openWorkspaceSettings('connected-agents', { action: 'openConnectGuide' });
+```
+
 ### Authentication Components
 
 For declarative rendering, use the conditional components:
@@ -504,7 +544,9 @@ Use the `useUserFeatures` hook to check feature flags programmatically:
 import { useUserFeatures } from '@buildbase/sdk/react';
 
 function FeatureCheck() {
-  const { features, isFeatureEnabled, refreshFeatures } = useUserFeatures();
+  // { features, isFeatureEnabled, loading, error, refetch }
+  // (the older `isLoading` / `refreshFeatures` names still work but are deprecated)
+  const { features, isFeatureEnabled, refetch } = useUserFeatures();
 
   return (
     <div>{isFeatureEnabled('premium-features') ? <PremiumContent /> : <StandardContent />}</div>
@@ -1074,6 +1116,142 @@ Platform mode supports granular overrides from the admin dashboard:
 
 These let you achieve team-like, managed, or enterprise-like behavior without a separate mode.
 
+## 🔌 Connected Agents
+
+Let users connect AI agents to their account and manage them. `<ConnectedAgents />` is a ready-made screen (also a workspace settings section) that lists the agents a user has authorized — each with a **Disconnect** action — and, when you provide an MCP server address, shows a **Connect an agent** button that opens a plain-language setup guide.
+
+### Enable the connect guide
+
+Pass an `mcp` config to the provider. Without it the screen still lists and revokes agents; with it, the "Connect an agent" button and setup dialog appear.
+
+```tsx
+<SaaSOSProvider
+  // ...serverUrl, orgId, auth
+  mcp={{
+    url: 'https://app.example.com/api/mcp', // your MCP server endpoint (required to show the guide)
+    name: 'Acme', // friendly name used in prose + config snippets
+    docsUrl: 'https://docs.example.com/agents', // optional "Learn more" link
+  }}
+>
+```
+
+The dialog walks users through the major AI apps — **ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline** — each with the exact click-path or config-file snippet (your server URL is filled in for them), plus a copy-and-paste prompt for chat assistants. It's fully translated (all 8 locales), RTL-aware, and responsive (full-screen on mobile, centered card on desktop).
+
+### The screen
+
+```tsx
+import { ConnectedAgents } from '@buildbase/sdk/react';
+
+function AgentsPage() {
+  return <ConnectedAgents />;
+}
+```
+
+Props: `title`, `description`, `disconnectLabel`, `emptyLabel` (all default to translated strings; pass `null` to hide the heading) and `showConnectGuide` (default `true` — set `false` to hide the connect button even when `mcp` is configured).
+
+Because it's a settings section, you can also open it programmatically:
+
+```tsx
+const { openWorkspaceSettings } = useSaaSAuth();
+
+openWorkspaceSettings('connected-agents'); // the screen (list + connect button)
+openWorkspaceSettings('connected-agents', { action: 'openConnectGuide' }); // straight to the setup dialog
+```
+
+The same deep link works via URL: `?bb=action:openConnectGuide`.
+
+### Custom UI
+
+- **`useConnectedAgents()`** — headless `{ agents, loading, error, revoking, refresh, revoke }` for a fully custom list.
+- **`useMcpConnection()`** — the `mcp` config you passed (or `null`), for building your own guide.
+- **`<ConnectMcpGuide />`** — the guide body on its own (copyable server URL + paste-in prompt + per-client accordion), embeddable anywhere. Override the app list via `mcp.clients` and the prompt via `mcp.prompt` (`false` hides it).
+- **`fillMcpTemplate` / `mcpServerKey`** — the placeholder helpers (`{{url}}` / `{{name}}` / `{{key}}`) for building custom client snippets.
+
+## 📱 Devices & Sessions
+
+Let users see and manage where they're signed in. Two ready-made screens (also combined into one workspace settings section, `devices`):
+
+- **`<Devices />`** — the devices the user has signed in from, each showing a friendly "Browser · OS" line, location + IP, last-used time, and a "This device" / "Trusted" / notifications badge. Per-row actions: **Rename**, **Sign out** (revoke that device's live sessions), and **Remove** (forget the device, with a confirm dialog).
+- **`<Sessions />`** — the user's currently-active sessions, each with a per-row **Sign out** (the current session is badged, not revocable here).
+
+Both are session-authed and scoped to the signed-in user — no config beyond wrapping your app in `<SaaSOSProvider>`. For the "This device" flag and device binding to work, the SDK automatically sends a persisted `x-device-id` header.
+
+### The screens
+
+```tsx
+import { Devices, Sessions } from '@buildbase/sdk/react';
+
+function SecurityPage() {
+  return (
+    <div className="space-y-8">
+      <Devices />
+      <Sessions />
+    </div>
+  );
+}
+```
+
+Or open the combined settings section programmatically:
+
+```tsx
+const { openWorkspaceSettings } = useSaaSAuth();
+openWorkspaceSettings('devices'); // "Devices & sessions" screen
+```
+
+### Show/hide actions & override labels
+
+Every action can be hidden and every button relabeled — an explicit prop wins, otherwise it falls back to the provider `ui.settings.devices.*` config (visible unless set to `false`).
+
+```tsx
+<Devices
+  title={null}            // hide the heading (like every screen; also `description`)
+  showRename={false}      // hide per-row actions
+  showSignOut={false}
+  showRemove={false}
+  renameLabel="Edit"      // relabel buttons (default to translated strings)
+  signOutLabel="Log out"
+  removeLabel="Delete"
+  emptyLabel="No devices yet"
+/>
+
+<Sessions showSignOut={false} signOutLabel="End session" emptyLabel="No other sessions" />
+```
+
+Provider-level equivalent (applies everywhere, incl. the settings screen):
+
+```tsx
+<SaaSOSProvider ui={{ settings: {
+  sections: { devices: false },  // hide the whole "Devices & sessions" settings section
+  devices: {
+    rename: false,        // device Rename
+    signOut: false,       // device Sign out
+    forget: false,        // device Remove
+    sessions: false,      // the active-sessions block on the settings screen
+    sessionSignOut: false // per-session Sign out
+  },
+}}}>
+```
+
+### Custom UI
+
+- **`useDevices()`** — headless `{ devices, loading, error, busyId, refresh, rename, signOut, forget }`.
+- **`useSessions()`** — headless `{ sessions, loading, error, revoking, refresh, revoke }`.
+- **`DevicesApi` / `SessionsApi`** (+ `IDeviceView` / `ISessionView` types) for direct calls.
+
+### Server-side
+
+```ts
+import BuildBase from '@buildbase/sdk';
+const bb = BuildBase({ serverUrl, orgId, getSessionId });
+
+await bb.devices.list();                 // IDeviceView[]
+await bb.devices.rename(deviceId, name);
+await bb.devices.signOut(deviceId);      // revoke the device's sessions
+await bb.devices.forget(deviceId);       // sign out + remove the row
+await bb.sessions.list();                // ISessionView[]
+await bb.sessions.revoke(sessionId);     // by the session's public handle
+```
+
 ## 👤 User Management
 
 ### User Attributes
@@ -1084,8 +1262,9 @@ Manage custom user attributes (key-value pairs):
 import { useUserAttributes } from '@buildbase/sdk/react';
 
 function UserProfile() {
-  const { attributes, isLoading, updateAttribute, updateAttributes, refreshAttributes } =
-    useUserAttributes();
+  // { attributes, loading, error, refetch, updateAttribute, updateAttributes }
+  // (the older `isLoading` / `refreshAttributes` names still work but are deprecated)
+  const { attributes, loading, updateAttribute, updateAttributes, refetch } = useUserAttributes();
 
   const handleUpdate = async () => {
     // Update single attribute
@@ -1245,19 +1424,23 @@ Plans support **pricing variants** (multi-currency). Use these utilities for dis
 
 ### Currency utilities
 
-| Export                               | Purpose                                                   |
-| ------------------------------------ | --------------------------------------------------------- |
-| `CURRENCY_DISPLAY`                   | Map of currency code → symbol (e.g. `usd` → `$`)          |
-| `CURRENCY_FLAG`                      | Map of currency code → flag emoji                         |
-| `PLAN_CURRENCY_CODES`                | Allowed billing currency codes (for dropdowns/validation) |
-| `PLAN_CURRENCY_OPTIONS`              | Options array for plan currency selects                   |
-| `getCurrencySymbol(currency)`        | Symbol for a Stripe currency code                         |
-| `getCurrencyFlag(currency)`          | Flag emoji for a currency code                            |
-| `formatCents(cents, currency)`       | Format cents as localized price string                    |
-| `formatOverageRate(cents, currency)` | Format overage rate for display                           |
-| `formatOverageRateWithLabel(...)`    | Overage rate with optional unit label                     |
-| `formatQuotaIncludedOverage(...)`    | "X included, then $Y / unit" style text                   |
-| `getQuotaUnitLabelFromName(name)`    | Human-readable unit label from quota name                 |
+| Export                                             | Purpose                                                         |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| `CURRENCY_DISPLAY`                                 | Map of currency code → symbol (e.g. `usd` → `$`)                |
+| `CURRENCY_FLAG`                                    | Map of currency code → flag emoji                               |
+| `PLAN_CURRENCY_CODES`                              | Allowed billing currency codes (for dropdowns/validation)       |
+| `PLAN_CURRENCY_OPTIONS`                            | Options array for plan currency selects                         |
+| `getCurrencySymbol(currency)`                      | Symbol for a Stripe currency code                               |
+| `getCurrencyFlag(currency)`                        | Flag emoji for a currency code                                  |
+| `formatCents(cents, currency)`                     | Format a minor-unit amount with the symbol table                |
+| `formatMinorAmountIntl(amount, currency, locale?)` | Locale-aware `Intl` money formatting of minor units             |
+| `getCurrencyDecimals(currency)`                    | ISO 4217 minor-unit digits (0 JPY, 2 USD, 3 KWD; CLDR fallback) |
+| `isZeroDecimalCurrency(currency)`                  | True when the currency has no minor unit (JPY, KRW, …)          |
+| `minorAmountToDisplay(amount, currency)`           | Minor units → display number string (no symbol)                 |
+| `formatOverageRate(cents, currency)`               | Format overage rate for display                                 |
+| `formatOverageRateWithLabel(...)`                  | Overage rate with optional unit label                           |
+| `formatQuotaIncludedOverage(...)`                  | "X included, then $Y / unit" style text                         |
+| `getQuotaUnitLabelFromName(name)`                  | Human-readable unit label from quota name                       |
 
 ### Pricing variant utilities
 
@@ -1297,7 +1480,9 @@ import {
 const variant = getPricingVariant(planVersion, 'usd');
 const cents = getBasePriceCents(planVersion, 'usd', 'monthly');
 if (cents != null) {
-  console.log(getCurrencySymbol('usd') + (cents / 100).toFixed(2));
+  // Never divide by 100 yourself — formatCents applies the currency's ISO 4217
+  // minor-unit factor (JPY ¥1,000 stays whole, KWD divides by 1000, USD by 100).
+  console.log(formatCents(cents, 'usd')); // "$12.99"
 }
 
 // Quota display with overage
@@ -2067,7 +2252,7 @@ import { eventEmitter } from '@buildbase/sdk';
 
 ## 🛡️ Error Handling
 
-The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. **SaaSOSProvider** wraps its children in an internal **SDKErrorBoundary** to catch React render errors inside the SDK tree. For app-level errors, wrap your app (or routes) in your own error boundary (e.g. React’s `ErrorBoundary` or your framework’s error UI). For failed async operations, check the `error` property on hooks and show user feedback (e.g. toast or inline message). See [Error codes](docs/ERROR_CODES.md) for SDK error codes and HTTP mappings.
+The SDK handles errors internally: API failures, auth errors, and component errors are logged and surfaced through hook states (e.g. `error` from `useSaaSWorkspaces`) and callbacks. **SaaSOSProvider** wraps its children in an internal **SDKErrorBoundary** to catch React render errors inside the SDK tree. For app-level errors, wrap your app (or routes) in your own error boundary (e.g. React’s `ErrorBoundary` or your framework’s error UI). For failed async operations, check the `error` property on hooks and show user feedback (e.g. toast or inline message). See [Error codes](https://unpkg.com/@buildbase/sdk/docs/ERROR_CODES.md) for SDK error codes and HTTP mappings.
 
 ## ⚙️ Settings
 
@@ -2077,7 +2262,11 @@ Access OS-level settings:
 import { useSaaSSettings } from '@buildbase/sdk/react';
 
 function SettingsExample() {
-  const { settings, getSettings } = useSaaSSettings();
+  // { settings, loading, error, refetch } — `loading` is true until the one-time
+  // fetch settles, so you can wait instead of rendering with partial defaults.
+  const { settings, loading, refetch } = useSaaSSettings();
+
+  if (loading) return <Spinner />;
 
   return (
     <div>
@@ -2155,9 +2344,11 @@ Prefer these SDK hooks for state and operations instead of `useAppSelector`:
 | `useSaaSAuth()`             | Auth state (user, session, status), signIn(returnUrl?), signOut, openWorkspaceSettings                                                                                                                                                                                    |
 | `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 and getSettings (prefer this when you only need settings)                                                                                                                                                                                           |
-| `useUserAttributes()`       | User attributes and update/refresh                                                                                                                                                                                                                                        |
-| `useUserFeatures()`         | User feature flags                                                                                                                                                                                                                                                        |
+| `useSaaSSettings()`         | Organization settings — `{ settings, loading, error, refetch }` (prefer this when you only need settings)                                                                                                                                                                 |
+| `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 }`                                                                                                                                                                                            |
+| `useMcpConnection()`        | The `mcp` connection config passed to the provider (or `null`), for a custom connect guide                                                                                                                                                                                |
 | `useSubscriptionContext()`  | Subscription for current workspace (response, loading, refetch); use inside SubscriptionContextProvider                                                                                                                                                                   |
 | `useTrialStatus()`          | Trial state: `isTrialing`, `daysRemaining`, `trialEndsAt`, `isTrialEnding`                                                                                                                                                                                                |
 | `usePushNotifications()`    | Push notification state and actions: `isSubscribed`, `subscribe()`, `unsubscribe()`                                                                                                                                                                                       |
@@ -2177,12 +2368,12 @@ Using hooks keeps your code stable if internal state shape changes and avoids di
 
 ### Types
 
-All TypeScript types are exported for type safety. See the [TypeScript definitions](./dist/index.d.ts) for complete type information.
+All TypeScript types are exported for type safety. See the [TypeScript definitions](https://unpkg.com/@buildbase/sdk/dist/index.d.ts) for complete type information.
 
 ### Further documentation
 
-- [Architecture](docs/ARCHITECTURE.md) – Layers, providers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
-- [Error codes](docs/ERROR_CODES.md) – SDK error codes and HTTP status mappings
+- [Architecture](https://unpkg.com/@buildbase/sdk/docs/ARCHITECTURE.md) – Layers, providers, APIs (BaseApi, UserApi, WorkspaceApi, SettingsApi), state, auth flow
+- [Error codes](https://unpkg.com/@buildbase/sdk/docs/ERROR_CODES.md) – SDK error codes and HTTP status mappings
 
 ## ⚙️ Configuration Reference
 
@@ -2935,11 +3126,11 @@ app.post('/webhooks/buildbase', (req, res) => {
 
 ## Agent Readiness (Discovery)
 
-> **Full guide:** [`docs/MCP-AND-AGENT-READINESS.md`](docs/MCP-AND-AGENT-READINESS.md) covers the whole surface — the fast path, the auth model, and the scope/resource customization spectrum. This section is the overview.
+> **Full guide:** [`docs/MCP-AND-AGENT-READINESS.md`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md) covers the whole surface — the fast path, the auth model, and the scope/resource customization spectrum. This section is the overview.
 
 Make a consuming app [agent ready](https://isitagentready.com) by serving the machine-readable discovery documents an AI client looks for — Agent Card, A2A card, OAuth metadata (RFC 8414/9728), Agent Skills, API Catalog (RFC 9727), MCP Server Card (SEP-1649 v1.0) + discovery manifest (SEP-1960), `robots.txt` with AI-bot rules + Content Signals, `sitemap.xml`, `security.txt`, `llms.txt`/`llms-full.txt`, and `auth.md`. Framework-agnostic and zero React: every function returns a plain `DiscoveryDocument` (`{ status, contentType, body, cacheControl, vary? }`).
 
-The fast path is [`createAgentStack`](docs/MCP-AND-AGENT-READINESS.md#fast-path--createagentstack) — one config derives the MCP handler **and** the whole discovery surface. To wire the discovery layer on its own, use `resolveAgentPath`:
+The fast path is [`createAgentStack`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#fast-path--createagentstack) — one config derives the MCP handler **and** the whole discovery surface. To wire the discovery layer on its own, use `resolveAgentPath`:
 
 ```ts
 // lib/agent-ready.ts
@@ -2948,17 +3139,17 @@ import { resolveAgentPath, type AgentReadyConfig } from '@buildbase/sdk';
 export const agentConfig: AgentReadyConfig = {
   serverUrl: process.env.BUILDBASE_URL!,
   orgId: process.env.BUILDBASE_ORG_ID!,
-  siteUrl: 'https://imejis.io',
-  site: { name: 'Imejis', description: 'Generate images from templates via API.' },
+  siteUrl: 'https://example.com',
+  site: { name: 'Acme', description: 'Generate images from templates via API.' },
   // Discovery content is YOURS — defined here in code, not in the platform:
   scopes: [
     { name: 'designs:read', description: 'View designs' },
     { name: 'render:execute', description: 'Render images' },
   ],
-  llmsTxt: '# Imejis\n\n> Generate images from templates via API.',
+  llmsTxt: '# Acme\n\n> Generate images from templates via API.',
   robots: { contentSignals: { search: true, aiInput: true, aiTrain: false } },
   sitemap: { urls: ['/', '/pricing'] }, // omit if you already generate sitemaps
-  protectedResources: [{ resource: 'https://imejis.io/mcp' }], // scopes inherited from catalog
+  protectedResources: [{ resource: 'https://example.com/mcp' }], // scopes inherited from catalog
   // skills, security, apiCatalog, mcpServerCard, a2aCard, extraPaths — all optional
 };
 
@@ -3049,9 +3240,9 @@ Clean split, no duplication: **your app owns discovery content, the platform own
 
 ## MCP Server (`@buildbase/sdk/mcp`)
 
-> **Full guide:** [`docs/MCP-AND-AGENT-READINESS.md`](docs/MCP-AND-AGENT-READINESS.md).
+> **Full guide:** [`docs/MCP-AND-AGENT-READINESS.md`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md).
 
-Turn your app into a **live MCP server** so AI agents can operate it: the built-in tools expose your BuildBase state (workspaces, subscription, quotas, credits, feature flags, permissions) and you add your own product tools with zod schemas. Stateless Streamable HTTP (MCP 2025-06-18) — pure functions plus a Web-standard `Request`/`Response` adapter, so it runs on Node 18+, edge, Deno, and Bun. Server-only, zero React; split from the core entry because it uses `zod` at runtime.
+Turn your app into a **live MCP server** so AI agents can operate it: the built-in tools expose your BuildBase state (workspaces, subscription, quotas, credits, feature flags, permissions) and you add your own product tools with zod schemas — plus **resources** (context a host loads without tool calls) and **prompts** (user-facing workflow templates). Stateless Streamable HTTP (MCP 2025-11-25, negotiating down to 2024-11-05) — pure functions plus a Web-standard `Request`/`Response` adapter, so it runs on Node 18+, edge, Deno, and Bun. Server-only, zero React; split from the core entry because it uses `zod` at runtime.
 
 The fast path bundles the server + the whole discovery surface from one config:
 
@@ -3063,8 +3254,8 @@ import { z } from 'zod';
 export const agent = createAgentStack({
   serverUrl: process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL!,
   orgId: process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!,
-  siteUrl: 'https://imejis.io',
-  site: { name: 'Imejis', description: 'Generate images from templates via API.' },
+  siteUrl: 'https://example.com',
+  site: { name: 'Acme', description: 'Generate images from templates via API.' },
   secret: process.env.SYSTEM_SECRET!, // derives buildbaseAuth (verify + aud + sid decrypt)
   scopes: [{ name: 'render:execute', description: 'Render images' }],
   mcp: {
@@ -3102,10 +3293,10 @@ const buildbase = BuildBase({
 
 export const mcp = createMcpHandler({
   buildbase,
-  serverInfo: { name: 'imejis', version: '1.0.0' },
+  serverInfo: { name: 'acme', version: '1.0.0' },
   auth: buildbaseAuth({
     secret: process.env.SYSTEM_SECRET!,
-    resource: ['https://imejis.io/mcp', 'https://imejis.io/api/mcp'],
+    resource: ['https://example.com/mcp', 'https://example.com/api/mcp'],
     requireAudience: true,
   }),
   builtinTools: 'readonly',
@@ -3123,14 +3314,14 @@ app.post('/mcp', async (req, res) => {
 });
 ```
 
-> **Copy-paste recipes for every framework** — Next.js (App + Pages Router), Express, Fastify, Hono, Bun, Deno, Cloudflare Workers, and React/SPA (WebMCP) — plus the per-framework mint route and a production checklist: [`docs/MCP-AND-AGENT-READINESS.md`](docs/MCP-AND-AGENT-READINESS.md#framework-recipes). Two adapters cover them all: `mcp.fetch(Request)` (web standard — App Router, Hono, Bun, Deno, edge) and `mcp.handle({method,headers,body})` (pure — Express, Fastify, Pages Router).
+> **Copy-paste recipes for every framework** — Next.js (App + Pages Router), Express, Fastify, Hono, Bun, Deno, Cloudflare Workers, and React/SPA (WebMCP) — plus the per-framework mint route and a production checklist: [`docs/MCP-AND-AGENT-READINESS.md`](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#framework-recipes). Two adapters cover them all: `mcp.fetch(Request)` (web standard — App Router, Hono, Bun, Deno, edge) and `mcp.handle({method,headers,body})` (pure — Express, Fastify, Pages Router).
 
 Advertise it via the server card so agents find the endpoint (the stack sets this automatically):
 
 ```ts
 export const agentConfig: AgentReadyConfig = {
   // ...
-  mcpServerCard: mcp.serverCard({ endpoint: 'https://imejis.io/api/mcp' }),
+  mcpServerCard: mcp.serverCard({ endpoint: 'https://example.com/api/mcp' }),
 };
 ```
 
@@ -3159,6 +3350,62 @@ The agent acts as an authenticated app user — it knows your app, not BuildBase
 
 Want per-scope gating on top? Set `requiredScopes` on your own custom tools and return the granted `scopes` from `auth.verify` — the handler hides a tool from `tools/list` (and refuses the call) when its `requiredScopes` aren't all granted. A token that carries **no** scopes sees only tools that require none (the built-ins), so a token minted without a `scope` claim can never unlock a scoped tool. Opt-in, using **your** scope names — the SDK never imposes its own.
 
+### Rich tool results (images, links, mixed content)
+
+Return any JSON-serializable value and the handler wraps it (string → text block; object → JSON text + `structuredContent`). For full control — images, audio, resource links, mixed blocks, or the `isError` flag — return a wire-shaped `McpToolResult` built with the exported helpers:
+
+```ts
+import { mcpImage, mcpResourceLink, mcpText } from '@buildbase/sdk/mcp';
+
+execute: async (input, ctx) => ({
+  content: [
+    mcpText('Revenue chart for Q2:'),
+    mcpImage(chartPngBase64, 'image/png'),
+    mcpResourceLink('https://app.example.com/reports/q2.pdf', 'q2-report'),
+  ],
+  structuredContent: { totalCents: 1_299_00, currency: 'usd' },
+});
+```
+
+### Resources & prompts
+
+Both are **opt-in**, and `initialize` capabilities only advertise what you actually configured — existing servers are byte-identical until you opt in.
+
+```ts
+createMcpHandler({
+  buildbase,
+  // Lean built-in context catalog: buildbase://profile, buildbase://workspaces,
+  // buildbase://workspace/{workspaceId}. Richer data stays tools-only.
+  builtinResources: true,
+  resources: [
+    defineMcpResource({
+      uri: 'app://docs/getting-started',
+      name: 'getting-started',
+      mimeType: 'text/markdown',
+      read: () => gettingStartedMarkdown, // string | object (JSON) | { text } | { blob }
+    }),
+  ],
+  resourceTemplates: [
+    defineMcpResourceTemplate({
+      uriTemplate: 'app://orders/{orderId}',
+      name: 'order',
+      read: (params, _uri, ctx) => ctx.custom.db.order.find(params.orderId),
+    }),
+  ],
+  prompts: [
+    defineMcpPrompt({
+      name: 'analyze_usage',
+      description: 'Review quota usage and suggest actions',
+      arguments: [{ name: 'workspaceId', required: true }],
+      get: async (args, ctx) =>
+        `Review this workspace's quota usage:\n${JSON.stringify(await ctx.bb.usage.getAll(args.workspaceId))}`,
+    }),
+  ],
+});
+```
+
+`requiredScopes` gates resources and prompts exactly like tools. Deliberately out of scope (the stateless transport has no push channel): resource subscriptions, `listChanged`, sampling, elicitation.
+
 ### Production hardening
 
 The handler ships with safe defaults; these are the knobs to review before going live:
@@ -3175,7 +3422,7 @@ export const mcp = createMcpHandler({
   buildbase,
   auth: { verify, resourceMetadataUrl },
   builtinTools: { include: ['get_quota_usage', 'record_usage'] },
-  allowedOrigins: ['https://app.imejis.io'],
+  allowedOrigins: ['https://app.example.com'],
   maxRequestBytes: 512 * 1024,
   rateLimit: async auth => ({ ok: await limiter.allow(auth?.userId), retryAfter: 30 }),
   onError: (err, ctx) => logger.error({ err, ...ctx }, 'mcp error'),
@@ -3223,7 +3470,7 @@ mintToken: (claims) => mintAgentToken({ claims, secret: process.env.SYSTEM_SECRE
 
 // verify (MCP server) — HS256 + RFC 8707 audience + sid decrypt → McpAuthInfo
 import { buildbaseAuth } from '@buildbase/sdk/mcp';
-auth: buildbaseAuth({ secret: process.env.SYSTEM_SECRET!, resource: 'https://imejis.io/mcp' }),
+auth: buildbaseAuth({ secret: process.env.SYSTEM_SECRET!, resource: 'https://example.com/mcp' }),
 ```
 
 Bringing your own token format? `auth.verify(token, req) → McpAuthInfo` accepts any Bearer token; set `auth.resourceMetadataUrl` so 401s carry the RFC 9728 challenge. Set `auth: false` to disable auth (local dev only). Debug audience mismatches with `MCP_AUTH_DEBUG=1`. Test with the MCP Inspector: `npx @modelcontextprotocol/inspector --cli http://localhost:3000/api/mcp --transport http --header "Authorization: Bearer <token>" --method tools/list`.
@@ -3232,7 +3479,7 @@ Bringing your own token format? `auth.verify(token, req) → McpAuthInfo` accept
 
 ### Scopes & resources — restrict or open up
 
-Scopes and resources are **app-owned** — the shared BuildBase authorization server stays scope/resource-agnostic. Scopes have three levers: **declare** a catalog (`scopes: [{ name, description }]` → `scopes_supported` in your own RFC 9728 protected-resource metadata), **gate per tool** (`requiredScopes` on a custom tool → hidden/refused unless the token carries them), and the **floor** (every tool runs under the user's BuildBase session, so the platform enforces the user's real permissions — an agent never exceeds the user). Resources have two: **declare** `protectedResources` (RFC 9728) and **bind** the token audience via `buildbaseAuth({ resource, requireAudience })` (RFC 8707) — the audience check at your resource is the whole gate. Built-ins are restricted with `builtinTools`, not scopes. Public clients (Claude Desktop, Cursor, Inspector) self-register with PKCE and no secret. Full model: [the guide](docs/MCP-AND-AGENT-READINESS.md#scopes--resources-restrict-or-open-up).
+Scopes and resources are **app-owned** — the shared BuildBase authorization server stays scope/resource-agnostic. Scopes have three levers: **declare** a catalog (`scopes: [{ name, description }]` → `scopes_supported` in your own RFC 9728 protected-resource metadata), **gate per tool** (`requiredScopes` on a custom tool → hidden/refused unless the token carries them), and the **floor** (every tool runs under the user's BuildBase session, so the platform enforces the user's real permissions — an agent never exceeds the user). Resources have two: **declare** `protectedResources` (RFC 9728) and **bind** the token audience via `buildbaseAuth({ resource, requireAudience })` (RFC 8707) — the audience check at your resource is the whole gate. Built-ins are restricted with `builtinTools`, not scopes. Public clients (Claude Desktop, Cursor, Inspector) self-register with PKCE and no secret. Full model: [the guide](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#scopes--resources-restrict-or-open-up).
 
 ## OAuth2 App Bridge
 
@@ -3243,7 +3490,7 @@ BuildBase runs the full OAuth2 authorization flow (login, consent, code, PKCE, r
 
 Both requests carry `Authorization: Bearer <JWT>`, an HS256 JWT signed with your client secret. This toolkit verifies those requests (timing-safe, no `alg` confusion) and shapes the exact response body the platform expects, so you write only the part that's yours: minting/invalidating a token in your own format.
 
-> For the common case, `mintToken: (claims) => mintAgentToken({ claims, secret })` is the preset — it signs HS256 with your secret, binds `aud` to the granted RFC 8707 resource, and embeds the encrypted `sid`. The examples below show the hand-rolled equivalent, for apps that mint their own token format (e.g. one shared with their web sessions). See [the guide](docs/MCP-AND-AGENT-READINESS.md#auth-minting--verifying-the-token).
+> For the common case, `mintToken: (claims) => mintAgentToken({ claims, secret })` is the preset — it signs HS256 with your secret, binds `aud` to the granted RFC 8707 resource, and embeds the encrypted `sid`. The examples below show the hand-rolled equivalent, for apps that mint their own token format (e.g. one shared with their web sessions). See [the guide](https://unpkg.com/@buildbase/sdk/docs/MCP-AND-AGENT-READINESS.md#auth-minting--verifying-the-token).
 
 ```ts
 // applicationTokenUrl handler (Next.js Pages Router)
@@ -3284,7 +3531,7 @@ When an agent calls your protected API without a valid token, reply with an RFC
 import { bearerChallenge } from '@buildbase/sdk';
 
 const c = bearerChallenge({
-  resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
+  resourceMetadataUrl: 'https://example.com/.well-known/oauth-protected-resource',
   error: 'invalid_token',
 });
 res.writeHead(c.status, c.headers).end(c.body);