@bravely-studios/account-web 0.3.4

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 Bravely Studios LLC. All rights reserved.
+
+This software is the proprietary work of Bravely Studios LLC. No part of this
+package may be reproduced, distributed, transmitted, modified, or otherwise
+exploited in any form or by any means without the prior written permission of
+Bravely Studios LLC.
+
+Unauthorized use, copying, or distribution is strictly prohibited.
+
+For licensing inquiries, contact jeff@bravely.dev.

package/README.md

@@ -0,0 +1,262 @@
+# @bravely-studios/account-web
+
+Thin TypeScript facade over the Bravely identity API for browser-based
+Bravely Studios apps. Used internally across the Bravely web app family.
+
+## What it does
+
+- **OAuth 2.1 + PKCE** sign-in via `auth.bravely.dev` — RFC 7636 S256.
+- **BAS lifecycle** — exchange / refresh against `identity.bravely.dev`.
+- **Entitlement cache** — 72h offline fallback.
+- **Activation state machine** — checkout-to-active flow.
+- **Paddle account actions** — BAS-authed checkout session and
+  customer-portal session helpers through `identity.bravely.dev`.
+- **`Bravely-Deprecation` handling** — soft warnings + hard
+  `BravelyClientKilledError` on HTTP 426 kill-switch.
+- **DPoP-ready** — RFC 9449 proof generation.
+
+## Install
+
+```bash
+npm install @bravely-studios/account-web
+```
+
+## Usage
+
+```ts
+import { BravelyAccountManager } from "@bravely-studios/account-web";
+
+const manager = new BravelyAccountManager({
+  authority: "https://auth.bravely.dev",
+  appSlug: "diskaroo",
+  clientVersion: "1.3.1",
+});
+
+// On page load
+await manager.restore();
+manager.onStateChange((state) => {
+  if (state.kind === "signed_in") renderApp(state);
+});
+
+// On a sign-in button click
+await manager.signIn();
+
+// React 19? Subscribe via useSyncExternalStore — `getState` returns a stable
+// reference between updates (0.2.1+), so no `_cachedState` workaround needed.
+//
+//   const state = useSyncExternalStore(
+//     manager.onStateChange.bind(manager),
+//     manager.getState.bind(manager),
+//   );
+
+// Entitlement gate
+if (await manager.hasEntitlement("diskaroo_pro")) {
+  showProFeatures();
+}
+
+// Paid upgrade
+await manager.openCheckout("annual");
+
+// Manage subscription
+const portal = await manager.createPaddlePortalSession();
+window.open(portal.url, "_blank");
+```
+
+## Module map
+
+| File                                    | Responsibility                                                                    |
+|-----------------------------------------|-----------------------------------------------------------------------------------|
+| `BravelyAccountManager.ts`              | Public facade. Sign-in, sign-out, entitlements, checkout, portal, activation.     |
+| `EntitlementCache.ts`                   | 72h offline cache with TTL + invalidation.                                        |
+| `ActivationStateMachine.ts`             | Port of the canonical activation machine.                                         |
+| `oauth.ts`                              | PKCE S256 helpers + authorize URL builder.                                        |
+| `storage.ts`                            | sessionStorage / IndexedDB / memory adapters.                                     |
+| `dpop.ts`                               | WebCrypto ES256 keypair + RFC 9449 proofs (Gate 2-ready).                         |
+| `deprecation.ts`                        | `Bravely-Deprecation` header parser + error classes.                              |
+| `types.ts`                              | TS types mirroring the OpenAPI 3.1 schemas.                                       |
+| `displayName.ts`                        | Slug → display-name lookup (`diskaroo` → `Diskaroo`).                             |
+| `components/ActivationLadder.tsx`       | **M3** — post-checkout 4-phase ladder (`Activating <App> Pro…`).                  |
+| `components/CrossAppCard.tsx`           | **M4** — third-quadrant card (`You own N Bravely Pro apps on this account.`).    |
+| `hooks/useActivationLaneFromUrl.ts`     | **M3** — detect `?upgraded` / `?checkout` / `?subscription` return params.        |
+| `hooks/useFreshLaunchRestoration.ts`    | **M2** — silent rehydrate + brief `Synced N items from your <device>.` toast.     |
+
+## C-ux M2/M3/M4 exports (0.2.0)
+
+Wave A of the C-ux M2-M4 rollout (`cux-m2-m4-rollout-plan.md`). New exports
+let the four D-Web variants — `prodjectly`, `scry-web`, `printscreenly-web`,
+`todoingly-web` — mount the foundational surfaces in Wave B-D.
+
+### `<ActivationLadder>` (M3)
+
+```tsx
+import { ActivationLadder } from "@bravely-studios/account-web";
+
+<ActivationLadder
+  state={manager.getActivationState()}
+  appSlug="diskaroo"
+  orderId={paddleOrderId ?? null}
+  onRetry={() => manager.pollForActivation()}
+  onContactSupport={() => window.open("mailto:jeff@bravely.dev")}
+/>
+```
+
+Renders nothing unless the manager is in `post_checkout_activation`.
+Auto-ticks elapsed every second; rolls through the 4 locked phases at
+0/15s/60s/120s. Phase copy is byte-identical to
+`bravely-commerce-router/docs/activation-state-machine.json` — the
+drift-test in `__tests__/ActivationLadder.test.tsx` enforces it.
+
+### `<CrossAppCard>` (M4)
+
+```tsx
+import { CrossAppCard } from "@bravely-studios/account-web";
+
+<CrossAppCard
+  entitlements={state.entitlements}
+  currentAppSlug="diskaroo"
+  variant="card"        // or "footer-chip"
+  dismissible={false}   // journey-doc default = persistent
+/>
+```
+
+Renders nothing when the user has zero cross-app entitlements. Excludes
+the current app's own `<slug>_pro` from the count; treats
+`bravely_premium` as a single bundle token.
+
+### `useActivationLaneFromUrl()` (M3)
+
+```tsx
+const { inActivationLane, source, clearUrlParam } = useActivationLaneFromUrl({
+  manager,
+  autoStartPolling: true,
+});
+
+useEffect(() => {
+  if (inActivationLane) clearUrlParam();
+}, [inActivationLane]);
+```
+
+Detects the three observed post-checkout return URL patterns:
+`?upgraded=true` (prodjectly), `?checkout=complete` (scry-web),
+`?subscription=success` (todoingly-web). Auto-calls
+`manager.notifyCheckoutCompleted()` and, if `autoStartPolling`, kicks
+off `manager.pollForActivation()`.
+
+### `useFreshLaunchRestoration()` (M2)
+
+```tsx
+const fresh = useFreshLaunchRestoration({
+  manager,
+  itemsLabel: "tasks",
+  resolveOtherDeviceName: () => null, // Gate 1 fallback
+});
+
+useEffect(() => {
+  fresh.setSyncedCount(myCollection.length);
+}, [myCollection.length]);
+
+return fresh.shouldShowToast ? <Toast>{fresh.toastText}</Toast> : null;
+```
+
+First-launch detector. UI is silent for 3 s after sign-in; then `Synced
+N items from your <device>.` shows for the host page to dismiss. The
+banned phrase family (`Welcome back. Restoring your Pro features`) is
+absent by design. Gate 1 device-name resolver is null; the hook drops
+the `from your <device>` anchor automatically.
+
+### Manager additions
+
+```ts
+// Cross-app filter — excludes <currentApp>_pro, includes bravely_premium.
+const others = manager.crossAppEntitlements();
+
+// Post-checkout polling runner — 30 retries × 1s..8s capped backoff.
+const result = await manager.pollForActivation();
+// result.outcome: "active" | "exhausted" | "timeout" | "not_signed_in"
+
+// Paddle customer-portal session — callers decide how to open the URL.
+const portal = await manager.createPaddlePortalSession();
+// portal.url is the hosted customer-portal URL.
+```
+
+## Storage adapters
+
+- **`sessionStorage`** — BAS, PKCE verifier, state. Wipes on tab close.
+- **`IndexedDB`** — refresh_token, entitlement cache, DPoP key handle.
+  Survives reload; key bytes never leave the browser (extractable=false).
+- **In-memory** — SSR / test fallback.
+
+Host pages can swap in their own ServiceWorker-backed adapter by passing
+`storage` into the manager config.
+
+## Activation state machine
+
+`getActivationState()` returns the current state from the canonical machine.
+Host pages render UI off the `name` (`restoring_session`, `verifying_entitlement`,
+`entitlement_cached_valid`, `post_checkout_activation`, etc.) and the
+`busy` flag (whether to show a spinner). CLAUDE.md hard rule
+`feedback_no_etas`: never render a predicted ETA — always elapsed time.
+
+## DPoP gate transition
+
+- **Gate 1 (today):** BAS-authed manager requests keep
+  `Authorization: Bearer <bas>` for router compatibility and also attach a
+  valid `DPoP` proof header with `ath`. The server runs in `off` mode and
+  accepts the Bearer scheme without verifying the proof.
+- **Gate 2 (next):** server enforcement can start from real client traffic
+  because `getAppDataToken()`, `openCheckout()`,
+  `createPaddlePortalSession()`, entitlement refreshes, and activation polls
+  already carry proof headers.
+
+## Changelog
+
+### 0.3.4 — 2026-05-13
+
+- **Infra:** package now publishes to `registry.npmjs.org` (public scope).
+  Previously hosted on GitHub Packages. No code changes; behavior is
+  identical to `0.3.3`.
+
+### 0.3.3 — 2026-05-13
+
+- **Feature:** `BravelyAccountManager` enters `fresh_launch_restoration`
+  when a BAS exists but the entitlement cache is missing, smoothing the
+  cold-start UX before the first entitlement read completes.
+
+### 0.3.2 — 2026-05-13
+
+- **Fix:** BAS-authenticated manager requests now attach an RFC 9449 `DPoP`
+  proof header, including `ath`, while preserving the Gate 1
+  `Authorization: Bearer <bas>` scheme required by current router endpoints.
+- **Fix:** fresh entitlement cache writes carry the generated DPoP JKT
+  thumbprint so Gate 2 cache binding can inspect the local key identity.
+
+### 0.3.0 — 2026-05-13
+
+- **Feature:** added `createPaddlePortalSession()`, a BAS-authed manager
+  primitive for `POST /api/paddle-portal`. It returns the hosted Paddle
+  customer-portal URL DTO and leaves checkout activation behavior unchanged.
+- **Types:** exported `PaddlePortalSession` and aligned the API baseline note
+  to `bravely-commerce-router` OpenAPI `1.2.1`.
+
+### 0.2.1 — 2026-05-12
+
+- **Fix:** `getState()` now returns a **stable reference** between writes.
+  Previously it cloned on every read, which broke React 19's
+  `useSyncExternalStore` (snapshot identity changed every render → React
+  error #185 / "Maximum update depth exceeded"). The clone now happens
+  once, inside `setState()`, before listeners fire. Listener payloads and
+  the next `getState()` call return the same object reference. Three
+  consumers (`prodjectly`, `printscreenly-web`, `todoingly-web`) carry
+  module-level `_cachedState` workarounds that become redundant with this
+  release — they can be dropped in a follow-up sweep.
+- **Fix:** internal `libVersion` default aligned to package version
+  (was hard-coded to `"0.2.0"`).
+- **Docs:** install snippet uses the correct `@bravely-studios` scope.
+
+### 0.2.0 — 2026-05-11
+
+- Initial C-ux M2/M3/M4 facade shipped.
+
+## License
+
+Proprietary. (c) 2026 Bravely Studios LLC.

package/dist/ActivationStateMachine.d.ts

@@ -0,0 +1,50 @@
+import type { ActivationState, ActivationStateName } from "./types.js";
+/** Canonical event names accepted by `transition()`. */
+export type ActivationEvent = "app_launched" | "app_launched_no_session" | "bas_found" | "bas_missing" | "bas_invalid" | "entitlement_check_success_pro" | "entitlement_check_success_none" | "entitlement_check_failure" | "checkout_completed" | "activation_polled_active" | "activation_polled_inactive" | "activation_timed_out" | "user_signed_in" | "user_skipped" | "user_clicked_retry";
+interface TransitionContext {
+    bas_present?: boolean;
+    entitlement_cache_present?: boolean;
+}
+type ConditionalTarget = {
+    when: TransitionContext;
+    to: ActivationStateName;
+    else?: ActivationStateName;
+};
+type TransitionTarget = ActivationStateName | ConditionalTarget;
+/**
+ * The retry budget for `post_checkout_activation` — matches the JSON spec.
+ * Host pages use this to schedule entitlement polling.
+ */
+export declare const POST_CHECKOUT_RETRY: {
+    readonly maxRetries: 30;
+    readonly initialBackoffMs: 1000;
+    readonly maxBackoffMs: 8000;
+    readonly backoffMultiplier: 1.5;
+};
+/** Auto-advance timeouts (ms). Matches the JSON `auto_advance_after_ms`. */
+export declare const AUTO_ADVANCE_MS: Partial<Record<ActivationStateName, number>>;
+/** The state name a given state auto-advances to on timeout. */
+export declare const AUTO_ADVANCE_TO: Partial<Record<ActivationStateName, ActivationStateName>>;
+export declare class ActivationStateMachine {
+    private state;
+    private subscribers;
+    constructor(initial?: ActivationStateName);
+    current(): ActivationState;
+    /**
+     * Attempt a transition. Returns the new state (or the unchanged state if
+     * the event is not a valid transition from the current state).
+     */
+    transition(event: ActivationEvent, ctx?: TransitionContext): ActivationState;
+    /** Force the machine into a specific state (used by activation pollers). */
+    force(name: ActivationStateName): ActivationState;
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    onStateChange(cb: (s: ActivationState) => void): () => void;
+    /** Elapsed ms since the current state was entered. */
+    elapsedMs(): number;
+    /** Lookup table introspection. */
+    static transitions: Record<ActivationStateName, Partial<Record<ActivationEvent, TransitionTarget>>>;
+    static busyStates: Set<ActivationStateName>;
+    private enter;
+}
+export {};
+//# sourceMappingURL=ActivationStateMachine.d.ts.map

package/dist/ActivationStateMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivationStateMachine.d.ts","sourceRoot":"","sources":["../src/ActivationStateMachine.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEvE,wDAAwD;AACxD,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,yBAAyB,GACzB,WAAW,GACX,aAAa,GACb,aAAa,GACb,+BAA+B,GAC/B,gCAAgC,GAChC,2BAA2B,GAC3B,oBAAoB,GACpB,0BAA0B,GAC1B,4BAA4B,GAC5B,sBAAsB,GACtB,gBAAgB,GAChB,cAAc,GACd,oBAAoB,CAAC;AAEzB,UAAU,iBAAiB;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,iBAAiB,CAAC;IACxB,EAAE,EAAE,mBAAmB,CAAC;IACxB,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B,CAAC;AAEF,KAAK,gBAAgB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAwDhE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,4EAA4E;AAC5E,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAKxE,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAKrF,CAAC;AAEF,qBAAa,sBAAsB;IACjC,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,WAAW,CAA2C;gBAElD,OAAO,GAAE,mBAA4B;IAIjD,OAAO,IAAI,eAAe;IAI1B;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,GAAE,iBAAsB,GAAG,eAAe;IAShF,4EAA4E;IAC5E,KAAK,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe;IAIjD,mEAAmE;IACnE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAK3D,sDAAsD;IACtD,SAAS,IAAI,MAAM;IAInB,kCAAkC;IAClC,MAAM,CAAC,WAAW,kFAAe;IACjC,MAAM,CAAC,UAAU,2BAAe;IAEhC,OAAO,CAAC,KAAK;CAKd"}

package/dist/ActivationStateMachine.js

@@ -0,0 +1,141 @@
+// Port of bravely-commerce-router/docs/activation-state-machine.json (v1.0.0).
+//
+// Keep aligned by hand. The canonical doc is the source of truth; this port
+// is a thin TS surface so host pages can render UI off `getActivationState()`.
+//
+// CLAUDE.md feedback_no_etas: every state surfaces ELAPSED time, never a
+// predicted ETA. Anti-patterns from M5 enforced in the banned-phrases CI
+// check (in bravely-commerce-router); the strings here MUST match the JSON.
+const TRANSITIONS = {
+    idle: {
+        app_launched: { when: { bas_present: true }, to: "restoring_session" },
+        app_launched_no_session: { when: { bas_present: false }, to: "pending_user_action" },
+    },
+    restoring_session: {
+        bas_found: "verifying_entitlement",
+        bas_missing: "fresh_launch_restoration",
+        bas_invalid: "pending_user_action",
+    },
+    verifying_entitlement: {
+        entitlement_check_success_pro: "entitlement_fresh_valid",
+        entitlement_check_success_none: "entitlement_none",
+        entitlement_check_failure: {
+            when: { entitlement_cache_present: true },
+            to: "entitlement_cached_valid",
+            else: "failed",
+        },
+    },
+    entitlement_cached_valid: {
+        entitlement_check_success_pro: "entitlement_fresh_valid",
+        entitlement_check_success_none: "entitlement_none",
+        entitlement_check_failure: "entitlement_cached_valid",
+    },
+    entitlement_fresh_valid: {},
+    entitlement_none: {
+        checkout_completed: "post_checkout_activation",
+    },
+    post_checkout_activation: {
+        activation_polled_active: "entitlement_fresh_valid",
+        activation_polled_inactive: "post_checkout_activation",
+        activation_timed_out: "failed",
+    },
+    fresh_launch_restoration: {
+        entitlement_check_success_pro: "entitlement_fresh_valid",
+        entitlement_check_success_none: "entitlement_none",
+        entitlement_check_failure: "failed",
+    },
+    pending_user_action: {
+        user_signed_in: "restoring_session",
+        user_skipped: "entitlement_none",
+    },
+    failed: {
+        user_clicked_retry: "pending_user_action",
+    },
+};
+const BUSY_STATES = new Set([
+    "restoring_session",
+    "verifying_entitlement",
+    "post_checkout_activation",
+    "fresh_launch_restoration",
+]);
+/**
+ * The retry budget for `post_checkout_activation` — matches the JSON spec.
+ * Host pages use this to schedule entitlement polling.
+ */
+export const POST_CHECKOUT_RETRY = {
+    maxRetries: 30,
+    initialBackoffMs: 1000,
+    maxBackoffMs: 8000,
+    backoffMultiplier: 1.5,
+};
+/** Auto-advance timeouts (ms). Matches the JSON `auto_advance_after_ms`. */
+export const AUTO_ADVANCE_MS = {
+    restoring_session: 8000,
+    verifying_entitlement: 8000,
+    post_checkout_activation: 120_000,
+    fresh_launch_restoration: 10_000,
+};
+/** The state name a given state auto-advances to on timeout. */
+export const AUTO_ADVANCE_TO = {
+    restoring_session: "failed",
+    verifying_entitlement: "failed",
+    post_checkout_activation: "failed",
+    fresh_launch_restoration: "failed",
+};
+export class ActivationStateMachine {
+    state;
+    subscribers = new Set();
+    constructor(initial = "idle") {
+        this.state = { name: initial, enteredAt: new Date(), busy: BUSY_STATES.has(initial) };
+    }
+    current() {
+        return { ...this.state };
+    }
+    /**
+     * Attempt a transition. Returns the new state (or the unchanged state if
+     * the event is not a valid transition from the current state).
+     */
+    transition(event, ctx = {}) {
+        const fromTable = TRANSITIONS[this.state.name];
+        const target = fromTable[event];
+        if (!target)
+            return this.current(); // no-op
+        const next = resolveTarget(target, ctx);
+        if (!next)
+            return this.current();
+        return this.enter(next);
+    }
+    /** Force the machine into a specific state (used by activation pollers). */
+    force(name) {
+        return this.enter(name);
+    }
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    onStateChange(cb) {
+        this.subscribers.add(cb);
+        return () => this.subscribers.delete(cb);
+    }
+    /** Elapsed ms since the current state was entered. */
+    elapsedMs() {
+        return Date.now() - this.state.enteredAt.getTime();
+    }
+    /** Lookup table introspection. */
+    static transitions = TRANSITIONS;
+    static busyStates = BUSY_STATES;
+    enter(name) {
+        this.state = { name, enteredAt: new Date(), busy: BUSY_STATES.has(name) };
+        for (const cb of this.subscribers)
+            cb({ ...this.state });
+        return this.current();
+    }
+}
+function resolveTarget(target, ctx) {
+    if (typeof target === "string")
+        return target;
+    for (const [k, v] of Object.entries(target.when)) {
+        if (ctx[k] !== v) {
+            return target.else ?? null;
+        }
+    }
+    return target.to;
+}
+//# sourceMappingURL=ActivationStateMachine.js.map

package/dist/ActivationStateMachine.js.map

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

package/dist/BravelyAccountManager.d.ts

@@ -0,0 +1,156 @@
+import type { BravelyAccountState, ManagerConfig, Entitlement, CheckoutPlan, PaddlePortalSession, ActivationState, LibVersionPolicy } from "./types.js";
+import { BravelyClientKilledError, OAuthError } from "./deprecation.js";
+/** Result of `pollForActivation()` — the manager's M3 activation runner. */
+export type ActivationResult = {
+    outcome: "active";
+    entitlements: Entitlement[];
+    attempts: number;
+} | {
+    outcome: "timeout";
+    attempts: number;
+} | {
+    outcome: "exhausted";
+    attempts: number;
+} | {
+    outcome: "not_signed_in";
+};
+type StateListener = (state: BravelyAccountState) => void;
+export declare class BravelyAccountManager {
+    private readonly cfg;
+    private readonly storage;
+    private readonly cache;
+    private readonly activation;
+    private state;
+    private listeners;
+    private libVersionPolicy;
+    private dpopKeypairPromise;
+    private dpopJktThumbprint;
+    constructor(config: ManagerConfig);
+    /**
+     * Return the current state. The returned reference is **stable across
+     * calls** until `setState()` is invoked — i.e. while the state has not
+     * changed, two consecutive `getState()` calls produce values for which
+     * `Object.is(a, b)` is true.
+     *
+     * This is the contract React 19's `useSyncExternalStore` requires: the
+     * `getSnapshot` callback must return `===` identical values until the
+     * `subscribe` callback fires. Returning a fresh clone on every read (which
+     * an earlier version of this facade did) triggers React error #185 —
+     * "Maximum update depth exceeded" — because the snapshot keeps "changing"
+     * even when nothing has happened.
+     *
+     * The clone happens once, at write time, inside `setState()`. Listeners
+     * receive the same reference this method returns until the next
+     * `setState()` swaps in a new canonical clone.
+     */
+    getState(): BravelyAccountState;
+    onStateChange(cb: StateListener): () => void;
+    getActivationState(): ActivationState;
+    getLibVersionPolicy(): LibVersionPolicy | null;
+    /**
+     * Hydrate from persistent storage and (if a BAS is present) verify it
+     * against the identity API. Call once on page load before rendering UI
+     * that depends on `getState()`.
+     */
+    restore(): Promise<BravelyAccountState>;
+    /**
+     * Begin the OAuth 2.1 + PKCE sign-in dance. Resolves to the new state. If
+     * the browser is at the start of the dance, this triggers a redirect
+     * (and the promise effectively never resolves before unload). If the
+     * browser is on the callback URL with `?code=...&state=...`, this finishes
+     * the exchange.
+     */
+    signIn(opts?: {
+        loginHint?: string;
+    }): Promise<BravelyAccountState>;
+    /** Sign out: drop local state. Server-side revoke is best-effort. */
+    signOut(): Promise<void>;
+    /**
+     * Read entitlements, serving the cached row if fresh and refreshing
+     * opportunistically. Always returns an array (possibly empty).
+     */
+    getEntitlements(): Promise<Entitlement[]>;
+    /** Convenience: check a single entitlement (e.g. `diskaroo_pro`). */
+    hasEntitlement(lookupKey: string): Promise<boolean>;
+    /** Mint an app-data-token for apps that need direct Firebase SDK access. */
+    getAppDataToken(): Promise<string>;
+    /**
+     * Open Paddle hosted-checkout for the given plan. Hits
+     * `/api/checkout/sessions` (BAS-authed), opens the returned URL via the
+     * system browser (`window.open(url, '_blank')`). The promise resolves once
+     * the request returns; the caller is responsible for polling
+     * `getEntitlements()` (or watching `getActivationState()`) for the
+     * post-checkout activation.
+     */
+    openCheckout(plan: CheckoutPlan): Promise<void>;
+    /**
+     * Mint a Paddle customer-portal session for the signed-in account.
+     * Consumers decide how to open `session.url`; checkout activation state is
+     * intentionally unchanged.
+     */
+    createPaddlePortalSession(): Promise<PaddlePortalSession>;
+    /** Inform the manager that checkout completion was observed. */
+    notifyCheckoutCompleted(): void;
+    /**
+     * Return the active entitlements that count as "cross-app" for the M4
+     * `<CrossAppCard>`. Excludes the current app's own `<slug>_pro` token.
+     * `bravely_premium` (the bundle entitlement) is included — it's the
+     * unifying signal that drives the M4 copy ("You own N Bravely Pro
+     * apps").
+     *
+     * Reads from the in-memory signed-in state (which mirrors the
+     * `EntitlementCache`); does not hit the network. Host pages that need a
+     * fresh fetch should call `getEntitlements()` first.
+     */
+    crossAppEntitlements(): Entitlement[];
+    /**
+     * Run the canonical M3 post-checkout activation polling loop against
+     * `/api/entitlements?app=<slug>`. Uses the retry budget locked in
+     * `POST_CHECKOUT_RETRY` (30 retries, 1s..8s capped exponential
+     * backoff). Fires the right activation state events as it runs.
+     *
+     * Returns:
+     *   - `{ outcome: "active" }` as soon as an entitlement is observed
+     *     (typically `<currentApp>_pro` or `bravely_premium`).
+     *   - `{ outcome: "exhausted" }` after `maxRetries` attempts without an
+     *     active entitlement.
+     *   - `{ outcome: "timeout" }` if total elapsed time hits the auto-
+     *     advance ceiling for `post_checkout_activation` (120s).
+     *   - `{ outcome: "not_signed_in" }` if no BAS is present.
+     *
+     * The promise resolves regardless of network failures. Each failure
+     * is treated as an inactive poll (the user's purchase is still safe;
+     * the activation state machine surfaces this via the ladder copy).
+     */
+    pollForActivation(): Promise<ActivationResult>;
+    private completeAuthorization;
+    private persistToken;
+    private refreshEntitlements;
+    /**
+     * Gate 1 compatibility path: keep `Authorization: Bearer <bas>` because
+     * the current router accepts Bearer on shared BAS endpoints, but attach a
+     * real RFC 9449 proof in the `DPoP` header so Gate 2 traffic is already
+     * exercising proof generation.
+     */
+    private fetchWithBas;
+    private dpopProof;
+    private getDpopKeypair;
+    /** Fetch wrapper that processes the `Bravely-Deprecation` header on every response. */
+    private fetchWithDeprecation;
+    private requireBas;
+    /**
+     * Replace the canonical in-memory state.
+     *
+     * Clones `next` once and stores the clone as `this.state` BEFORE notifying
+     * listeners. Listeners receive the same reference subsequent `getState()`
+     * calls will return — required for `useSyncExternalStore` consumers (see
+     * `getState()` for the React #185 background).
+     *
+     * Cloning at write time also seals off any external references the caller
+     * still holds to `next`: later mutations of `next` (or its nested
+     * `entitlements` array) cannot leak into `this.state`.
+     */
+    private setState;
+}
+export { BravelyClientKilledError, OAuthError };
+//# sourceMappingURL=BravelyAccountManager.d.ts.map

package/dist/BravelyAccountManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BravelyAccountManager.d.ts","sourceRoot":"","sources":["../src/BravelyAccountManager.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EACb,WAAW,EAEX,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAEL,wBAAwB,EACxB,UAAU,EACX,MAAM,kBAAkB,CAAC;AAE1B,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,WAAW,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAgBjC,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAE1D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CACmF;IACvG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,kBAAkB,CAA4C;IACtE,OAAO,CAAC,iBAAiB,CAAuB;gBAEpC,MAAM,EAAE,aAAa;IA0BjC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,IAAI,mBAAmB;IAI/B,aAAa,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,IAAI;IAK5C,kBAAkB,IAAI,eAAe;IAIrC,mBAAmB,IAAI,gBAAgB,GAAG,IAAI;IAI9C;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC;IA4B7C;;;;;;OAMG;IACG,MAAM,CAAC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6B7E,qEAAqE;IAC/D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B9B;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAU/C,qEAAqE;IAC/D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKzD,4EAA4E;IACtE,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAYxC;;;;;;;OAOG;IACG,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBrD;;;;OAIG;IACG,yBAAyB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAW/D,gEAAgE;IAChE,uBAAuB,IAAI,IAAI;IAI/B;;;;;;;;;;OAUG;IACH,oBAAoB,IAAI,WAAW,EAAE;IAMrC;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC;YAuEtC,qBAAqB;YAoCrB,YAAY;YA4BZ,mBAAmB;IA+CjC;;;;;OAKG;YACW,YAAY;YASZ,SAAS;YAgBT,cAAc;IAmB5B,uFAAuF;YACzE,oBAAoB;YAkCpB,UAAU;IAMxB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ;CAMjB;AA4CD,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,CAAC"}