@aifeatures/react 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -42,6 +42,22 @@ interface PublicOptionValue {
42
42
  * `selectedImages()`, which applies that rule for you).
43
43
  */
44
44
  images: string[];
45
+ /**
46
+ * Colour chip for this value: a hex colour ("#6B7A4F") or an image URL for
47
+ * a pattern/finish. null when the merchant hasn't set one — `VariantPicker`
48
+ * then renders the value's text label instead, so a half-swatched option
49
+ * shows which values still need one.
50
+ *
51
+ * Deliberately unrelated to `images` above: those are product photography
52
+ * shown when the value is SELECTED, and are never used as a chip.
53
+ *
54
+ * OPTIONAL on the type, though the API always sends it. This interface is
55
+ * exported, and `VariantPicker` takes `options` directly — so consumers
56
+ * hand-author these literals, and a required key would fail their build on
57
+ * what ships as a patch release. Readers must treat missing and null alike
58
+ * (`v.swatch ?? null`).
59
+ */
60
+ swatch?: string | null;
45
61
  }
46
62
  /** A product option axis (e.g. "Size", "Color") the buyer chooses from. */
47
63
  interface PublicOption {
@@ -81,6 +97,43 @@ interface PublicVariant {
81
97
  /** Units remaining when tracked; null when unlimited (untracked/backorder). */
82
98
  available: number | null;
83
99
  }
100
+ /**
101
+ * One subscription selling plan (subscriptions Unit 2/8). Amounts are NEVER
102
+ * localized: plans bill in the store's BASE currency, so `unit_amount` is
103
+ * base-currency minor units and `percent_off_bps` applies to the
104
+ * base-currency variant price — on a localized product response, label plan
105
+ * prices with `base_currency`, never with the converted `currency`.
106
+ */
107
+ interface PublicSubscriptionPlan {
108
+ id: string;
109
+ /** 'week' | 'month' | 'year' (stored verbatim — render unknowns as-is). */
110
+ interval: string;
111
+ interval_count: number;
112
+ /** Merchant display name ("Subscribe & save 15%"); null = derive a label. */
113
+ title: string | null;
114
+ /** Display order (the server already sorts by it). */
115
+ position: number;
116
+ /** Basis points off the one-time price (1500 = 15%); null for absolute plans. */
117
+ percent_off_bps: number | null;
118
+ /** Absolute recurring price in BASE-currency minor units; null for percent plans. */
119
+ unit_amount: number | null;
120
+ }
121
+ /**
122
+ * The product's subscription offer block. Null when there is nothing to
123
+ * render (no active plans and not subscription-only).
124
+ */
125
+ interface PublicProductSubscription {
126
+ /** Subscription-only product — no one-time purchase option. */
127
+ required: boolean;
128
+ /**
129
+ * Whether subscription checkout can be offered RIGHT NOW (payments active
130
+ * AND the published site serves /account). false → hide the plans (or, for
131
+ * a required product, render the "currently unavailable" default) — never
132
+ * explain why to a visitor.
133
+ */
134
+ ready: boolean;
135
+ plans: PublicSubscriptionPlan[];
136
+ }
84
137
  /**
85
138
  * Public (buyer-facing) product config, exactly as returned by
86
139
  * `GET {apiUrl}/v1/p/{productId}`. Field names stay snake_case to match the wire
@@ -171,6 +224,12 @@ interface PublicProduct {
171
224
  options: PublicOption[];
172
225
  /** Active, purchasable variants. Always at least one (the default variant). */
173
226
  variants: PublicVariant[];
227
+ /**
228
+ * Subscription selling plans (additive, subscriptions Unit 2). Null/absent
229
+ * when the product offers none — optional so older API deployments that
230
+ * omit the field still typecheck.
231
+ */
232
+ subscription?: PublicProductSubscription | null;
174
233
  }
175
234
  interface UseProductOptions {
176
235
  /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
@@ -378,6 +437,24 @@ interface StartCheckoutOptions {
378
437
  cancelUrl?: string;
379
438
  /** Prefills the email field on the Stripe Checkout page. */
380
439
  customerEmail?: string;
440
+ /**
441
+ * Subscription selling plan to buy (subscriptions Unit 8). Present =
442
+ * subscription-mode checkout: quantity is locked at 1 (any `quantity`
443
+ * passed is ignored), the buyer's market country is not sent (plans bill
444
+ * in the store's base currency, never localized), and no price
445
+ * expectation rides (the recurring amount is plan-derived server-side).
446
+ *
447
+ * When a session token is stored (the buyer signed in on this site), the
448
+ * purchase goes through POST /v1/account/subscribe with the bearer so a
449
+ * proven Stripe Customer can be reused. On a DEFINITIVE 401/404 from that
450
+ * twin (stale token, re-darkened /v1/account prefix) the stored token is
451
+ * cleared and the SAME purchase silently retries anonymously via /v1/p —
452
+ * one retry, no visible error (plan §Stripe Customer handling).
453
+ * Timeouts/network errors/5xx render the standard error state instead,
454
+ * token untouched, NO automatic retry: the original request may have
455
+ * succeeded, and a blind retry would double-mint sessions.
456
+ */
457
+ planId?: string;
381
458
  /**
382
459
  * The EXACT unit price the page displayed (minor units) — pass it so a
383
460
  * price the merchant edited between render and click makes the server
@@ -781,7 +858,11 @@ interface ShippingOptionConflict {
781
858
  }
782
859
  interface CartConflictItem {
783
860
  variant_id: string;
784
- code: 'unavailable' | 'insufficient_stock' | 'price_changed' | 'quantity_exceeds_max';
861
+ code: 'unavailable' | 'insufficient_stock' | 'price_changed' | 'quantity_exceeds_max'
862
+ /** The merchant made this product subscription-only after the cart was
863
+ * built. There is no quantity or price to fix — the line has to go, and
864
+ * the product is bought from its own page via PlanPicker instead. */
865
+ | 'subscription_only';
785
866
  /** insufficient_stock only: units currently available. */
786
867
  available?: number;
787
868
  /** price_changed only: the per-unit price checkout would charge NOW. */
@@ -949,6 +1030,8 @@ interface VariantPickerProps {
949
1030
  valueClassName?: string;
950
1031
  /** Class added to the currently selected value button. */
951
1032
  selectedValueClassName?: string;
1033
+ /** Class for the swatch chip rendered in place of a swatched value's label. */
1034
+ swatchClassName?: string;
952
1035
  /**
953
1036
  * Class added to values with no variant under the current other selections.
954
1037
  * Most of these stay clickable (clicking re-anchors the selection around
@@ -976,7 +1059,7 @@ interface VariantPickerProps {
976
1059
  * Unstyled-first: pass the *ClassName props (or target the data-selected /
977
1060
  * data-available attributes) to match the site's design.
978
1061
  */
979
- declare function VariantPicker({ options, variants, value, syncUrl, onChange, onVariantChange, className, style, optionClassName, optionLabelClassName, valueClassName, selectedValueClassName, unavailableValueClassName, }: VariantPickerProps): react_jsx_runtime.JSX.Element | null;
1062
+ declare function VariantPicker({ options, variants, value, syncUrl, onChange, onVariantChange, className, style, optionClassName, optionLabelClassName, valueClassName, selectedValueClassName, unavailableValueClassName, swatchClassName, }: VariantPickerProps): react_jsx_runtime.JSX.Element | null;
980
1063
 
981
1064
  interface BuyButtonProps {
982
1065
  /** Product ID from aifeatures */
@@ -989,6 +1072,15 @@ interface BuyButtonProps {
989
1072
  variantId?: string;
990
1073
  /** Defaults to 1. Must be within [1, max_quantity]. */
991
1074
  quantity?: number;
1075
+ /**
1076
+ * Subscription selling plan to buy (get it from `<PlanPicker onChange>`;
1077
+ * null/undefined = one-time purchase). A selected plan locks quantity at 1,
1078
+ * switches the default label to "Subscribe", and sends `plan_id` with the
1079
+ * checkout — through POST /v1/account/subscribe when the buyer has a
1080
+ * stored session, with the silent anonymous fallback on a definitive
1081
+ * 401/404 (see useCheckout's planId doc).
1082
+ */
1083
+ planId?: string | null;
992
1084
  /** Total amount in minor units — custom-amount (tip jar) products only. */
993
1085
  amount?: number;
994
1086
  /** Opaque passthrough stored on the order (string values only). */
@@ -1028,7 +1120,7 @@ interface BuyButtonProps {
1028
1120
  *
1029
1121
  * Unstyled by default — pass className/style to match the site's design.
1030
1122
  */
1031
- declare function BuyButton({ productId, variantId, quantity, amount, metadata, successUrl, cancelUrl, customerEmail, apiUrl, disabled, className, style, errorClassName, spinner, children, }: BuyButtonProps): react_jsx_runtime.JSX.Element;
1123
+ declare function BuyButton({ productId, variantId, quantity, planId, amount, metadata, successUrl, cancelUrl, customerEmail, apiUrl, disabled, className, style, errorClassName, spinner, children, }: BuyButtonProps): react_jsx_runtime.JSX.Element;
1032
1124
 
1033
1125
  interface AddToCartButtonProps {
1034
1126
  /** Product ID from aifeatures */
@@ -1182,6 +1274,19 @@ interface OrderSessionLineItem {
1182
1274
  */
1183
1275
  refund_reason?: "oversold" | "merchant";
1184
1276
  }
1277
+ /**
1278
+ * Renewal terms of a subscription signup order (subscriptions Unit 3/8) —
1279
+ * locked at checkout from the order's own plan snapshot, never from live
1280
+ * plan rows.
1281
+ */
1282
+ interface OrderSessionSubscription {
1283
+ /** 'week' | 'month' | 'year' (stored verbatim). */
1284
+ interval: string;
1285
+ interval_count: number;
1286
+ /** The recurring charge in minor units of `currency` — what renews. */
1287
+ amount: number;
1288
+ currency: string;
1289
+ }
1185
1290
  /**
1186
1291
  * Response shape of `GET {apiUrl}/v1/o/session/{sessionId}` (snake_case wire
1187
1292
  * format). Deliberately carries NO buyer PII (no email/name) — the session id
@@ -1213,6 +1318,13 @@ interface OrderSession {
1213
1318
  currency?: string;
1214
1319
  /** What was bought — a receipt-style summary. */
1215
1320
  line_items?: OrderSessionLineItem[];
1321
+ /**
1322
+ * Present ONLY on subscription signup orders (append-only wire additions —
1323
+ * one-time payloads stay byte-identical): 'subscription' marks the order
1324
+ * as a signup, and `subscription` carries its renewal terms.
1325
+ */
1326
+ source?: "checkout" | "subscription";
1327
+ subscription?: OrderSessionSubscription;
1216
1328
  }
1217
1329
  interface OrderConfirmationProps {
1218
1330
  /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
@@ -1254,4 +1366,531 @@ interface OrderConfirmationProps {
1254
1366
  }
1255
1367
  declare function OrderConfirmation({ apiUrl, className, style, sessionId: sessionIdProp, pollIntervalMs, pollTimeoutMs, followRedirect, redirectDelayMs, renderNoSession, renderPending, renderPaid, renderFailed, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element | null;
1256
1368
 
1257
- export { type AddCartLineInput, AddToCartButton, type AddToCartButtonProps, type AddToCartResult, AifeaturesCaptcha, type AifeaturesCaptchaProps, BuyButton, type BuyButtonProps, CartCheckoutButton, type CartCheckoutButtonProps, type CartCheckoutLine, type CartConflictItem, type CartItemLine, type CartLine, type CartLineDisplay, type CartLineStatus, type CartSummary, type CartSummaryShipping, type CartSummaryShippingOption, MARKET_COUNTRIES, MAX_CART_LINES, type MarketCountry, OrderConfirmation, type OrderConfirmationProps, type OrderFulfillment, type OrderSession, type OrderSessionLineItem, type OrderStatus, ProductPrice, type ProductPriceProps, type PublicOption, type PublicOptionValue, type PublicProduct, type PublicVariant, type PublicVariantOptionValue, type ShippingOptionConflict, type StartCartCheckoutOptions, type StartCheckoutOptions, type UseCartCheckoutOptions, type UseCartCheckoutResult, type UseCartItemsOptions, type UseCartItemsResult, type UseCartResult, type UseCartSummaryOptions, type UseCartSummaryResult, type UseCheckoutOptions, type UseCheckoutResult, type UseMarketOptions, type UseMarketResult, type UseProductOptions, type UseProductResult, VariantPicker, type VariantPickerProps, type VariantSelection, ZERO_DECIMAL_CURRENCIES, applySelectionToUrl, formatPrice, getOptions, getVariants, isMultiVariant, isValueAvailable, isValueInCatalog, reanchorSelection, resolveVariant, searchFromSelection, selectedImages, selectedValues, selectionFromSearch, useCart, useCartCheckout, useCartItems, useCartSummary, useCheckout, useMarket, useProduct, valueSlug, variantPriceRange };
1369
+ /**
1370
+ * The recurring price a plan derives from a base one-time price, in minor
1371
+ * units.
1372
+ *
1373
+ * MIRROR: packages/api/src/lib/subscriptionPlans.ts `planRecurringAmount` is
1374
+ * the SOURCE OF TRUTH — keep this byte-equivalent. The rounding is
1375
+ * deliberate and must match exactly: percent discounts round the DISCOUNT
1376
+ * down (Math.floor), i.e. the recurring price UP — the merchant advertised
1377
+ * "up to N% off", and a price displayed here that rounds the other way would
1378
+ * differ from what checkout actually charges every cycle.
1379
+ */
1380
+ declare function planRecurringAmount(baseUnitAmount: number, plan: Pick<PublicSubscriptionPlan, 'percent_off_bps' | 'unit_amount'>): number;
1381
+ interface PlanPickerOptionContext {
1382
+ /** The plan this option represents — null for the one-time option. */
1383
+ plan: PublicSubscriptionPlan | null;
1384
+ selected: boolean;
1385
+ /**
1386
+ * Recurring price in BASE-currency minor units (one-time option: the base
1387
+ * price itself). Null when it cannot be derived — a percent plan with no
1388
+ * usable base price, e.g. a localized product response (plan prices are
1389
+ * never fx-localized) or a custom-amount product.
1390
+ */
1391
+ price: number | null;
1392
+ /** `price` formatted with the BASE currency ("$25.50"), or null. */
1393
+ priceLabel: string | null;
1394
+ /** Default display label ("Subscribe & save 15% — $21.25 every month"). */
1395
+ label: string;
1396
+ /** Select this option. */
1397
+ select: () => void;
1398
+ }
1399
+ interface PlanPickerProps {
1400
+ /**
1401
+ * The product from `useProduct` — the picker reads `product.subscription`,
1402
+ * plus the base price/currency for percent-plan math. Alternatively pass
1403
+ * `subscription` (and `baseUnitAmount`/`currency`) directly.
1404
+ */
1405
+ product?: PublicProduct | null;
1406
+ /** The subscription payload, when not passing `product`. */
1407
+ subscription?: PublicProductSubscription | null;
1408
+ /**
1409
+ * Base one-time price (BASE-currency minor units) percent plans discount.
1410
+ * Pass the SELECTED variant's price on multi-variant products so the
1411
+ * displayed plan price tracks the variant. Defaults to the product's
1412
+ * top-level `unit_amount` — but only on a NON-localized response: plan
1413
+ * prices are never fx-localized (they bill in the store's base currency),
1414
+ * so on a localized response percent plans render without a computed
1415
+ * price unless you supply the base-currency amount here.
1416
+ */
1417
+ baseUnitAmount?: number | null;
1418
+ /** Currency for plan price labels (defaults to the product's BASE currency). */
1419
+ currency?: string;
1420
+ /**
1421
+ * Controlled selection: a plan id, or null for one-time. Omit for
1422
+ * uncontrolled (defaults to one-time — or the first plan by position when
1423
+ * the product is subscription-only).
1424
+ */
1425
+ value?: string | null;
1426
+ /** Fires with the chosen plan id (null = one-time) — including the
1427
+ * automatic subscription-required default on mount. */
1428
+ onChange?: (planId: string | null) => void;
1429
+ className?: string;
1430
+ style?: CSSProperties;
1431
+ /** Class for every option row. */
1432
+ optionClassName?: string;
1433
+ /** Class added to the selected option row. */
1434
+ selectedOptionClassName?: string;
1435
+ /** Label for the one-time option (default "One-time purchase"). */
1436
+ oneTimeLabel?: ReactNode;
1437
+ /** Replace an option row entirely (both plan and one-time rows). */
1438
+ renderOption?: (ctx: PlanPickerOptionContext) => ReactNode;
1439
+ /**
1440
+ * Rendered when the product is subscription-only but subscriptions can't
1441
+ * be offered right now (`required && !ready`). The default is a
1442
+ * plain-statement "currently unavailable" — deliberately reason-free
1443
+ * (merchant configuration state never surfaces to visitors); overrides
1444
+ * should restyle it, not explain it.
1445
+ */
1446
+ renderUnavailable?: () => ReactNode;
1447
+ }
1448
+ /**
1449
+ * Headless single-select for subscription selling plans (subscriptions R2).
1450
+ * Renders the one-time option plus one row per plan — or plans only when the
1451
+ * product is subscription-required. Feed the selection to `<BuyButton
1452
+ * planId>` (a selected plan locks quantity at 1 and switches the CTA to
1453
+ * "Subscribe").
1454
+ *
1455
+ * Degraded states (plan §Unit 8, default copy is deliberate):
1456
+ * - no subscription block → renders nothing (one-time only);
1457
+ * - `ready: false`, not required → renders nothing — plans are silently
1458
+ * hidden, the one-time path is untouched, no error surface;
1459
+ * - `ready: false`, required → the "currently unavailable" default
1460
+ * (renderUnavailable), with no purchase controls and no reason given.
1461
+ */
1462
+ declare function PlanPicker({ product, subscription: subscriptionProp, baseUnitAmount, currency, value, onChange, className, style, optionClassName, selectedOptionClassName, oneTimeLabel, renderOption, renderUnavailable, }: PlanPickerProps): react_jsx_runtime.JSX.Element | null;
1463
+
1464
+ interface StoredSessionCustomer {
1465
+ email: string;
1466
+ name: string | null;
1467
+ }
1468
+
1469
+ type SessionStatus = 'signed_out' | 'pending' | 'signed_in' | 'unavailable';
1470
+ type SessionCustomer = StoredSessionCustomer;
1471
+ /** Why the hook is signed_out, when it wasn't a plain fresh visit. */
1472
+ type SessionReason = 'session_expired' | 'invalid_code' | null;
1473
+ interface UseSessionOptions {
1474
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1475
+ apiUrl?: string;
1476
+ /**
1477
+ * Whether THIS instance consumes a `?code=` magic-link param from the URL
1478
+ * on mount (default true). Exactly ONE mounted instance must own the
1479
+ * consumption — the code is single-use server-side, so a second instance
1480
+ * exchanging it burns it and strands the reason on the wrong hook.
1481
+ * AccountLogin sets this false when a parent session is passed in
1482
+ * (AccountPage owns the URL there). Read once on mount.
1483
+ */
1484
+ consumeUrlCode?: boolean;
1485
+ }
1486
+ type LoginResult =
1487
+ /** `via: 'preview'` — the editor host claimed the handshake and minted a
1488
+ * preview session (already signed in, no email was sent). */
1489
+ {
1490
+ ok: true;
1491
+ via: 'email' | 'preview';
1492
+ } | {
1493
+ ok: false;
1494
+ code: 'rate_limited' | 'unavailable' | 'error';
1495
+ error: string;
1496
+ };
1497
+ type VerifyResult = {
1498
+ ok: true;
1499
+ } | {
1500
+ ok: false;
1501
+ code: 'invalid_code' | 'rate_limited' | 'unavailable' | 'error';
1502
+ error: string;
1503
+ };
1504
+ interface UseSessionResult {
1505
+ status: SessionStatus;
1506
+ /** Display echo (email/name) — null until signed in. */
1507
+ customer: SessionCustomer | null;
1508
+ /** The session bearer — null unless signed in. */
1509
+ token: string | null;
1510
+ /** Why signed_out, when there is a why (expired session, bad code). */
1511
+ reason: SessionReason;
1512
+ /**
1513
+ * Request a magic link for `email` (uniform 200 — "sent" even for unknown
1514
+ * addresses, by server design). Inside the editor iframe this offers the
1515
+ * preview-session handshake to the host first and only falls back to the
1516
+ * real POST when nothing claims it.
1517
+ */
1518
+ login: (email: string) => Promise<LoginResult>;
1519
+ /** POST-exchange a login code (single-use) for a session. */
1520
+ verifyCode: (code: string) => Promise<VerifyResult>;
1521
+ /** Delete the server session (best-effort) and clear the stored token. */
1522
+ logout: () => Promise<void>;
1523
+ /**
1524
+ * Re-validate the stored session against GET /v1/account/me: a live session
1525
+ * refreshes the customer echo; 401 clears it (signed_out, reason
1526
+ * 'session_expired'); a whole-prefix 404 flips to 'unavailable'. Network
1527
+ * errors leave the state untouched.
1528
+ */
1529
+ refresh: () => Promise<void>;
1530
+ }
1531
+ /**
1532
+ * Customer-account session state (subscriptions Unit 8). The token lives in
1533
+ * origin-scoped storage (`aifeatures_session`, sessionStorage.ts) so every
1534
+ * mounted instance — account page, buy box — shares one signed-in answer,
1535
+ * cross-tab included.
1536
+ *
1537
+ * On mount it consumes a `?code=` magic-link param from the URL: stripped via
1538
+ * history.replaceState BEFORE the exchange (OrderConfirmation's precedent —
1539
+ * the code must not linger in history/analytics/Referer), then POSTed to
1540
+ * /v1/account/verify (POST-to-consume defeats scanner prefetch; the code is
1541
+ * single-use server-side).
1542
+ *
1543
+ * Degradations (plan §Magic-link flow): a whole-prefix 404 (dark-launched or
1544
+ * re-darkened /v1/account) maps to status 'unavailable' — components render
1545
+ * "sign-in temporarily unavailable", never a dead error.
1546
+ */
1547
+ declare function useSession(options?: UseSessionOptions): UseSessionResult;
1548
+
1549
+ interface AccountLoginFormContext {
1550
+ email: string;
1551
+ setEmail: (email: string) => void;
1552
+ submit: () => void;
1553
+ submitting: boolean;
1554
+ /** 'rate_limited' (429 from /login) or 'error' (network/unexpected). */
1555
+ errorKind: 'rate_limited' | 'error' | null;
1556
+ errorMessage: string | null;
1557
+ /** Why the visitor is signed out, when there is a why. */
1558
+ reason: SessionReason;
1559
+ }
1560
+ interface AccountLoginSentContext {
1561
+ email: string;
1562
+ /** True once the resend affordance should show (~30s after the send). */
1563
+ canResend: boolean;
1564
+ /** Re-request the link (generic copy either way — cooldowns are invisible
1565
+ * uniform 200s server-side). */
1566
+ resend: () => void;
1567
+ submitting: boolean;
1568
+ /** Go back to the email form. */
1569
+ reset: () => void;
1570
+ }
1571
+ interface AccountLoginProps {
1572
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1573
+ apiUrl?: string;
1574
+ /**
1575
+ * Share a parent's useSession() (AccountPage passes its own so the login
1576
+ * form and the page agree on status). Omit to run standalone.
1577
+ */
1578
+ session?: UseSessionResult;
1579
+ /** Delay before the resend affordance appears (default 30s). */
1580
+ resendDelayMs?: number;
1581
+ className?: string;
1582
+ style?: CSSProperties;
1583
+ /** Replace the email-entry state (also carries invalid-code / expired /
1584
+ * rate-limited context). */
1585
+ renderForm?: (ctx: AccountLoginFormContext) => ReactNode;
1586
+ /** Replace the check-your-email state. */
1587
+ renderSent?: (ctx: AccountLoginSentContext) => ReactNode;
1588
+ /** Replace the sign-in-temporarily-unavailable state (dark /v1/account
1589
+ * prefix). The default deliberately has NO resend CTA — none can work. */
1590
+ renderUnavailable?: () => ReactNode;
1591
+ }
1592
+ /**
1593
+ * Magic-link sign-in for the account page (subscriptions R6/R9). States, all
1594
+ * with working unstyled defaults and render-prop overrides:
1595
+ *
1596
+ * - email entry (with the session-expired / invalid-code notice above it —
1597
+ * an invalid or expired link's recovery IS this form: "email me a new
1598
+ * link");
1599
+ * - check-your-email, with a resend affordance after ~30s. The copy stays
1600
+ * generic on purpose: the server answers a uniform 200 whether or not it
1601
+ * sent (unknown emails, cooldowns), so this component can never promise
1602
+ * more than "if that address has orders here, a link is on its way";
1603
+ * - rate-limited (a real 429 from /login);
1604
+ * - sign-in temporarily unavailable (whole-prefix 404 — dark-launched or
1605
+ * re-darkened /v1/account): a plain statement with NO resend CTA, because
1606
+ * no resend can work.
1607
+ *
1608
+ * Inside the editor iframe, submit engages the preview-session handshake
1609
+ * (useSession.login) and signs straight in when the host claims it — the
1610
+ * check-your-email state is skipped.
1611
+ */
1612
+ declare function AccountLogin({ apiUrl, session: sessionProp, resendDelayMs, className, style, renderForm, renderSent, renderUnavailable, }: AccountLoginProps): react_jsx_runtime.JSX.Element;
1613
+
1614
+ interface AccountPagePmBannerContext {
1615
+ /** 'retrying' while a subscription is still past_due after the card
1616
+ * update; 'recovered' once nothing is. */
1617
+ state: 'retrying' | 'recovered';
1618
+ /** Manual re-check while the retry is pending. */
1619
+ checkAgain: () => void;
1620
+ checking: boolean;
1621
+ }
1622
+ interface AccountPageProps {
1623
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1624
+ apiUrl?: string;
1625
+ className?: string;
1626
+ style?: CSSProperties;
1627
+ /** Forwarded to the built-in AccountLogin (delay before resend shows). */
1628
+ resendDelayMs?: number;
1629
+ /** Override pieces of the built-in login (render props etc.). */
1630
+ loginProps?: Omit<AccountLoginProps, 'apiUrl' | 'session'>;
1631
+ /** Replace the whole-page loading state (code exchange, /me fetch). */
1632
+ renderLoading?: () => ReactNode;
1633
+ /** Replace the /me error state. */
1634
+ renderError?: (ctx: {
1635
+ error: string;
1636
+ retry: () => void;
1637
+ }) => ReactNode;
1638
+ /** Replace the signed-in-but-nothing-here state. */
1639
+ renderEmpty?: () => ReactNode;
1640
+ /** Replace the signed-in header (customer email + sign out). */
1641
+ renderHeader?: (ctx: {
1642
+ customer: {
1643
+ email: string;
1644
+ name: string | null;
1645
+ };
1646
+ site: {
1647
+ name: string;
1648
+ } | null;
1649
+ signOut: () => void;
1650
+ }) => ReactNode;
1651
+ /** Replace the `?pm=updated` portal-return banner. */
1652
+ renderPmBanner?: (ctx: AccountPagePmBannerContext) => ReactNode;
1653
+ /** Replace the manage-grant expired state (login recovery below it stays). */
1654
+ renderManageExpired?: () => ReactNode;
1655
+ }
1656
+ /**
1657
+ * The buyer account page for the site's `/account` route (subscriptions
1658
+ * R9/R14): magic-link sign-in, order history, subscription management —
1659
+ * or, arriving via `?manage_code=` (the manage-link resolver's handoff), a
1660
+ * single-subscription manage view that ignores any ambient session.
1661
+ *
1662
+ * URL consumption on mount, all stripped via history.replaceState before any
1663
+ * network use (OrderConfirmation's precedent):
1664
+ * - `?code=` → POST-exchanged for a session (useSession);
1665
+ * - `?manage_code=` → POST-exchanged for a manage grant. The grant token
1666
+ * lives in component memory ONLY — never storage, never
1667
+ * a URL (plan §Manage link);
1668
+ * - `?pm=updated` → the portal-return marker: re-fetch on mount and show
1669
+ * "card updated — retrying" (still past_due) vs
1670
+ * "recovered" (active), with a manual "check again".
1671
+ *
1672
+ * Degradations: a whole-prefix 404 anywhere maps back to the login state —
1673
+ * with the dedicated "sign-in temporarily unavailable" copy when the login
1674
+ * submit itself hits the dark prefix (AccountLogin); a 401 mid-browse clears
1675
+ * the stored token and returns to email entry with a brief message, keeping
1676
+ * the buyer on this page.
1677
+ */
1678
+ declare function AccountPage({ apiUrl, className, style, resendDelayMs, loginProps, renderLoading, renderError, renderEmpty, renderHeader, renderPmBanner, renderManageExpired, }: AccountPageProps): react_jsx_runtime.JSX.Element;
1679
+
1680
+ /**
1681
+ * INTERNAL module — shared wire types + fetch classification for the
1682
+ * /v1/account surface (subscriptions Unit 8). Not exported from the package
1683
+ * index except for the payload TYPES (re-exported by the barrel).
1684
+ *
1685
+ * The one non-obvious rule lives here: DARK-PREFIX DETECTION. The whole
1686
+ * /v1/account prefix ships behind a config flag and re-darkening is a live
1687
+ * incident-response move (plan §Magic-link flow), so every route can answer
1688
+ * an EMPTY-BODY 404 indistinguishable from a path that doesn't exist. Live
1689
+ * routes that legitimately 404 (e.g. "Subscription not found") always carry
1690
+ * a JSON `{error}` body — so `404 with a completely EMPTY body` is classified
1691
+ * `unavailable`, and components map it to the login / "temporarily
1692
+ * unavailable" states instead of a dead error. A 404 that carries ANYTHING
1693
+ * (that JSON error, or an interposed proxy/CDN's HTML page) is an ordinary
1694
+ * refusal: the session is not implicated and must not be cleared.
1695
+ */
1696
+ /** One order row from GET /v1/account/me (bounded receipt shelf). */
1697
+ interface AccountOrder {
1698
+ id: string;
1699
+ order_number: number | null;
1700
+ status: string;
1701
+ /** 'checkout' | 'cart' | 'subscription' — subscription = signup or renewal. */
1702
+ source: string;
1703
+ amount_total: number;
1704
+ shipping_total: number | null;
1705
+ tax_total: number | null;
1706
+ currency: string;
1707
+ created_at: string;
1708
+ line_items: Array<{
1709
+ name: string | null;
1710
+ quantity: number | null;
1711
+ unit_amount: number | null;
1712
+ }>;
1713
+ }
1714
+ /**
1715
+ * One subscription row, as serialized by the session surface
1716
+ * (`subscriberSubscriptionView`) — the manage-grant view
1717
+ * (`manageSubscriptionView`) is the same shape minus `product_id` /
1718
+ * `created_at` / `shipping_address`, plus `shipping_name` / `shipping_city`,
1719
+ * so the optional fields cover both doorways with one type.
1720
+ */
1721
+ interface AccountSubscription {
1722
+ id: string;
1723
+ /** Stripe status verbatim ('active', 'past_due', …) — render unmodeled
1724
+ * values generically, never throw on them. */
1725
+ status: string;
1726
+ product_id?: string;
1727
+ plan_title: string | null;
1728
+ plan_interval: string;
1729
+ plan_interval_count: number;
1730
+ /** Locked signup amount (minor units). */
1731
+ plan_amount: number;
1732
+ /** Current recurring amount mirrored from Stripe (falls back to plan_amount). */
1733
+ current_amount: number;
1734
+ currency: string;
1735
+ current_period_end: string | null;
1736
+ cancel_at_period_end: boolean;
1737
+ canceled_at: string | null;
1738
+ /** Terminal — no future invoice can arrive. "Ended — resubscribe" copy. */
1739
+ ended: boolean;
1740
+ is_test: boolean;
1741
+ created_at?: string;
1742
+ shipping_address?: {
1743
+ name?: string | null;
1744
+ address?: {
1745
+ line1?: string | null;
1746
+ line2?: string | null;
1747
+ city?: string | null;
1748
+ state?: string | null;
1749
+ postal_code?: string | null;
1750
+ country?: string | null;
1751
+ } | null;
1752
+ } | null;
1753
+ /** Manage-grant view only. */
1754
+ shipping_name?: string | null;
1755
+ shipping_city?: string | null;
1756
+ }
1757
+ /** Response of GET /v1/account/me. */
1758
+ interface AccountMePayload {
1759
+ customer: {
1760
+ email: string;
1761
+ name: string | null;
1762
+ };
1763
+ site: {
1764
+ name: string;
1765
+ };
1766
+ orders: AccountOrder[];
1767
+ subscriptions: AccountSubscription[];
1768
+ }
1769
+ /** The shipping_address input shape POST /subscriptions/:id/address accepts. */
1770
+ interface AccountShippingAddressInput {
1771
+ name?: string | null;
1772
+ address: {
1773
+ line1: string;
1774
+ line2?: string | null;
1775
+ city?: string | null;
1776
+ state?: string | null;
1777
+ postal_code?: string | null;
1778
+ country: string;
1779
+ };
1780
+ }
1781
+
1782
+ interface AccountOrdersProps {
1783
+ /** The `orders` array from GET /v1/account/me (newest first, bounded). */
1784
+ orders: AccountOrder[];
1785
+ className?: string;
1786
+ style?: CSSProperties;
1787
+ /** Section heading (default "Your orders"); null renders none. */
1788
+ heading?: ReactNode | null;
1789
+ /** Replace the no-orders state. */
1790
+ renderEmpty?: () => ReactNode;
1791
+ /** Replace one order row. */
1792
+ renderOrder?: (order: AccountOrder) => ReactNode;
1793
+ }
1794
+ /**
1795
+ * The signed-in buyer's order history (subscriptions R9) — a receipt shelf,
1796
+ * presentational only: hand it the `orders` from /v1/account/me. Unstyled
1797
+ * defaults; restyle via className or replace rows via renderOrder.
1798
+ */
1799
+ declare function AccountOrders({ orders, className, style, heading, renderEmpty, renderOrder, }: AccountOrdersProps): react_jsx_runtime.JSX.Element;
1800
+
1801
+ /**
1802
+ * Which doorway this list acts through:
1803
+ * - 'session': the signed-in account page — per-subscription
1804
+ * /v1/account/subscriptions/:id/* endpoints (cancel, reactivate, address,
1805
+ * FULL-config portal).
1806
+ * - 'manage': the emailed manage-grant — the /v1/account/manage/* endpoints,
1807
+ * scoped to exactly ONE subscription (cancel, MINIMAL-config card-update; no
1808
+ * address change, and NO REACTIVATE — the grant token lives in component
1809
+ * memory only, never in storage).
1810
+ *
1811
+ * WHY 'manage' CANNOT REACTIVATE. The grant descends from a token emailed with
1812
+ * a receipt, which proves only that someone once received an email — a shared
1813
+ * inbox, a forward, a mailbox compromised later. A magic-link sign-in proves
1814
+ * CURRENT control of the mailbox. Stopping money (cancel) and preserving money
1815
+ * (card update) are fine on the weaker proof; STARTING money is not, so the
1816
+ * server does not serve /v1/account/manage/reactivate at all. `paths()` nulls it
1817
+ * the same way it nulls `address`, and the row renders a sign-in pointer where
1818
+ * the button would be.
1819
+ */
1820
+ type SubscriptionListAuth = {
1821
+ kind: 'session';
1822
+ token: string;
1823
+ } | {
1824
+ kind: 'manage';
1825
+ token: string;
1826
+ };
1827
+ type MutationKind = 'cancel' | 'reactivate' | 'address' | 'portal';
1828
+ interface SubscriptionMutationState {
1829
+ kind: MutationKind;
1830
+ phase: 'pending' | 'error' | 'success';
1831
+ error?: string;
1832
+ }
1833
+ interface SubscriptionRowContext {
1834
+ subscription: AccountSubscription;
1835
+ /** Open panel: cancel confirmation or the address form. */
1836
+ panel: 'none' | 'confirm_cancel' | 'address';
1837
+ mutation: SubscriptionMutationState | null;
1838
+ /** True when the card-update button should not render (test rows, or the
1839
+ * server answered portal_unavailable). */
1840
+ portalHidden: boolean;
1841
+ openCancelConfirm: () => void;
1842
+ closePanel: () => void;
1843
+ confirmCancel: () => void;
1844
+ /** No-ops in the 'manage' doorway — restarting billing needs a session, so
1845
+ * `reactivateAvailable` is false there and a custom renderRow must render the
1846
+ * sign-in pointer instead of a button. */
1847
+ reactivate: () => void;
1848
+ /** False in the 'manage' doorway: the server serves no grant-scoped
1849
+ * reactivate. */
1850
+ reactivateAvailable: boolean;
1851
+ openAddressForm: () => void;
1852
+ saveAddress: (address: AccountShippingAddressInput) => void;
1853
+ openPortal: () => void;
1854
+ }
1855
+ interface SubscriptionListProps {
1856
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1857
+ apiUrl?: string;
1858
+ subscriptions: AccountSubscription[];
1859
+ auth: SubscriptionListAuth;
1860
+ /** The bearer was refused (session_expired / manage_expired) — the parent
1861
+ * should drop to its signed-out / grant-expired state. */
1862
+ onAuthError?: (failure: {
1863
+ code: string | null;
1864
+ error: string;
1865
+ }) => void;
1866
+ /** The whole /v1/account prefix answered dark 404s mid-browse. */
1867
+ onUnavailable?: () => void;
1868
+ /** A mutation returned a fresh row (also fired when a raced terminal
1869
+ * cancel comes back `ended`). */
1870
+ onSubscriptionChange?: (sub: AccountSubscription) => void;
1871
+ className?: string;
1872
+ style?: CSSProperties;
1873
+ /** Section heading (default "Your subscriptions"); null renders none. */
1874
+ heading?: ReactNode | null;
1875
+ /** Replace the no-subscriptions state. */
1876
+ renderEmpty?: () => ReactNode;
1877
+ /** Replace one subscription row (receives the full action context). */
1878
+ renderRow?: (ctx: SubscriptionRowContext) => ReactNode;
1879
+ }
1880
+ /**
1881
+ * The subscriber's subscription rows (subscriptions R9/R12): status per
1882
+ * state (active / past_due / scheduled-to-cancel with lapse date + reactivate
1883
+ * / ended with resubscribe copy), a cancel flow with an explicit confirm step
1884
+ * stating the lapse date, reactivate, shipping-address editing (session
1885
+ * doorway only), and the card-update portal handoff — hidden for test rows
1886
+ * and after a `portal_unavailable` refusal, since no working card-update
1887
+ * exists behind it.
1888
+ *
1889
+ * Mutation arcs are per-row pending / error-with-retry / success. A raced
1890
+ * terminal cancel (`ended` code) flips the row to its ended state rather
1891
+ * than erroring — the copy is "this subscription has ended", and the only
1892
+ * path onward is resubscribing on the product page.
1893
+ */
1894
+ declare function SubscriptionList({ apiUrl, subscriptions, auth, onAuthError, onUnavailable, onSubscriptionChange, className, style, heading, renderEmpty, renderRow, }: SubscriptionListProps): react_jsx_runtime.JSX.Element;
1895
+
1896
+ export { AccountLogin, type AccountLoginFormContext, type AccountLoginProps, type AccountLoginSentContext, type AccountMePayload, type AccountOrder, AccountOrders, type AccountOrdersProps, AccountPage, type AccountPagePmBannerContext, type AccountPageProps, type AccountShippingAddressInput, type AccountSubscription, type AddCartLineInput, AddToCartButton, type AddToCartButtonProps, type AddToCartResult, AifeaturesCaptcha, type AifeaturesCaptchaProps, BuyButton, type BuyButtonProps, CartCheckoutButton, type CartCheckoutButtonProps, type CartCheckoutLine, type CartConflictItem, type CartItemLine, type CartLine, type CartLineDisplay, type CartLineStatus, type CartSummary, type CartSummaryShipping, type CartSummaryShippingOption, type LoginResult, MARKET_COUNTRIES, MAX_CART_LINES, type MarketCountry, OrderConfirmation, type OrderConfirmationProps, type OrderFulfillment, type OrderSession, type OrderSessionLineItem, type OrderSessionSubscription, type OrderStatus, PlanPicker, type PlanPickerOptionContext, type PlanPickerProps, ProductPrice, type ProductPriceProps, type PublicOption, type PublicOptionValue, type PublicProduct, type PublicProductSubscription, type PublicSubscriptionPlan, type PublicVariant, type PublicVariantOptionValue, type SessionCustomer, type SessionReason, type SessionStatus, type ShippingOptionConflict, type StartCartCheckoutOptions, type StartCheckoutOptions, SubscriptionList, type SubscriptionListAuth, type SubscriptionListProps, type SubscriptionMutationState, type SubscriptionRowContext, type UseCartCheckoutOptions, type UseCartCheckoutResult, type UseCartItemsOptions, type UseCartItemsResult, type UseCartResult, type UseCartSummaryOptions, type UseCartSummaryResult, type UseCheckoutOptions, type UseCheckoutResult, type UseMarketOptions, type UseMarketResult, type UseProductOptions, type UseProductResult, type UseSessionOptions, type UseSessionResult, VariantPicker, type VariantPickerProps, type VariantSelection, type VerifyResult, ZERO_DECIMAL_CURRENCIES, applySelectionToUrl, formatPrice, getOptions, getVariants, isMultiVariant, isValueAvailable, isValueInCatalog, planRecurringAmount, reanchorSelection, resolveVariant, searchFromSelection, selectedImages, selectedValues, selectionFromSearch, useCart, useCartCheckout, useCartItems, useCartSummary, useCheckout, useMarket, useProduct, useSession, valueSlug, variantPriceRange };