@farthershore/farthershore-js 0.2.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ This project adheres to Semantic Versioning (pre-1.0: minors may break).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-06-22
+
+### Changed
+
+- **Lockstep SDK family.** `@farthershore/farthershore-js`,
+  `@farthershore/product`, and `@farthershore/backend` now publish at ONE shared
+  version (`0.8.0`). The frontend SDK jumps `0.2.0` → `0.8.0` to align with the
+  family floor (the highest current SDK). Pin all three to the same version. A CI
+  invariant (`sdk-family-version` in `@farthershore/contracts`) keeps the three
+  `package.json` versions equal.
+
+### Added
+
+- `X-FS-SDK-Version` request header on every Core call — a one-way client
+  annotation (value = the SDK version) for platform observability. The platform
+  does not branch on it.
+- A compat fingerprint (`CONTRACTS_FP`) is stamped into the generated catalog
+  types — a stable hash over the canonical `@farthershore/contracts` DTO set so
+  CI can detect when an SDK projection drifts from contracts.
+- The resolve/bootstrap DTO now carries an additive `schemaVersion` for future
+  negotiation (read tolerantly; absent = `1`).
+
 ## [0.2.0] - 2026-06-18
 
 ### Added

package/README.md

@@ -4,12 +4,14 @@ The **Farther Shore Frontend SDK** — the canonical browser integration layer
 between a static frontend artifact (the default dev-portal template, generated
 frontends, managed components, custom frontends) and the Farther Shore platform.
 
-> **Status: `0.1.0` (early release).** Published to npm. Pre-1.0, so minor
-> versions may include breaking changes while the API stabilizes against the dev
-> portal, managed template, and real builder features. See [`PUBLISHING.md`](./PUBLISHING.md)
-> for the gates to `1.0.0` (wire-contract lock, browser token exchange, gateway
-> CORS, stage e2e). The `@stripe/stripe-js` analog to the upstream runtime
-> package `@farthershore/metering`.
+> **Status: `0.8.0` (lockstep SDK family).** Published to npm. Versioned in
+> lockstep with `@farthershore/product` and `@farthershore/backend` — pin the
+> three to the SAME version. Pre-1.0, so minor versions may include breaking
+> changes while the API stabilizes against the dev portal, managed template, and
+> real builder features. See [`PUBLISHING.md`](./PUBLISHING.md) for the gates to
+> `1.0.0` (wire-contract lock, browser token exchange, gateway CORS, stage e2e).
+> The `@stripe/stripe-js` analog to the upstream runtime package
+> `@farthershore/backend`.
 
 ```bash
 pnpm add @farthershore/farthershore-js   # React is an optional peer (for /react)
@@ -196,6 +198,37 @@ Hooks: `useBootstrap`, `useProduct`, `useSession` (+ `signIn`/`signOut`),
 `openBillingPortal`), `useFeature(name)`, plus `useFartherShore()` for the raw
 client. They're thin wrappers over the client — no duplicated logic.
 
+## Customizing the portal (the fork model)
+
+Every product ships with a generic managed portal by default. To customize it,
+**edit the product repo's `frontend/` tree** (what `farthershore init` / platform
+provisioning scaffolds): change the components, layout, and styles, then push —
+the platform rebuilds `frontend/` into a custom release and serves it instead of
+the default. Your product's _contract_ (plans, pricing, routes, meters) lives in
+`product/` and is managed as code; the UI lives in `frontend/`.
+
+The scaffold is already SDK-wired: one `createFartherShoreClient.fromEnv()`
+client (coreUrl from the bundler env in dev, edge-injected `window.__FS_CONFIG__`
+in prod — env stays automatic) under one `<FartherShoreRoot>`, rendering the
+zero-prop data components (`<PlansTable/>`, `<UsageCard/>`, `<BillingSummary/>`,
+`<ApiKeysPanel/>`, …).
+
+### Rendering a product-authored nav after a fork — `<FsManifestNav>`
+
+A product can author a `frontendManifest` (nav + pages) in `product.config.ts`.
+The managed default template renders it, but a **fork that replaces the template
+silently drops it**. `<FsManifestNav>` is the opt-in fix: it maps the manifest's
+`nav` entries to links so the authored nav survives a fork with one import. It's
+zero-prop, accessible (a `<nav aria-label>` of links with `aria-current` on the
+active path), and renders nothing when no manifest was authored.
+
+```tsx
+import { FsManifestNav } from "@farthershore/farthershore-js/components";
+
+// Renders boot.frontendManifest.nav; swap in a router <Link> via linkComponent.
+<FsManifestNav activePath={location.pathname} />;
+```
+
 ## Deferred (no platform endpoint yet)
 
 - **Clerk browser sign-in** is host-app-driven (pass `getToken`); the SDK doesn't
@@ -205,13 +238,16 @@ client. They're thin wrappers over the client — no duplicated logic.
 
 ## Versioning & stability
 
-This package is **pre-1.0 (`0.x`)**. Under SemVer's 0.x rules a **minor** bump
-(`0.1.x` → `0.2.0`) may include **breaking changes**, so the usual caret range is
+This package is **pre-1.0 (`0.x`)** and ships as part of a **lockstep SDK
+family**: `@farthershore/farthershore-js`, `@farthershore/product`, and
+`@farthershore/backend` are published at the SAME version (currently `0.8.0`).
+Pin all three to the same version. Under SemVer's 0.x rules a **minor** bump
+(`0.8.x` → `0.9.0`) may include **breaking changes**, so the usual caret range is
 unsafe here:
 
-- ❌ `^0.1` / `^0.1.0` — caret does **not** lock the minor across `0.x`; it would
-  silently accept a breaking `0.2.0`.
-- ✅ Pin **exact** (`0.1.0`) or use a patch-only tilde (`~0.1.0`) until `1.0.0`.
+- ❌ `^0.8` / `^0.8.0` — caret does **not** lock the minor across `0.x`; it would
+  silently accept a breaking `0.9.0`.
+- ✅ Pin **exact** (`0.8.0`) or use a patch-only tilde (`~0.8.0`) until `1.0.0`.
 
 Breaking changes within `0.x` are recorded in [`CHANGELOG.md`](./CHANGELOG.md)
 (Keep a Changelog format) — read it before bumping.

package/dist/auth-user.d.ts

@@ -0,0 +1,7 @@
+import type { FsAuthUser } from "./types.js";
+/** Normalize a Clerk user object OR a persona sign-in response user into the
+ *  SDK's {@link FsAuthUser}. Returns null when `raw` isn't an object (signed
+ *  out / unknown). Every named field degrades to null; `fullName` falls back to
+ *  `first last` when Clerk/persona doesn't supply one. */
+export declare function normalizeAuthUser(raw: unknown): FsAuthUser | null;
+//# sourceMappingURL=auth-user.d.ts.map

package/dist/auth-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-user.d.ts","sourceRoot":"","sources":["../src/auth-user.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAkB7C;;;0DAG0D;AAC1D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAmBjE"}

package/dist/auth-user.js

@@ -0,0 +1,43 @@
+// W6.1 — the FsAuthUser normalizer. One typed identity (`FsAuthUser`) over the
+// two shapes the SDK ever sees: Clerk's user object and the persona sign-in
+// RESPONSE user (built by core's `synthesizeUser`). Both put the primary email
+// at the NESTED path `primaryEmailAddress.emailAddress` — read that path, with
+// a flat `email` fallback. SDK-only: no platform/contracts dependency.
+function str(v) {
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+/** Read the primary email from EITHER the Clerk/persona nested
+ *  `primaryEmailAddress.emailAddress` path OR a flat top-level `email`. */
+function readEmail(o) {
+    const nested = o.primaryEmailAddress;
+    if (nested && typeof nested === "object") {
+        const email = nested.emailAddress;
+        const s = str(email);
+        if (s)
+            return s;
+    }
+    return str(o.email);
+}
+/** Normalize a Clerk user object OR a persona sign-in response user into the
+ *  SDK's {@link FsAuthUser}. Returns null when `raw` isn't an object (signed
+ *  out / unknown). Every named field degrades to null; `fullName` falls back to
+ *  `first last` when Clerk/persona doesn't supply one. */
+export function normalizeAuthUser(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    const firstName = str(o.firstName);
+    const lastName = str(o.lastName);
+    const explicitFull = str(o.fullName);
+    const synthesizedFull = [firstName, lastName].filter(Boolean).join(" ") || null;
+    return {
+        id: str(o.id),
+        firstName,
+        lastName,
+        fullName: explicitFull ?? synthesizedFull,
+        email: readEmail(o),
+        imageUrl: str(o.imageUrl),
+        raw,
+    };
+}
+//# sourceMappingURL=auth-user.js.map

package/dist/auth-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-user.js","sourceRoot":"","sources":["../src/auth-user.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,+EAA+E;AAC/E,uEAAuE;AAIvE,SAAS,GAAG,CAAC,CAAU;IACrB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED;2EAC2E;AAC3E,SAAS,SAAS,CAAC,CAA0B;IAC3C,MAAM,MAAM,GAAG,CAAC,CAAC,mBAAmB,CAAC;IACrC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,KAAK,GAAI,MAAqC,CAAC,YAAY,CAAC;QAClE,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAED;;;0DAG0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,CAAC,GAAG,GAA8B,CAAC;IAEzC,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,eAAe,GACnB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAE1D,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACb,SAAS;QACT,QAAQ;QACR,QAAQ,EAAE,YAAY,IAAI,eAAe;QACzC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;QACnB,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACzB,GAAG;KACJ,CAAC;AACJ,CAAC"}

package/dist/auto-key.d.ts

@@ -0,0 +1,14 @@
+/** The auto-created key arrives as `string | { secret?: string } | null` on the
+ *  wire (OnboardingResult.autoApiKey). Normalize it to the bare secret, or null. */
+export declare function normalizeAutoApiKey(value: unknown): string | null;
+/** Stash the one-time secret for the dashboard to reveal. A falsy/invalid value
+ *  is a no-op (the banner simply never shows). SSR/storage-blocked safe. */
+export declare function storeAutoApiKey(value: unknown): void;
+/** Read the stored secret WITHOUT clearing it. Returns null when none is
+ *  stashed (or storage is unavailable). Clearing is the caller's explicit
+ *  post-mount step so a re-render can't consume the showing key. */
+export declare function peekAutoApiKey(): string | null;
+/** Consume the stored secret — call once the reveal banner has mounted, so it is
+ *  shown exactly once and never re-shown on a later visit. */
+export declare function clearAutoApiKey(): void;
+//# sourceMappingURL=auto-key.d.ts.map

package/dist/auto-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-key.d.ts","sourceRoot":"","sources":["../src/auto-key.ts"],"names":[],"mappings":"AAkBA;oFACoF;AACpF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOjE;AAED;4EAC4E;AAC5E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAUpD;AAED;;oEAEoE;AACpE,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAS9C;AAED;8DAC8D;AAC9D,wBAAgB,eAAe,IAAI,IAAI,CAQtC"}

package/dist/auto-key.js

@@ -0,0 +1,70 @@
+// One-time auto-created API-key reveal store (W8.4).
+//
+// During onboarding the platform auto-creates an API key whose secret is shown
+// EXACTLY ONCE (`OnboardingResult.autoApiKey`). This SDK-managed store hands that
+// secret from the onboarding/subscribe call to the dashboard, where it is
+// revealed once and cleared — so a generated frontend doesn't hand-roll the
+// stash (the dev-portal template previously kept its own copy).
+//
+// Backed by sessionStorage: the secret never lands in a URL / browser history
+// and dies with the tab. The contract mirrors the SSR portal's 60s HttpOnly
+// cookie: shown once, never re-shown.
+//   - storeAutoApiKey(value): stash after the onboarding/subscribe call.
+//   - peekAutoApiKey():       read WITHOUT clearing (so a StrictMode double
+//                             render or remount can't eat the one showing).
+//   - clearAutoApiKey():      consume it — call once the banner has mounted.
+const AUTO_KEY_STORAGE_KEY = "fs_auto_key";
+/** The auto-created key arrives as `string | { secret?: string } | null` on the
+ *  wire (OnboardingResult.autoApiKey). Normalize it to the bare secret, or null. */
+export function normalizeAutoApiKey(value) {
+    if (typeof value === "string" && value)
+        return value;
+    if (value && typeof value === "object") {
+        const secret = value.secret;
+        if (typeof secret === "string" && secret)
+            return secret;
+    }
+    return null;
+}
+/** Stash the one-time secret for the dashboard to reveal. A falsy/invalid value
+ *  is a no-op (the banner simply never shows). SSR/storage-blocked safe. */
+export function storeAutoApiKey(value) {
+    const key = normalizeAutoApiKey(value);
+    if (!key)
+        return;
+    try {
+        if (typeof window !== "undefined" && window.sessionStorage) {
+            window.sessionStorage.setItem(AUTO_KEY_STORAGE_KEY, key);
+        }
+    }
+    catch {
+        /* no storage → the banner simply never shows */
+    }
+}
+/** Read the stored secret WITHOUT clearing it. Returns null when none is
+ *  stashed (or storage is unavailable). Clearing is the caller's explicit
+ *  post-mount step so a re-render can't consume the showing key. */
+export function peekAutoApiKey() {
+    try {
+        if (typeof window !== "undefined" && window.sessionStorage) {
+            return window.sessionStorage.getItem(AUTO_KEY_STORAGE_KEY);
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Consume the stored secret — call once the reveal banner has mounted, so it is
+ *  shown exactly once and never re-shown on a later visit. */
+export function clearAutoApiKey() {
+    try {
+        if (typeof window !== "undefined" && window.sessionStorage) {
+            window.sessionStorage.removeItem(AUTO_KEY_STORAGE_KEY);
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+//# sourceMappingURL=auto-key.js.map

package/dist/auto-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-key.js","sourceRoot":"","sources":["../src/auto-key.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,+EAA+E;AAC/E,kFAAkF;AAClF,0EAA0E;AAC1E,4EAA4E;AAC5E,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,sCAAsC;AACtC,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,6EAA6E;AAE7E,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAE3C;oFACoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,MAAM,GAAI,KAA8B,CAAC,MAAM,CAAC;QACtD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;4EAC4E;AAC5E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,GAAG,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,IAAI,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC3D,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED;;oEAEoE;AACpE,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC3D,OAAO,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;8DAC8D;AAC9D,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC3D,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC"}

package/dist/bootstrap.d.ts

@@ -1,6 +1,24 @@
 import { type ClientContext } from "./config.js";
-import type { Bootstrap } from "./types.js";
+import type { Bootstrap, Plan } from "./types.js";
+import type { PortalPlanWire, PlanMeterWire, PlanLimitWire } from "./generated/catalog-types.js";
+type RawPlanMeter = PlanMeterWire;
+type RawPlanLimit = PlanLimitWire;
+type RawPortalPlan = Omit<PortalPlanWire, "grants" | "meters" | "limits" | "planDetails" | "featureGates" | "capability_limits" | "max_monthly_spend_cents" | "min_monthly_spend_cents"> & {
+    grants?: PortalPlanWire["grants"] | null;
+    meters?: RawPlanMeter[] | null;
+    limits?: RawPlanLimit[] | null;
+    planDetails?: string[] | null;
+    featureGates?: Record<string, boolean> | null;
+    capability_limits?: Record<string, number | boolean> | null;
+    max_monthly_spend_cents?: number | null;
+    min_monthly_spend_cents?: number | null;
+};
+/** Map a snake_case wire `PortalPlan` → the camelCase domain {@link Plan}.
+ *  INTERNAL helper shared by `resolveBootstrap` (catalog) and the `/me`
+ *  account surface (`availablePlans`) — NOT part of the public API. */
+export declare function mapPlan(p: RawPortalPlan): Plan;
 /** Resolve + cache the product/env/gateway onto `ctx`. Idempotent — safe to call
  *  repeatedly; the client memoizes the result. */
 export declare function resolveBootstrap(ctx: ClientContext): Promise<Bootstrap>;
+export {};
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAEV,SAAS,EAWV,MAAM,YAAY,CAAC;AAuMpB;kDACkD;AAClD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAuC7E"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAEV,SAAS,EAMT,IAAI,EAKL,MAAM,YAAY,CAAC;AAMpB,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACd,MAAM,8BAA8B,CAAC;AAiDtC,KAAK,YAAY,GAAG,aAAa,CAAC;AAClC,KAAK,YAAY,GAAG,aAAa,CAAC;AAQlC,KAAK,aAAa,GAAG,IAAI,CACvB,cAAc,EACZ,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,aAAa,GACb,cAAc,GACd,mBAAmB,GACnB,yBAAyB,GACzB,yBAAyB,CAC5B,GAAG;IACF,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC,CAAC;AAoFF;;uEAEuE;AACvE,wBAAgB,OAAO,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAqB9C;AAsED;kDACkD;AAClD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CA8C7E"}

package/dist/bootstrap.js

@@ -77,13 +77,19 @@ function mapPlanLimit(l) {
         ...(l.enforcement ? { enforcement: l.enforcement } : {}),
     };
 }
-function mapPlan(p) {
+/** Map a snake_case wire `PortalPlan` → the camelCase domain {@link Plan}.
+ *  INTERNAL helper shared by `resolveBootstrap` (catalog) and the `/me`
+ *  account surface (`availablePlans`) — NOT part of the public API. */
+export function mapPlan(p) {
     return {
         id: p.id,
         key: p.key,
         name: p.name,
         description: p.description ?? null,
         recurringFeeCents: p.recurring_fee_cents,
+        // The platform omits `billing_interval` for monthly plans (the default);
+        // default a missing/absent value to "month" so the UI always has a cadence.
+        billingInterval: p.billing_interval === "year" ? "year" : "month",
         grants: p.grants ?? [],
         trialDays: p.trial_days,
         maxMonthlySpendCents: p.max_monthly_spend_cents ?? null,
@@ -93,8 +99,48 @@ function mapPlan(p) {
         planDetails: p.planDetails ?? [],
         featureGates: p.featureGates ?? {},
         capabilityLimits: p.capability_limits ?? {},
+        ...(p.creditPolicy ? { creditPolicy: p.creditPolicy } : {}),
     };
 }
+/** Map the resolve DTO's declared-resource catalog into the SDK domain type,
+ *  enriching each entry with its per-plan numeric `cap`. The cap is NOT on the
+ *  catalog wire shape — it lives on each plan's `capability_limits[<name>]`
+ *  (the BARE resource name, e.g. `widgets`, NOT `resource:widgets`). We resolve
+ *  it from the FEATURED plan when one is set, else the first plan that caps it,
+ *  so the catalog carries a sensible default ceiling for display. A `true`
+ *  (unlimited) or non-numeric entry leaves `cap` undefined; a resource no plan
+ *  caps stays uncapped. The authoritative live cap for the SUBSCRIBER's pinned
+ *  plan still comes from `fs.resources(name).count()` (W5.2). */
+function mapDeclaredResources(raw, plans, featuredCompiledPlanId) {
+    if (!Array.isArray(raw))
+        return [];
+    const featured = featuredCompiledPlanId
+        ? plans.find((p) => p.id === featuredCompiledPlanId)
+        : undefined;
+    function capFor(name) {
+        const fromFeatured = featured?.capabilityLimits[name];
+        if (typeof fromFeatured === "number")
+            return fromFeatured;
+        for (const plan of plans) {
+            const value = plan.capabilityLimits[name];
+            if (typeof value === "number")
+                return value;
+        }
+        return undefined;
+    }
+    return raw
+        .filter((r) => !!r && typeof r.name === "string")
+        .map((r) => {
+        const cap = capFor(r.name);
+        return {
+            name: r.name,
+            ...(r.display ? { display: r.display } : {}),
+            scope: r.scope === "subject" ? "subject" : "subscription",
+            ...(r.subjectType ? { subjectType: r.subjectType } : {}),
+            ...(cap !== undefined ? { cap } : {}),
+        };
+    });
+}
 /** Derive coarse capability keys from the resolved product + plans so a
  *  managed frontend can branch on what the product actually offers (instead of
  *  the previously hard-coded empty array). */
@@ -144,6 +190,8 @@ export async function resolveBootstrap(ctx) {
         ctx.environmentId = ctx.environmentId ?? environment.id;
     ctx.gatewayUrl = ctx.gatewayUrl ?? `https://${product.gatewayHost}`;
     return {
+        // CC5 — tolerant read: absent version means the pre-versioning shape (1).
+        schemaVersion: raw.schemaVersion ?? 1,
         product,
         environment,
         branding: product.branding,
@@ -151,6 +199,7 @@ export async function resolveBootstrap(ctx) {
         frontendReleaseHash: raw.frontendReleaseHash ?? null,
         frontendManifest: raw.frontendManifest ?? null,
         capabilities: deriveCapabilities(product, plans),
+        declaredResources: mapDeclaredResources(raw.product.declaredResources, plans, product.featuredCompiledPlanId),
         features: [],
     };
 }

package/dist/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -6,4 +6,13 @@ export interface ReadCacheEntry {
 export declare function cachedRead<T>(ctx: ClientContext, parts: ReadonlyArray<string | null | undefined>, fn: () => Promise<T>): Promise<T>;
 /** Drop every cached read — after any mutation, auth change, or org switch. */
 export declare function bustReadCache(ctx: ClientContext): void;
+/**
+ * Reset everything an ENTITLEMENT-MUTATING action invalidates (W6.3): the read
+ * cache AND the cached short-lived gateway context token. A plan change /
+ * cancel / restore / top-up / subscribe can change what the edge grants, so the
+ * next feature call must re-mint a token reflecting the new entitlement instead
+ * of riding the stale one. Use this (not bare {@link bustReadCache}) after any
+ * mutation that can move the subscriber's entitlement.
+ */
+export declare function bustEntitlementCaches(ctx: ClientContext): void;
 //# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3B;AAED,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAC/C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAEtD"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3B;AAED,wBAAgB,UAAU,CAAC,CAAC,EAC1B,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAC/C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAG9D"}

package/dist/cache.js

@@ -31,4 +31,16 @@ export function cachedRead(ctx, parts, fn) {
 export function bustReadCache(ctx) {
     ctx.readCache.clear();
 }
+/**
+ * Reset everything an ENTITLEMENT-MUTATING action invalidates (W6.3): the read
+ * cache AND the cached short-lived gateway context token. A plan change /
+ * cancel / restore / top-up / subscribe can change what the edge grants, so the
+ * next feature call must re-mint a token reflecting the new entitlement instead
+ * of riding the stale one. Use this (not bare {@link bustReadCache}) after any
+ * mutation that can move the subscriber's entitlement.
+ */
+export function bustEntitlementCaches(ctx) {
+    ctx.readCache.clear();
+    ctx.gatewayContextToken = null;
+}
 //# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,uEAAuE;AACvE,6EAA6E;AAC7E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,qEAAqE;AACrE,yEAAyE;AACzE,sCAAsC;AAItC,MAAM,WAAW,GAAG,MAAM,CAAC;AAO3B,MAAM,UAAU,UAAU,CACxB,GAAkB,EAClB,KAA+C,EAC/C,EAAoB;IAEpB,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,EAAE,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,CAAC,EAAE,GAAG,WAAW;QAAE,OAAO,GAAG,CAAC,OAAqB,CAAC;IACxE,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC;IACrB,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;QACjB,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,EAAE,CAAC;YAChD,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,GAAkB;IAC9C,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,uEAAuE;AACvE,6EAA6E;AAC7E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,qEAAqE;AACrE,yEAAyE;AACzE,sCAAsC;AAItC,MAAM,WAAW,GAAG,MAAM,CAAC;AAO3B,MAAM,UAAU,UAAU,CACxB,GAAkB,EAClB,KAA+C,EAC/C,EAAoB;IAEpB,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,EAAE,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,CAAC,EAAE,GAAG,WAAW;QAAE,OAAO,GAAG,CAAC,OAAqB,CAAC;IACxE,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC;IACrB,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;QACjB,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,EAAE,CAAC;YAChD,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,GAAkB;IAC9C,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAkB;IACtD,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACtB,GAAG,CAAC,mBAAmB,GAAG,IAAI,CAAC;AACjC,CAAC"}