@01.software/sdk 0.56.1 → 0.65.1

package/CHANGELOG.md

@@ -1,5 +1,197 @@
 # @01.software/sdk
 
+## 0.65.1
+
+### Patch Changes
+
+- 2f12d9b: Align the SDK's Payload development dependencies with the 3.90.1 relationship-path read-access fix used by Console.
+
+## 0.65.0
+
+### Minor Changes
+
+- 49d3944: Add optional image/video gallery item descriptors to storefront content reads, with safe thumbnails and explicit ready, processing, or unavailable states. Keep existing image responses and gallery ordering compatible; video playback continues through the server-only admission helper.
+
+### Patch Changes
+
+- 210e4a8: Sync generated tenant types with the optional Console menu display-name preference. Saved preferences remain restricted to Console operators.
+
+## 0.64.1
+
+### Patch Changes
+
+- 94917e1: Align the SDK's Payload development dependencies with the stable 3.90.0 security fixes used by Console.
+- 72131ac: Refresh the generated video types to reflect the chapter editor's placement in the General tab. Existing chapter data and playback behavior are unchanged.
+
+## 0.64.0
+
+### Minor Changes
+
+- 6ec64b3: Preserve collection filter meaning for browser and server `find`/`count` and
+  server bulk mutations. Null equality filters were not filtered correctly before
+  for fields such as text: null became an empty string. `equals: null` and
+  `not_equals: null` now retain null through Payload's native JSON `where` query
+  parameter; date null filters, including the documented `publishedAt` example,
+  remain supported. Bulk mutations now also accept these null equality filters.
+
+  BREAKING (0.x minor): reads now share bulk's pre-request `ValidationError`
+  rejection. Newly rejected read inputs explicitly include `where: {}`,
+  `and: []`, `or: []`, an empty condition object such as `{ id: {} }`,
+  `not_in: []`, `in: []`, and undefined filter values. Nesting beyond 10 and
+  arrays above 1000 elements are also rejected. Null outside equality operators
+  remains rejected. This narrows the accepted read inputs, including empty forms
+  that previously succeeded. When no conditions remain, omit `where` instead of
+  passing `where: {}`. Remove undefined conditions explicitly or return an empty
+  result for an empty ID selection. Collection access rules stay unchanged.
+
+### Patch Changes
+
+- 9a86409: Expose the server-only Membership renewal benefit hold field in generated collection types.
+- e4d1efe: Fix collection updateMany and removeMany filters to use Payload query encoding.
+  Send update fields directly as JSON so authorized bulk mutations reach the existing
+  collection access checks and hooks.
+
+  Calls that previously failed with 400 now actually run.
+  Review existing bulk callers before upgrading. Filters with null/undefined values,
+  empty condition objects, empty arrays, nesting beyond 10 levels, or arrays over
+  1000 elements are rejected
+  before sending a mutation.
+
+- 745bd40: Classify unapplied membership paid evidence as an internal Console collection.
+- 7caa6cc: Document unapplied membership payment evidence in generated payload types.
+
+## 0.63.0
+
+### Minor Changes
+
+- a8f7691: Add `customer.auth.withdraw(currentPassword)` for password-reauthenticated self-withdrawal. Successful withdrawal archives the account and clears the local SDK session; active memberships and passwordless-only accounts return explicit refusal reasons.
+
+### Patch Changes
+
+- 741b7d8: Synchronize the generated Payload type description for customer consent receipts.
+- a33e6ea: Clarify in the generated Link field documentation that expiration removes a link from storefront lists while leaving stored state and direct collection reads unchanged.
+- 4e47268: Clarify the generated audit-log payload documentation: audit summaries contain structural evidence, not personal-data values, secrets or request/response bodies.
+- 0e80819: Synchronize generated internal usage types with the Console's separate email observation field. Public collection buckets and billing meters remain unchanged.
+
+## 0.62.2
+
+### Patch Changes
+
+- e10f77f: Sync generated tenant customer-auth settings and the internal hosted consent receipt type. The receipt collection remains outside published collection clients and HTTP contracts.
+- ee4176a: Clarify generated Customer consent field documentation as tenant self-reports while the hosted server receipt remains the authority for hosted reconsent.
+
+## 0.62.1
+
+### Patch Changes
+
+- 676c69f: Add nullable usage invoice minimum-charge exemption evidence to generated types.
+- bb4d0e2: Update API key scope guidance and generated types after retiring the stored web analytics scope.
+
+## 0.62.0
+
+### Minor Changes
+
+- 4c023aa: BREAKING (0.x minor): Orders raw bulk updates now fail before document mutation.
+  Generic Orders `updateMany` and Admin Panel bulk edit are rejected. Keep top-ID
+  updates for unconditional edits; conditional callers must preserve the complete
+  where query and an at-most-one bound using raw HTTP or the Console Local API.
+  Document native admission/failure codes and retain the SDK's terminal HTTP 400
+  handling. Other collections and SDK transport signatures are unchanged.
+  Transaction-disabled Orders updates without a live external transaction also
+  fail before mutation with a localized HTTP 400; normal and sequential external
+  transactions continue to work.
+
+### Patch Changes
+
+- 5a372d8: Correct the form submissions collection description to match its available actions.
+- 87b450e: Synchronize generated Payload types for internal personal saved order views. Published collection addressability is unchanged.
+- 2bcf3ae: Sync generated customer OAuth client types with implemented-only social provider
+  selection and validation in Console. Previously saved unimplemented providers
+  remain readable but are omitted from hosted login.
+
+## 0.61.1
+
+### Patch Changes
+
+- 4283bcd: Synchronize generated Payload type documentation for hidden event locations. SDK field shapes remain unchanged.
+
+## 0.61.0
+
+### Minor Changes
+
+- 22061d6: BREAKING (0.x minor): `useCustomerLogout()` now awaits direct refresh-family revocation and can report a server failure after local credentials are cleared. Use `customer.auth.logoutAsync()` for server logout; the synchronous `logout()` remains local-only compatibility.
+- 418cdca: Add server-only external Customer link helpers with bounded previous-state snapshots, version-fenced mutations, and explicit request replay identity.
+
+### Patch Changes
+
+- 0b1704a: Expose the existing billing custody method on the server client factory and withMarket return types.
+
+## 0.60.0
+
+### Minor Changes
+
+- 1fea398: Add server-only delegated Membership ciphertext custody operations.
+- cad9245: Add a server-only API for purpose-bound tenant-encrypted installation credentials.
+
+## 0.59.2
+
+### Patch Changes
+
+- 936c20a: Include the tenant password-registration setting in generated Payload types. The existing Customer registration method preserves the new `registration_disabled` API reason.
+
+## 0.59.1
+
+### Patch Changes
+
+- 259d977: Sync the internal generated Payload result type for the reconciled ticket payment outcome. No public SDK API changes.
+
+## 0.59.0
+
+### Minor Changes
+
+- ad385ac: Add the server-only external-effect claims API for tenant-owned provider work. Require redacted report evidence and a remote operation identity before reporting no effect.
+
+## 0.58.0
+
+### Minor Changes
+
+- d558727: Add server Customer delegation inputs for Customer Group restricted paid admission purchases across Cart, Checkout, and PaymentSession APIs.
+- 6ce7cf3: BREAKING (0.x minor): Remove the three retired analytics collection slugs from
+  the exported `INTERNAL_COLLECTIONS` list and `InternalCollection` union, along
+  with their generated SDK types.
+
+### Patch Changes
+
+- 26f94eb: Expose the tenant-wide timezone field in generated Payload collection types.
+
+## 0.57.0
+
+### Minor Changes
+
+- 1b0deb7: BREAKING (0.x minor): Remove the SDK `createAnalytics`, `Analytics`, and `AnalyticsConfig` root exports and the `@01.software/sdk/analytics` and `/analytics/react` subpaths. Existing integrations should use an external analytics tool such as GA4, Plausible, or Vercel Analytics instead. The init CLI no longer generates or advertises an analytics helper.
+- b91e56a: Add server-only `video.playback(videoId)` and `VideoPlayer.streamUrl` for signed,
+  quota-metered VOD playback. BREAKING for assets explicitly migrated to signed
+  playback: a stored legacy `muxPlaybackId` remains historical usage evidence,
+  but raw Mux HLS, thumbnail, and MP4 URLs built from it stop working. Existing
+  unmigrated paid assets retain their public playback path.
+
+### Patch Changes
+
+- 6ab5331: Synchronize generated Payload types and collection ordering for the internal MCP daily usage collection.
+- eb1e49f: Sync internal generated Payload types for the objectless ticket payment kernel result. No public SDK API changes.
+
+## 0.56.3
+
+### Patch Changes
+
+- ef686ff: Synchronize generated entitlement types for explicit tenant-local Project Free grants and their server-owned activation key.
+
+## 0.56.2
+
+### Patch Changes
+
+- ee75768: Synchronize the SDK Payload types with the TicketPurchase kernel obligation schema.
+
 ## 0.56.1
 
 ### Patch Changes

package/README.md

@@ -50,7 +50,6 @@ import { receiveEmbeddedAdminSession } from '@01.software/sdk/embedded-admin'
 import { verifyEmbeddedAdminSession } from '@01.software/sdk/embedded-admin/server'
 
 // Components - sub-path imports per domain
-import { Analytics } from '@01.software/sdk/analytics/react'
 import { RichTextContent } from '@01.software/sdk/ui/rich-text'
 import { Image } from '@01.software/sdk/ui/image'
 import { FormRenderer } from '@01.software/sdk/ui/form'
@@ -70,7 +69,6 @@ entry.
 | `@01.software/sdk/client`                | browser-safe `createClient` entry and SDK error guards                   | none                                                                                                       |
 | `@01.software/sdk/server`                | `createServerClient`, server-only APIs, and SDK error guards             | none; keep `secretKey` code on the server                                                                  |
 | `@01.software/sdk/errors`                | SDK error classes and guards                                             | none                                                                                                       |
-| `@01.software/sdk/analytics`             | browser analytics client and typed event helpers                         | none                                                                                                       |
 | `@01.software/sdk/metadata`              | SEO metadata extraction and generation helpers                           | none                                                                                                       |
 | `@01.software/sdk/webhook`               | webhook handlers, event guards, and webhook types                        | none                                                                                                       |
 | `@01.software/sdk/query`                 | React Query hooks, cache helpers, `getQueryClient`                       | `@tanstack/react-query`, `react`, `react-dom`                                                              |
@@ -78,7 +76,6 @@ entry.
 | `@01.software/sdk/storefront-cache`      | product storefront cache resource name helpers                           | none                                                                                                       |
 | `@01.software/sdk/embedded-admin`        | embedded app browser handshake and shared protocol types                 | none                                                                                                       |
 | `@01.software/sdk/embedded-admin/server` | assertion verification and JWKS loading                                  | none; keep receiver session creation on the server                                                         |
-| `@01.software/sdk/analytics/react`       | `<Analytics />`                                                          | `react`, `react-dom`                                                                                       |
 | `@01.software/sdk/ui/rich-text`          | `RichTextContent`, `StyledRichTextContent`                               | `react`, `react-dom`, `@payloadcms/richtext-lexical`                                                       |
 | `@01.software/sdk/ui/form`               | `FormRenderer`                                                           | `react`, `react-dom`                                                                                       |
 | `@01.software/sdk/ui/code-block`         | `CodeBlock`, `highlight`                                                 | `react`, `react-dom`, `shiki`, `hast-util-to-jsx-runtime`                                                  |
@@ -87,6 +84,18 @@ entry.
 | `@01.software/sdk/ui/video`              | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
 | `@01.software/sdk/ui/image`              | `Image`                                                                  | `react`, `react-dom`                                                                                       |
 
+### Video playback admission
+
+On your server, call `createServerClient(...).video.playback(video.id)` after
+applying your viewer's content-access policy. Pass its `streamUrl` to
+`<VideoPlayer video={video} streamUrl={streamUrl} />`.
+The bearer URL expires after two hours; refresh it before the deadline during
+long playback or after a long pause. Free playback uses a quota-metered gateway and can return 403 when the
+monthly allowance is exhausted or 503 when admission cannot be verified.
+`muxPlaybackId`, `getVideoStreamUrl`, and raw Mux thumbnail/MP4 helpers are
+legacy public-ID paths for unmigrated paid assets. A signed asset's retained
+`muxPlaybackId` is historical usage evidence and is not a playable URL.
+
 `CanvasRenderer` renders reserved `shape` nodes (`terminator`, `process`,
 `decision`, `io`, `subprocess`) with first-party SVG geometry, without a tenant
 catalog row or QuickJS template.
@@ -162,91 +171,7 @@ Migration quick reference:
   self-contained and must not import private contracts; Console code should
   import shared helpers from contracts directly.
 
-### Analytics
-
-```typescript
-// Pageviews + custom events (browser)
-import { createAnalytics } from '@01.software/sdk/analytics'
-
-const analytics = createAnalytics({ publishableKey: 'pk01_xxx' })
-// auto-tracks pageviews; call analytics.pageview('/custom-path') manually if needed
-analytics.track('signup', { plan: 'pro', trial: false })
-```
-
-**Custom events must be registered first.** Each custom event name, its
-dimensions, and any enum/boolean value sets are defined per workspace in
-Console → Analytics. An unregistered or mistyped event is accepted by the
-browser (200/204) and then **silently dropped server-side** — no client error.
-Register the event before firing it.
-
-**Typed events (compile-time safety).** Declare an event map as a plain `type`
-(do **not** `extends AnalyticsEventMap` — an index signature would defeat
-typo detection) and pass it as the generic. Mistyped names and out-of-enum
-values then fail to compile:
-
-```typescript
-import {
-  createAnalytics,
-  defineAnalyticsEvents,
-} from '@01.software/sdk/analytics'
-
-type ShopEvents = {
-  signup: { plan: 'free' | 'pro'; trial: boolean }
-  add_to_cart: { productId: string; price: number }
-  checkout_start: undefined // no props
-}
-
-const analytics = createAnalytics<ShopEvents>({ publishableKey: 'pk01_xxx' })
-analytics.track('signup', { plan: 'pro', trial: false }) // ✅
-analytics.track('checkout_start') // ✅ no props
-// analytics.track('signpu', { plan: 'pro', trial: false }) // ❌ unknown event
-// analytics.track('signup', { plan: 'team', trial: false }) // ❌ enum violation
-
-// Bind the map once to avoid repeating the generic:
-const create = defineAnalyticsEvents<ShopEvents>()
-const a2 = create({ publishableKey: 'pk01_xxx' })
-```
-
-**React.** Use `AnalyticsProvider` + `useAnalytics()` to fire events from
-components. The provider auto-tracks pageviews like `<Analytics/>` and owns one
-instance for its subtree:
-
-Reusing the `ShopEvents` type from above:
-
-```tsx
-import {
-  AnalyticsProvider,
-  useAnalytics,
-} from '@01.software/sdk/analytics/react'
-
-function Root() {
-  return (
-    <AnalyticsProvider>
-      <App />
-    </AnalyticsProvider>
-  )
-}
-
-function SignupButton() {
-  const { track, pageview } = useAnalytics<ShopEvents>()
-  // pageview(path?) is available for manual SPA pageviews; the provider already auto-tracks pageviews
-  return (
-    <button onClick={() => track('signup', { plan: 'pro', trial: false })}>
-      Sign up
-    </button>
-  )
-}
-```
-
-`<Analytics />` remains available as a pageview-only mount helper for apps that
-do not fire custom events from components.
-
-**Send mode.** `mode: 'auto'` (default) suppresses sends on local hosts
-(`localhost` / `127.0.0.1` / `*.local`); `'production'` always sends, even
-locally; `'development'` never sends. The hosted `<script>` snippet uses the
-same vocabulary via `window.__01_analytics__.mode` or `data-mode`; its legacy
-`captureOnLocalhost: true` flag is equivalent to `mode: 'production'` and is
-honored only when `mode` is unset.
+For website analytics, integrate an external tool such as GA4, Plausible, or Vercel Analytics in your own frontend. The SDK no longer provides analytics collection helpers.
 
 ## Getting Started
 
@@ -390,11 +315,26 @@ storefronts can render time-sensitive copy.
 
 `content.galleryItems.list()` calls `GET /api/gallery-items/storefront`;
 gallery item DTOs include title, description, content, gallery reference, and
-image media. Tenant, metadata, draft status, and storage/provider internals are
+optional `mediaType` (`image` or `video`). Treat an omitted `mediaType` as `image`
+for older responses. Image items retain `image` media. Video items include a
+safe `video` descriptor with `availability: 'ready' | 'processing' | 'unavailable'`,
+and may include a video document `id` and uploaded `thumbnail`. Disabled or
+plan-blocked video features, missing/deleted targets, and failed videos return
+only `{ availability: 'unavailable' }`, preserving each item's position and
+pagination. The image relationship is not used as a video poster.
+Tenant, metadata, draft status, and storage/provider internals are
 omitted. Gallery item reads require either `gallerySlug` or `galleryId`; prefer
 `gallerySlug` for storefront routes. The default gallery item sort is `manual`,
 matching curator order from the Console.
 
+The descriptor's `ready` state is preparation metadata, not playback authority.
+Your application server must verify that the requested video belongs to the
+published gallery/item and apply its viewer policy before calling
+`server.video.playback(video.id)`. Deliver that response's `streamUrl` to the
+player; playback rechecks the current tenant, video state, and feature/plan.
+Keep server credentials on the application server. Gallery responses do not
+include playback URLs, provider IDs, or tokens.
+
 Both helpers return Payload-style pagination (`docs`, `totalDocs`, `page`,
 `limit`, etc.). `limit` is bounded server-side to `1..100`; invalid query,
 publishable-key, feature, rate-limit, and server errors surface through the
@@ -866,6 +806,50 @@ Keep these calls in trusted server code. Do not mutate `customers.groups`
 directly: after source-authority activation it is a read-compatible projection
 and direct writes return `customer_groups_direct_write_retired`.
 
+### External Customer links (server only)
+
+`server.externalCustomerLinks` connects a platform Customer to an external
+Customer ID within the namespace and environment derived from an active
+integration registration. Your app supplies a normalized stable `accountScope`
+to reserve identity; namespace-bound keys authorize all accounts in that
+namespace, and account scope is not an account ACL. All six methods (`connect`,
+`get`, `list`,
+`unlink`, `capturePreviousState`, `clearPreviousState`) require server
+credentials and Customer read or write scope.
+
+```typescript
+const link = await server.externalCustomerLinks.connect({
+  integrationId,
+  customerId,
+  accountScope,
+  externalCustomerId: 'contact-123',
+  requestId: crypto.randomUUID(),
+})
+const capture = {
+  integrationId,
+  customerId,
+  linkId: link.id,
+  requestId: crypto.randomUUID(),
+  expectedVersion: link.version,
+  previousState: { tier: 'silver' },
+}
+await server.externalCustomerLinks.capturePreviousState(capture)
+// After an interrupted response, retry this exact request, including expectedVersion.
+```
+
+The bounded previous state accepts up to 16 flat string/number/boolean/null
+fields, 512 characters per string, and 2048 UTF-8 JSON bytes. It records only
+what your server supplies; the platform performs no external provider I/O.
+Before restoring provider state, check the current active owner with
+`list({ integrationId, accountScope, externalCustomerId, state: 'active' })`
+and evaluate whether the restoration is still appropriate. Lists accept optional Customer,
+account scope, external ID, and state filters (external ID requires account
+scope), `limit` (default 25, maximum 100), and `afterId`;
+use `nextCursor` for the next page. Unlink and clear also require a fresh
+request UUID and the current version; exact retries retain the original values.
+A privacy-erased snapshot has state `erased`, null `externalCustomerId`, and
+null `previousState`. Keep these calls and snapshots in trusted server code.
+
 ## Storefront performance defaults
 
 - **PLP:** prefer `commerce.product.listingPage()` or `useProductListingPage()` (GET `/api/products/listing-groups/query/catalog`, CDN-cacheable, card-ready). Use `listingGroupsCatalog({ productIds })` only when IDs are already known. Treat the full listing-groups response shape as a server-auth escape hatch because it can include operational stock fields. Avoid fetching a product list and then calling `detail()` per card.
@@ -1137,6 +1121,49 @@ await server.collections.from('articles').updateMany(where, data)
 await server.collections.from('articles').removeMany(where)
 ```
 
+Collection `find`, `count`, `updateMany`, and `removeMany` share filter validation.
+`equals: null` and `not_equals: null` retain their null meaning through Payload
+REST, including text fields; null-containing filters use Payload's native JSON
+`where` query parameter. Other filters keep bracketed encoding. The SDK throws
+`ValidationError` before a request for undefined values, null outside those two
+operators, empty condition objects, empty arrays (including `and`/`or`), nesting
+beyond 10 levels, and arrays with more than 1000 elements. Omit `where` for an
+unfiltered read. For a dynamically empty ID list, return an empty result before
+calling the SDK rather than passing `in: []`. False, zero, empty strings, and
+Date conditions remain valid.
+
+Check your bulk filters carefully: calls that previously failed with HTTP 400
+now perform updates or deletions. Large `in`/`not_in`
+lists can exceed URL length limits (around 250 UUIDs); split work into smaller
+batches. For `not_in`, keep the full exclusion condition in every batch rather
+than splitting the exclusions across separate mutations.
+
+### Orders update compatibility
+
+Orders accept one-document updates only. Admin Panel bulk edits and generic
+`server.collections.from('orders').updateMany(...)` are rejected before any
+Order changes with HTTP 400 (`errors[0].data.code: order_bulk_update_unsupported`).
+Use `update(orderId, data)` for an unconditional edit. For a conditional update,
+keep the entire where predicate in the raw `PATCH /api/orders` query and set
+`limit=1`; send the field data as the body. Local API callers use numeric
+`limit: 1`, or a strict UUID `id.equals` that bounds the complete predicate.
+An ID in only one OR branch is insufficient. SDK `updateMany` has no limit
+option and is not a supported Orders CAS path.
+
+A conditional miss returns `docs: [], errors: []`. A collected hook failure
+instead returns HTTP 500 (`errors[0].data.code: order_update_failed`), with a
+localized message and rollback of the supported single operation. Access and
+tenant checks remain in force. Do not replace a conditional update with an
+unconditional ID update or automatically retry payment capture. Separate
+per-order edits do not promise atomic success across the whole selection.
+
+Console Local API Orders updates also require a live transaction. Setting
+`disableTransaction: true` without a live external transaction rejects both
+top-ID and where updates before writes with HTTP 400
+(`errors[0].data.code: order_transaction_required`). Remove that option to
+use Payload's normal transaction, or pass a live external transaction;
+a request transaction ID by itself is not sufficient.
+
 ### API Response Types (Payload Native)
 
 The SDK returns Payload CMS native response types without wrapping:
@@ -1339,7 +1366,6 @@ const { token, customer } = await client.customer.auth.login({
 // Profile & token management
 const profile = await client.customer.auth.me()
 client.customer.auth.isAuthenticated()
-client.customer.auth.logout()
 
 // Authenticated customer's own orders (Client-only)
 const orders = await client.commerce.orders.listMine({
@@ -1348,12 +1374,22 @@ const orders = await client.commerce.orders.listMine({
   financialStatus: 'paid',
 })
 
+await client.customer.auth.logoutAsync()
+
 // Password
 await client.customer.auth.forgotPassword('john@example.com')
 await client.customer.auth.resetPassword(token, newPassword)
 await client.customer.auth.changePassword(currentPassword, newPassword)
 ```
 
+`logoutAsync()` revokes the direct refresh-token family on the server and clears
+local credentials even when the request fails. Handle a rejection as incomplete
+server revocation. The older synchronous `logout(): void` clears local state
+immediately but cannot revoke the server session. `useCustomerLogout()` awaits
+the server request and clears authenticated customer query data on success or
+failure. An issued access token can remain valid for up to 15 minutes; legacy
+bearer-only refresh remains a separate compatibility path.
+
 `forgotPassword()` keeps the same SDK signature in both delivery modes. A
 tenant administrator chooses either backward-compatible signed webhook
 delivery or platform-managed email in the Console customer-authentication
@@ -1362,6 +1398,31 @@ the platform appends the `token` query parameter and sends through the verified
 tenant sender or the platform fallback. Do not add reset tokens or dynamic
 redirect URLs to the SDK call.
 
+#### Self-withdrawal
+
+A signed-in customer with a local password can withdraw using their current
+password. With an authenticated client:
+
+```ts
+const { withdrawnAt } = await client.customer.auth.withdraw(currentPassword)
+```
+
+This calls `POST /api/customers/withdraw` with the publishable key and Customer
+JWT. Success archives the account immediately and clears the SDK's local
+credentials. Clear any application-owned session cookies and customer cache as
+well. Archived accounts cannot use existing sessions or authenticate again.
+Withdrawal preserves order, payment and membership-charge history; it does not
+erase personal data or free the email for a new registration.
+
+Branch on `SDKError.apiReason`: `active_membership_exists` (409) requires the
+membership to end first, including scheduled cancellations still in an active
+status; `reauthentication_unavailable` (409) means no local password is set and
+the customer should contact the tenant administrator. Incorrect passwords use
+the shared login attempt counter and temporary lock (`account_locked`, 423).
+Refusal leaves the SDK credentials intact. Server keys cannot withdraw on a
+customer's behalf. Operator restore continues to follow the existing archive
+rules; the withdrawal timestamp is retained.
+
 ### Market discovery
 
 Discover a tenant's active buyer markets and resolve the default market. These
@@ -2013,6 +2074,28 @@ await server.community.moderation.banCustomer({ customerId, isPermanent?, banned
 await server.community.moderation.unbanCustomer({ customerId })
 ```
 
+### Installation credentials (server only)
+
+`createServerClient().installationCredentials` stores one bounded ciphertext
+for a registered non-payment OAuth installation. A tenant administrator must
+register the installation and explicitly bind the server key; an ordinary
+`sk01_` key or external-effect claim grant is insufficient. Encrypt before
+`create`, decrypt only in your server, and keep OAuth and provider calls there.
+
+```typescript
+const current = await server.installationCredentials.get({ installationId })
+const next = await server.installationCredentials.replace({
+  installationId,
+  expectedVersion: current.version,
+  ciphertext: newlyEncryptedCredential,
+})
+```
+
+Replacement uses a version condition; after an uncertain result, read back
+before retrying. `dispose` clears the platform copy but does not revoke a
+credential already read by your server. A platform database restore requires
+re-authorization before older installations become readable again.
+
 ### Webhook
 
 Webhooks created in Console start inactive. Use this setup order so no event is
@@ -2286,7 +2369,7 @@ SOFTWARE_SECRET_KEY=sk01_...  # Server only — opaque API key from Console
 
 > `secretKey` may be an `sk01_...` API key or a `pat01_...` personal access token. Server SDK calls must also send the matching `publishableKey`; PAT tenant selection is pinned server-side, and callers must not send `X-Tenant-Id`.
 
-API keys created without explicit scopes use the default `['read', 'write']`. Console API-key creation can request narrower `scopes[]`; in the first explicit-scope slice tenant admins may grant only `read` and `write`. Higher-authority scopes such as `webhook`, `analytics`, and `super-admin` require platform authority and otherwise return `scope_grant_forbidden`.
+API keys created without explicit scopes use the default `['read', 'write']`. Console API-key creation can request narrower `scopes[]`; tenant admins may grant only `read` and `write`. `webhook` and `super-admin` require a super-admin session. Requests containing the retired `analytics` scope, alone or mixed, are rejected for every role. Previously issued keys keep their identity; an analytics-only key has no effective access, while a mixed key keeps its other scopes.
 
 > **SDK 0.9.0**: Server auth now uses opaque bearer tokens (`sk01_...`). Generate API keys from the Console. `createServerToken`, `createApiKey`, and `parseApiKey` are no longer part of the SDK surface.