@usethrottle/auth 0.1.2 → 0.2.1

package/CLAUDE.md

@@ -36,6 +36,31 @@ points: `.` (core), `./react`, `./forms` — see `exports` in `package.json`.
   empty `useOrders`/`useAddresses` results by adding client-side workarounds;
   see the README's "Email verification and the claim cutoff" section.
 
+## Components layer (`src/react/components/`, `./components` entry)
+
+- **Step-up interception already exists in the core.** `client.ts:168`
+  intercepts `403 step_up_required` and calls `onStepUpRequired()` before
+  retrying the call once. `ThrottleProvider` supplies that callback (it opens
+  `StepUpDialog` and resolves the promise from the dialog's submit/cancel) —
+  it does not, and must not, re-implement the interception itself.
+- **`ThrottleProvider` composes `ThrottleAuthProvider`, it does not replace
+  it.** It builds the `ThrottleAuth` client itself (so it can pass
+  `onStepUpRequired` at construction time) and hands that client to
+  `ThrottleAuthProvider` via the `auth` injection prop that already exists for
+  this purpose. Every hook from `./react` (`useAuth`, `useCustomer`,
+  `useOrders`, …) keeps working underneath unchanged.
+- **Every rule in `styles.ts` must stay a single-class selector.** A merchant
+  className from `appearance.elements` lands on the same element as the
+  shipped class, so an override wins only via equal specificity + source
+  order. A descendant selector (e.g. `.throttle-card .throttle-button`) would
+  silently outrank a merchant's override no matter what class they add.
+- **`THROTTLE_ELEMENT_KEYS` (in `appearance.tsx`) is public API.** It is the
+  exhaustive list of every `data-throttle-element` a component may render.
+  Adding a rendered element without adding its key here passes typecheck and
+  build but fails `element-keys.test.tsx`, which mounts a sweep of components
+  and asserts every `data-throttle-element` found is in the list — the element
+  would otherwise be unreachable through `appearance.elements` for merchants.
+
 ## Conventions
 
 - Every exported function's public surface is asserted in `src/exports.test.ts`

package/README.md

@@ -189,6 +189,264 @@ function Orders() {
 - `useSubscriptions(page?)` — `cancel(id, { atPeriodEnd })`, `pause(id)`,
   `resume(id)`.
 
+## Drop-in components
+
+A third entry point, `@usethrottle/auth/components`, ships pre-styled React
+components on top of everything above — a sign-in form, an account dropdown, a
+full account dashboard — so most storefronts never touch `useAuth`/`useCustomer`
+directly. It re-exports the whole `./react` hooks surface too, so this is the
+only import path a component-using storefront needs.
+
+### Quick start
+
+```tsx
+import { ThrottleProvider, UserButton, SignInButton, SignedIn, SignedOut }
+  from '@usethrottle/auth/components';
+
+export default function Layout({ children }) {
+  return (
+    <ThrottleProvider publishableKey={process.env.NEXT_PUBLIC_THROTTLE_PK}>
+      <nav>
+        <SignedIn><UserButton /></SignedIn>
+        <SignedOut><SignInButton /></SignedOut>
+      </nav>
+      {children}
+    </ThrottleProvider>
+  );
+}
+```
+
+`<ThrottleProvider>` replaces `<ThrottleAuthProvider>` from `./react` — it
+takes the same `publishableKey`/`baseUrl`/`storage`/`claimCartOnSignIn` config,
+plus `appearance` and `localization` (below) and `injectStyles`. It composes
+the existing provider rather than replacing it, so every hook from `./react`
+keeps working underneath unchanged.
+
+`<SignedIn>`, `<SignedOut>` and `<Protect requireVerified fallback={...}>` are
+conditional-render guards — they render nothing while the session is still
+loading, so a navbar never flashes the wrong state during session restore.
+`<Protect>` additionally gates on `emailVerified` when `requireVerified` is set.
+
+### Components
+
+| Component | Purpose | Key props |
+| --------- | ------- | --------- |
+| `SignIn` | Email/password sign-in form. | `onSuccess()`, `onForgotPassword()`, `onSignUp()`, `appearance`, `localization` |
+| `SignUp` | Registration form. | `onSuccess()`, `onSignIn()`, `appearance`, `localization` |
+| `ForgotPassword` | Requests a reset-link email. | `onBack()`, `appearance`, `localization` |
+| `ResetPassword` | Consumes a reset-link token, sets a new password. | `token`, `onSuccess()`, `appearance`, `localization` |
+| `VerifyEmail` | Consumes a verification-link token, or offers a resend prompt with no token. | `token`, `onSuccess()`, `appearance`, `localization` |
+| `AuthFlow` | Switches between all five auth views above, with optional hash-based routing. | `initialView` / `view` + `onViewChange` (controlled), `routing: 'virtual' \| 'hash'`, `afterSignIn()`, `afterSignUp()` |
+| `AuthModal` | `AuthFlow` in an overlay. | `open`, `onClose()`, `initialView`, `afterSignIn()` |
+| `SignInButton` | Opens `AuthModal` (`mode="modal"`, default) or links to a URL (`mode="redirect"`). | `mode`, `url`, `initialView`, `asChild`, `afterSignIn()` |
+| `SignOutButton` | Signs out; `everywhere` revokes every session (may prompt step-up). | `everywhere`, `onSignedOut()` |
+| `UserButton` | Signed-in identity dropdown: manage account, sign out. Renders nothing while signed out. | `mode: 'modal' \| 'navigate'`, `accountUrl`, `tabs`, `afterSignOut()` |
+| `AccountDashboard` | Tabbed account shell composing all nine panels below. | `tabs` (defaults to all seven), `tab` / `onTabChange` (controlled), `routing: 'virtual' \| 'hash'` |
+| `VerifyEmailBanner` | Persistent "verify your email" banner with a resend button. | `appearance`, `localization` |
+| `ProfilePanel` | Name/phone/company/marketing-opt-in form. | `appearance`, `localization` |
+| `AddressesPanel` | List, add, edit, delete, and set-default addresses. | `appearance`, `localization` |
+| `PaymentMethodsPanel` | List saved cards, set default, remove. Read-only for adding — see Known limits. | `appearance`, `localization` |
+| `OrdersPanel` | Order list; drills into `OrderDetail` internally. | `onViewSubscription(id)`, `appearance`, `localization` |
+| `OrderDetail` | One order's line items, totals, and addresses. | `orderId`, `onBack()`, `onViewSubscription(id)`, `appearance`, `localization` |
+| `InvoicesPanel` | Invoice list; drills into `InvoiceDetail` internally. | `appearance`, `localization` |
+| `InvoiceDetail` | One invoice's totals and a PDF download button. | `appearance`, `localization` |
+| `SubscriptionsPanel` | Subscription list: cancel (now or at period end), pause, resume. | `appearance`, `localization` |
+| `SecurityPanel` | Change-password form and active-device session list. | `appearance`, `localization` |
+
+Every panel behind the buyer plane's verified-only routes (`OrdersPanel`,
+`InvoicesPanel`, `PaymentMethodsPanel`, `SubscriptionsPanel`) renders the
+[claim-cutoff](#email-verification-and-the-claim-cutoff) empty state
+automatically while `emailVerified` is `false` — you do not need to gate them
+yourself, though `<Protect requireVerified>` is still useful for gating an
+entire route. `AddressesPanel` is not claim-cutoff gated — the server does not
+require a verified email to read or write addresses.
+
+### Theming
+
+Two independent knobs, both accepted as an `appearance` prop on
+`ThrottleProvider` (applies to everything below it) or on any individual
+component (merges with, and overrides, the provider's value — so a component
+prop only needs to carry what's different):
+
+```tsx
+<ThrottleProvider
+  publishableKey={pk}
+  appearance={{
+    theme: 'auto',                 // 'light' | 'dark' | 'auto' (follows prefers-color-scheme)
+    variables: {
+      colorPrimary: '#7c3aed',
+      colorPrimaryForeground: '#ffffff',
+      borderRadius: '6px',
+      fontFamily: 'Inter, system-ui, sans-serif',
+    },
+    elements: {
+      // key → className appended alongside the built-in class
+      'signIn.submitButton': 'my-brand-button',
+      card: 'my-brand-card',
+    },
+    components: {
+      // swap a primitive wholesale instead of just restyling it
+      Spinner: MyBrandSpinner,
+    },
+  }}
+>
+```
+
+**`variables`** — CSS custom properties, set on the `.throttle-root` wrapper
+every top-level component renders:
+
+| Variable key | CSS custom property | Default (light) |
+| ------------ | -------------------- | ---------------- |
+| `colorPrimary` | `--throttle-color-primary` | `#18181b` |
+| `colorPrimaryForeground` | `--throttle-color-primary-foreground` | `#ffffff` |
+| `colorBackground` | `--throttle-color-background` | `#ffffff` |
+| `colorSurface` | `--throttle-color-surface` | `#f8fafc` |
+| `colorForeground` | `--throttle-color-foreground` | `#0e1116` |
+| `colorMuted` | `--throttle-color-muted` | `#eceef2` |
+| `colorMutedForeground` | `--throttle-color-muted-foreground` | `#5b6472` |
+| `colorBorder` | `--throttle-color-border` | `#e2e8f0` |
+| `colorDanger` | `--throttle-color-danger` | `#c2321f` |
+| `colorDangerSurface` | `--throttle-color-danger-surface` | `#fef2f2` |
+| `colorDangerBorder` | `--throttle-color-danger-border` | `#fecaca` |
+| `colorSuccess` | `--throttle-color-success` | `#127a4a` |
+| `colorSuccessSurface` | `--throttle-color-success-surface` | `#ecfdf5` |
+| `colorSuccessBorder` | `--throttle-color-success-border` | `#a7f3d0` |
+| `colorWarning` | `--throttle-color-warning` | `#92400e` |
+| `colorWarningSurface` | `--throttle-color-warning-surface` | `#fffbeb` |
+| `colorWarningBorder` | `--throttle-color-warning-border` | `#fde68a` |
+| `fontFamily` | `--throttle-font-family` | system font stack |
+| `fontSize` | `--throttle-font-size` | `16px` |
+| `borderRadius` | `--throttle-radius` | `12px` |
+| `borderWidth` | `--throttle-border-width` | `1px` |
+| `spacing` | `--throttle-spacing` | `8px` |
+| `shadowCard` | `--throttle-shadow-card` | `0 1px 3px rgba(15,23,42,.08), 0 1px 2px rgba(15,23,42,.04)` |
+| `shadowPopover` | `--throttle-shadow-popover` | `0 10px 24px rgba(15,23,42,.12), 0 2px 6px rgba(15,23,42,.06)` |
+| `transition` | `--throttle-transition` | `150ms cubic-bezier(.2,0,.2,1)` |
+| `zModal` | `--throttle-z-modal` | `2147483000` |
+| `zPopover` | `--throttle-z-popover` | `2147482000` |
+
+### Set `colorPrimary` and `colorPrimaryForeground` together
+
+`colorPrimaryForeground` is the text colour drawn on top of `colorPrimary`. They
+are separate variables, so overriding only the first leaves the theme's own
+foreground in place — white in light, near-black in dark — and the pair is not
+always readable. A terracotta primary on its own measures 3.65:1 against the
+dark theme's foreground, below the 4.5:1 WCAG asks for button text.
+
+In development the components measure the pair and warn once in the console when
+it falls short, naming the ratio and the theme it fails in. Nothing is logged in
+production builds, and colours we cannot parse (`var(--brand)`, `rgb(...)`,
+named colours) are left alone rather than guessed at.
+
+An unrecognized key is dropped rather than passed through — a typo never
+silently reaches the DOM as a custom property that does nothing. `theme: 'dark'`
+swaps every color variable's default; `'auto'` follows
+`prefers-color-scheme` and swaps only when `theme` is left unset.
+
+**`elements`** — every element a component renders carries a stable key
+(`'signIn.submitButton'`, `'card'`, `'field.input'`, …) via
+`data-throttle-element` in the DOM, and `THROTTLE_ELEMENT_KEYS` is the
+exhaustive, frozen list of them. Map any key to a className in `elements` and
+it is appended alongside the shipped class — every shipped rule is a single
+class selector, so an appended class of equal specificity wins on source
+order. This means Tailwind utility classes work directly, no wrapper needed:
+
+```tsx
+appearance={{
+  elements: {
+    'signIn.submitButton': 'bg-violet-600 hover:bg-violet-700 text-white rounded-lg',
+    card: 'shadow-xl rounded-2xl ring-1 ring-violet-100',
+    'field.input': 'focus:ring-2 focus:ring-violet-500',
+  },
+}}
+```
+
+If your bundler ever loads Tailwind's stylesheet *after* ours (order no longer
+in your favor), add Tailwind's `!` important prefix (`!bg-violet-600`) rather
+than fighting load order — it's a one-character fix that works regardless of
+which stylesheet lands last.
+
+### Localization
+
+```tsx
+<ThrottleProvider
+  publishableKey={pk}
+  localization={{
+    signIn: { title: 'Welcome back', submitButton: 'Log in' },
+    errors: { weak_password: 'Choose a longer password.' },
+  }}
+>
+```
+
+Every string in `enUS` (also exported, for reference or as a base to spread
+from) can be overridden at any depth — a component prop only needs the keys it
+changes, and everything else falls back to the default English copy.
+
+`errors` is a `code → message` map layered in front of the shipped
+`ThrottleAuthError` → copy mapping: when a call fails, a component looks up
+`errors[err.code]` first and only falls back to the built-in message if that
+key is absent. Use it to customize copy for `weak_password`,
+`too_many_attempts`, or any other `ThrottleAuthError` code from the
+[Errors](#errors) table above, without losing the built-in messages for every
+code you don't override.
+
+### Styles
+
+Styles auto-inject on mount by default (`<ThrottleProvider injectStyles>`, true
+unless set otherwise) via a single `<style>` tag, so a plain
+`npm install` + `<ThrottleProvider>` is enough to see fully-styled components.
+For a flash-free SSR paint, disable the runtime injection and import the
+stylesheet directly instead, so it's present in the very first paint:
+
+```tsx
+import '@usethrottle/auth/styles.css';
+// ...
+<ThrottleProvider publishableKey={pk} injectStyles={false}>
+```
+
+### Next.js App Router
+
+Put `<ThrottleProvider>` once, in the root layout. Every drop-in component is
+already a client component internally — nothing under it needs its own
+`'use client'` directive:
+
+```tsx
+// app/layout.tsx
+import { ThrottleProvider } from '@usethrottle/auth/components';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <ThrottleProvider publishableKey={process.env.NEXT_PUBLIC_THROTTLE_PK!}>
+          {children}
+        </ThrottleProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Known limits
+
+- **No add-card control.** There is no buyer-plane route for creating a saved
+  payment method (see [What this package does NOT do](#what-this-package-does-not-do)),
+  so `PaymentMethodsPanel` only lists, sets a default, and removes — it never
+  renders a card-entry form. Add cards through
+  [`@usethrottle/payment-methods`](https://usethrottle.dev/docs/developers/payment-methods)
+  (a merchant-minted client token, separate from this package), then let
+  `PaymentMethodsPanel` (or `useSavedCards()`) pick up the new card on its next
+  fetch.
+- **`<SignUp/>`'s success copy is deliberately hedged.** The register endpoint
+  returns the same `pending` status, and sends no email, both for a genuinely
+  new address and for a repeat attempt on an address that already has an
+  account — the server cannot tell your UI which case happened without leaking
+  which emails are registered. So the shipped copy reads "If that email is
+  new, check your inbox…" rather than "We sent you an email" — the latter
+  would be false in the second case. Override `localization.signUp.pendingNotice`
+  if you want different wording, but keep it similarly non-committal for the
+  same reason.
+
 ## Email verification and the claim cutoff
 
 **This is the single most surprising thing about this API — read it before

package/dist/chunk-AIXBUDOT.js

@@ -0,0 +1,50 @@
+"use client";
+
+// src/react/forms/messages.ts
+function waitCopy(seconds) {
+  if (!seconds || !Number.isFinite(seconds)) return "Please wait a moment and try again.";
+  if (seconds < 60) return `Please wait ${Math.ceil(seconds)} seconds and try again.`;
+  const minutes = Math.ceil(seconds / 60);
+  return `Please wait ${minutes} ${minutes === 1 ? "minute" : "minutes"} and try again.`;
+}
+function messageForError(err) {
+  const e = err;
+  switch (e?.code) {
+    case "invalid_credentials":
+      return "That email or password is not correct.";
+    case "weak_password":
+      return e.message || "Please choose a stronger password.";
+    case "too_many_attempts":
+      return `Too many attempts. ${waitCopy(e.retryAfter)}`;
+    case "verification_required":
+      return "Please verify your email address to continue.";
+    case "step_up_required":
+      return "Please re-enter your password to continue.";
+    case "session_revoked":
+      return "Your session has ended. Please sign in again.";
+    case "token_expired":
+    case "token_invalid":
+    case "token_already_used":
+      return "That link is no longer valid. Please request a new link.";
+    case "auth_unavailable":
+      return "Accounts are briefly unavailable. Please try again shortly.";
+    case "origin_not_allowed":
+    case "auth_not_enabled":
+    case "invalid_api_key":
+    case "environment_mismatch":
+      return "Accounts are not available right now. Please contact support.";
+    case "cart_already_claimed":
+      return "That cart belongs to a different account.";
+    case "not_found":
+      return "We could not find that.";
+    case "payment_method_in_use":
+      return e.message || "That payment method is in use and cannot be removed.";
+    default:
+      return "Something went wrong. Please try again.";
+  }
+}
+
+export {
+  messageForError
+};
+//# sourceMappingURL=chunk-AIXBUDOT.js.map

package/dist/chunk-AIXBUDOT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/forms/messages.ts"],"sourcesContent":["import { ThrottleAuthError } from '../../errors';\n\nfunction waitCopy(seconds?: number): string {\n  if (!seconds || !Number.isFinite(seconds)) return 'Please wait a moment and try again.';\n  if (seconds < 60) return `Please wait ${Math.ceil(seconds)} seconds and try again.`;\n  const minutes = Math.ceil(seconds / 60);\n  return `Please wait ${minutes} ${minutes === 1 ? 'minute' : 'minutes'} and try again.`;\n}\n\n/**\n * Buyer-facing copy for every code the storefront API returns. Two codes are\n * deliberately NOT passed through from the server: `invalid_credentials` (the\n * server is vague on purpose — enumerating accounts through our own UI would\n * undo that) and anything unrecognised.\n */\nexport function messageForError(err: unknown): string {\n  const e = err as Partial<ThrottleAuthError> & { code?: string };\n  switch (e?.code) {\n    case 'invalid_credentials':\n      return 'That email or password is not correct.';\n    case 'weak_password':\n      // The server's message IS the policy reason (\"Use at least 12 characters\").\n      return e.message || 'Please choose a stronger password.';\n    case 'too_many_attempts':\n      return `Too many attempts. ${waitCopy(e.retryAfter)}`;\n    case 'verification_required':\n      return 'Please verify your email address to continue.';\n    case 'step_up_required':\n      return 'Please re-enter your password to continue.';\n    case 'session_revoked':\n      return 'Your session has ended. Please sign in again.';\n    case 'token_expired':\n    case 'token_invalid':\n    case 'token_already_used':\n      return 'That link is no longer valid. Please request a new link.';\n    case 'auth_unavailable':\n      return 'Accounts are briefly unavailable. Please try again shortly.';\n    case 'origin_not_allowed':\n    case 'auth_not_enabled':\n    case 'invalid_api_key':\n    case 'environment_mismatch':\n      // Merchant misconfiguration, not something the buyer can fix.\n      return 'Accounts are not available right now. Please contact support.';\n    case 'cart_already_claimed':\n      return 'That cart belongs to a different account.';\n    case 'not_found':\n      return 'We could not find that.';\n    case 'payment_method_in_use':\n      // The server's message IS the fix (\"set another card as default\n      // first\") — same rationale as weak_password below.\n      return e.message || 'That payment method is in use and cannot be removed.';\n    default:\n      return 'Something went wrong. Please try again.';\n  }\n}\n"],"mappings":";;;AAEA,SAAS,SAAS,SAA0B;AAC1C,MAAI,CAAC,WAAW,CAAC,OAAO,SAAS,OAAO,EAAG,QAAO;AAClD,MAAI,UAAU,GAAI,QAAO,eAAe,KAAK,KAAK,OAAO,CAAC;AAC1D,QAAM,UAAU,KAAK,KAAK,UAAU,EAAE;AACtC,SAAO,eAAe,OAAO,IAAI,YAAY,IAAI,WAAW,SAAS;AACvE;AAQO,SAAS,gBAAgB,KAAsB;AACpD,QAAM,IAAI;AACV,UAAQ,GAAG,MAAM;AAAA,IACf,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAEH,aAAO,EAAE,WAAW;AAAA,IACtB,KAAK;AACH,aAAO,sBAAsB,SAAS,EAAE,UAAU,CAAC;AAAA,IACrD,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAEH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAGH,aAAO,EAAE,WAAW;AAAA,IACtB;AACE,aAAO;AAAA,EACX;AACF;","names":[]}

package/dist/chunk-HGBAIM6B.js

@@ -0,0 +1,140 @@
+"use client";
+import {
+  ThrottleAuthError,
+  useAuth
+} from "./chunk-SZ427BQ3.js";
+
+// src/react/hooks.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function asError(err) {
+  if (err instanceof ThrottleAuthError) return err;
+  const anyErr = err;
+  return new ThrottleAuthError({
+    code: anyErr?.code ?? "request_failed",
+    message: anyErr?.message ?? String(err),
+    statusCode: anyErr?.statusCode ?? 0
+  });
+}
+function useResource(empty, load, deps) {
+  const { status, emailVerified } = useAuth();
+  const [data, setData] = useState(empty);
+  const [isLoading, setIsLoading] = useState(status === "loading");
+  const [error, setError] = useState(null);
+  const gen = useRef(0);
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+      gen.current++;
+    };
+  }, []);
+  const refetch = useCallback(async () => {
+    const mine = ++gen.current;
+    setIsLoading(true);
+    try {
+      const next = await load();
+      if (!alive.current || gen.current !== mine) return;
+      setData(next);
+      setError(null);
+    } catch (err) {
+      if (!alive.current || gen.current !== mine) return;
+      setError(asError(err));
+    } finally {
+      if (alive.current && gen.current === mine) setIsLoading(false);
+    }
+  }, deps);
+  useEffect(() => {
+    if (status !== "authenticated") {
+      gen.current++;
+      setData(empty);
+      setError(null);
+      setIsLoading(status === "loading");
+      return;
+    }
+    void refetch();
+  }, [status, emailVerified, refetch]);
+  return { data, isLoading, error, refetch };
+}
+function useCustomer() {
+  const { account } = useAuth();
+  const res = useResource(null, () => account.getProfile(), [account]);
+  const update = useCallback(async (patch) => {
+    await account.updateProfile(patch);
+    await res.refetch();
+  }, [account, res]);
+  return { ...res, update };
+}
+function useAddresses() {
+  const { account } = useAuth();
+  const res = useResource([], () => account.listAddresses(), [account]);
+  const after = async (p) => {
+    await p;
+    await res.refetch();
+  };
+  return {
+    ...res,
+    create: (input) => after(account.createAddress(input)),
+    update: (id, patch) => after(account.updateAddress(id, patch)),
+    remove: (id) => after(account.deleteAddress(id))
+  };
+}
+function useSavedCards() {
+  const { account } = useAuth();
+  const res = useResource([], () => account.listPaymentMethods(), [account]);
+  const after = async (p) => {
+    await p;
+    await res.refetch();
+  };
+  return {
+    ...res,
+    setDefault: (id) => after(account.setDefaultPaymentMethod(id)),
+    remove: (id) => after(account.deletePaymentMethod(id))
+  };
+}
+function useOrders(page) {
+  const { account } = useAuth();
+  return useResource([], () => account.listOrders(page), [account, page?.cursor, page?.limit]);
+}
+function useInvoices(page) {
+  const { account } = useAuth();
+  return useResource([], () => account.listInvoices(page), [account, page?.cursor, page?.limit]);
+}
+function useSubscriptions(page) {
+  const { account } = useAuth();
+  const res = useResource(
+    [],
+    () => account.listSubscriptions(page),
+    [account, page?.cursor, page?.limit]
+  );
+  const after = async (p) => {
+    await p;
+    await res.refetch();
+  };
+  return {
+    ...res,
+    cancel: (id, opts) => after(account.cancelSubscription(id, opts)),
+    pause: (id) => after(account.pauseSubscription(id)),
+    resume: (id) => after(account.resumeSubscription(id))
+  };
+}
+function useOrder(id) {
+  const { account } = useAuth();
+  return useResource(null, async () => id ? account.getOrder(id) : null, [account, id]);
+}
+function useInvoice(id) {
+  const { account } = useAuth();
+  return useResource(null, async () => id ? account.getInvoice(id) : null, [account, id]);
+}
+
+export {
+  useCustomer,
+  useAddresses,
+  useSavedCards,
+  useOrders,
+  useInvoices,
+  useSubscriptions,
+  useOrder,
+  useInvoice
+};
+//# sourceMappingURL=chunk-HGBAIM6B.js.map

package/dist/chunk-HGBAIM6B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/hooks.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from 'react';\nimport { ThrottleAuthError } from '../errors';\nimport type { Address, AddressInput, Customer, Invoice, Order, OrderDetail, PaymentMethod, ProfilePatch, Subscription } from '../types';\nimport type { Page } from '../account';\nimport { useAuth } from './context';\n\nexport interface Resource<T> {\n  data: T;\n  isLoading: boolean;\n  error: ThrottleAuthError | null;\n  refetch(): Promise<void>;\n}\n\nfunction asError(err: unknown): ThrottleAuthError {\n  if (err instanceof ThrottleAuthError) return err;\n  const anyErr = err as any;\n  return new ThrottleAuthError({\n    code: anyErr?.code ?? 'request_failed',\n    message: anyErr?.message ?? String(err),\n    statusCode: anyErr?.statusCode ?? 0,\n  });\n}\n\n/**\n * One fetch-on-auth-change primitive behind every resource hook. `emailVerified`\n * is a dependency on purpose: verifying lifts the claim cutoff, and lists that\n * were legitimately empty a moment ago are not empty any more.\n */\nfunction useResource<T>(empty: T, load: () => Promise<T>, deps: unknown[]): Resource<T> {\n  const { status, emailVerified } = useAuth();\n  const [data, setData] = useState<T>(empty);\n  const [isLoading, setIsLoading] = useState(status === 'loading');\n  const [error, setError] = useState<ThrottleAuthError | null>(null);\n  const gen = useRef(0);\n  const alive = useRef(true);\n\n  useEffect(() => {\n    // Set on mount, not only cleared on unmount: React StrictMode mounts,\n    // unmounts and remounts in development, and a ref that is only ever set\n    // to false would silently discard every response for the rest of the\n    // component's life.\n    alive.current = true;\n    return () => { alive.current = false; gen.current++; };\n  }, []);\n\n  const refetch = useCallback(async () => {\n    const mine = ++gen.current;\n    setIsLoading(true);\n    try {\n      const next = await load();\n      if (!alive.current || gen.current !== mine) return;\n      setData(next);\n      setError(null);\n    } catch (err) {\n      if (!alive.current || gen.current !== mine) return;\n      setError(asError(err));\n    } finally {\n      if (alive.current && gen.current === mine) setIsLoading(false);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, deps);\n\n  useEffect(() => {\n    if (status !== 'authenticated') {\n      gen.current++;               // abandon anything in flight\n      setData(empty);\n      setError(null);\n      setIsLoading(status === 'loading');\n      return;\n    }\n    void refetch();\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [status, emailVerified, refetch]);\n\n  return { data, isLoading, error, refetch };\n}\n\nexport function useCustomer(): Resource<Customer | null> & { update(patch: ProfilePatch): Promise<void> } {\n  const { account } = useAuth();\n  const res = useResource<Customer | null>(null, () => account.getProfile(), [account]);\n  const update = useCallback(async (patch: ProfilePatch) => {\n    await account.updateProfile(patch);\n    await res.refetch();\n  }, [account, res]);\n  return { ...res, update };\n}\n\nexport function useAddresses(): Resource<Address[]> & {\n  create(input: AddressInput): Promise<void>;\n  update(id: string, patch: Partial<AddressInput>): Promise<void>;\n  remove(id: string): Promise<void>;\n} {\n  const { account } = useAuth();\n  const res = useResource<Address[]>([], () => account.listAddresses(), [account]);\n  const after = async (p: Promise<unknown>) => { await p; await res.refetch(); };\n  return {\n    ...res,\n    create: (input) => after(account.createAddress(input)),\n    update: (id, patch) => after(account.updateAddress(id, patch)),\n    remove: (id) => after(account.deleteAddress(id)),\n  };\n}\n\nexport function useSavedCards(): Resource<PaymentMethod[]> & {\n  setDefault(id: string): Promise<void>;\n  remove(id: string): Promise<void>;\n} {\n  const { account } = useAuth();\n  const res = useResource<PaymentMethod[]>([], () => account.listPaymentMethods(), [account]);\n  const after = async (p: Promise<unknown>) => { await p; await res.refetch(); };\n  return {\n    ...res,\n    setDefault: (id) => after(account.setDefaultPaymentMethod(id)),\n    remove: (id) => after(account.deletePaymentMethod(id)),\n  };\n}\n\nexport function useOrders(page?: Page): Resource<Order[]> {\n  const { account } = useAuth();\n  return useResource<Order[]>([], () => account.listOrders(page), [account, page?.cursor, page?.limit]);\n}\n\nexport function useInvoices(page?: Page): Resource<Invoice[]> {\n  const { account } = useAuth();\n  return useResource<Invoice[]>([], () => account.listInvoices(page), [account, page?.cursor, page?.limit]);\n}\n\nexport function useSubscriptions(page?: Page): Resource<Subscription[]> & {\n  cancel(id: string, opts?: { atPeriodEnd?: boolean }): Promise<void>;\n  pause(id: string): Promise<void>;\n  resume(id: string): Promise<void>;\n} {\n  const { account } = useAuth();\n  const res = useResource<Subscription[]>([], () => account.listSubscriptions(page),\n    [account, page?.cursor, page?.limit]);\n  const after = async (p: Promise<unknown>) => { await p; await res.refetch(); };\n  return {\n    ...res,\n    cancel: (id, opts) => after(account.cancelSubscription(id, opts)),\n    pause: (id) => after(account.pauseSubscription(id)),\n    resume: (id) => after(account.resumeSubscription(id)),\n  };\n}\n\n/**\n * Single-resource reads for the detail views. A `null` id means \"nothing\n * selected\" and must not call the API — `useResource` still runs, so the\n * loader resolves to null rather than being skipped, which keeps the\n * loading/error shape identical whether or not an id is present.\n */\nexport function useOrder(id: string | null): Resource<OrderDetail | null> {\n  const { account } = useAuth();\n  return useResource<OrderDetail | null>(null, async () => (id ? account.getOrder(id) : null), [account, id]);\n}\n\nexport function useInvoice(id: string | null): Resource<Invoice | null> {\n  const { account } = useAuth();\n  return useResource<Invoice | null>(null, async () => (id ? account.getInvoice(id) : null), [account, id]);\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-SOPTBXF3.js → chunk-SZ427BQ3.js}

@@ -1,3 +1,5 @@
+"use client";
+
 // src/errors.ts
 var ThrottleAuthError = class extends Error {
   code;
@@ -184,7 +186,8 @@ function createThrottleAuth(config) {
         const data = await request({ ...base, method: "POST", path: "/auth/refresh", body: { refreshToken } });
         await persist(data);
       } catch (err) {
-        await forget();
+        const refused = err instanceof ThrottleAuthError && (err.statusCode === 401 || err.statusCode === 403);
+        if (refused) await forget();
         throw err;
       }
     });
@@ -365,6 +368,7 @@ function createAccount(auth) {
     getOrder: (id) => call("GET", `/me/orders/${seg(id)}`),
     listInvoices: (page) => call("GET", `/me/invoices${query(page)}`),
     getInvoice: (id) => call("GET", `/me/invoices/${seg(id)}`),
+    getInvoicePdfUrl: (id) => call("GET", `/me/invoices/${seg(id)}/pdf`),
     listSubscriptions: (page) => call("GET", `/me/subscriptions${query(page)}`),
     getSubscription: (id) => call("GET", `/me/subscriptions/${seg(id)}`),
     cancelSubscription: (id, opts) => call("POST", `/me/subscriptions/${seg(id)}/cancel`, opts),
@@ -374,11 +378,52 @@ function createAccount(auth) {
   };
 }
 
+// src/react/context.tsx
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+var Ctx = createContext(null);
+function ThrottleAuthProvider(props) {
+  const { auth: injected, publishableKey, baseUrl, storage, onStepUpRequired, children } = props;
+  const value = useMemo(() => {
+    const auth = injected ?? createThrottleAuth({ publishableKey, baseUrl, storage, onStepUpRequired });
+    return { auth, account: createAccount(auth) };
+  }, [injected, publishableKey, baseUrl]);
+  const restored = useRef(null);
+  useEffect(() => {
+    if (restored.current === value.auth) return;
+    restored.current = value.auth;
+    void value.auth.restore();
+  }, [value]);
+  return /* @__PURE__ */ jsx(Ctx.Provider, { value, children });
+}
+function useCtx() {
+  const ctx = useContext(Ctx);
+  if (!ctx) throw new Error("useAuth must be used inside a <ThrottleAuthProvider>");
+  return ctx;
+}
+function useAuthContext() {
+  return useCtx();
+}
+function useAuth() {
+  const { auth, account } = useCtx();
+  const snapshot = useSyncExternalStore(auth.subscribe, auth.getSnapshot, auth.getSnapshot);
+  return {
+    ...snapshot,
+    isLoading: snapshot.status === "loading",
+    isAuthenticated: snapshot.status === "authenticated",
+    auth,
+    account
+  };
+}
+
 export {
   ThrottleAuthError,
   memoryStorage,
   localStorageAdapter,
   createThrottleAuth,
-  createAccount
+  createAccount,
+  ThrottleAuthProvider,
+  useAuthContext,
+  useAuth
 };
-//# sourceMappingURL=chunk-SOPTBXF3.js.map
+//# sourceMappingURL=chunk-SZ427BQ3.js.map