@aifeatures/react 0.3.1 → 0.5.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
@@ -19,6 +19,14 @@ interface AifeaturesCaptchaProps {
19
19
  * Drop this into any form to add CAPTCHA protection. The Turnstile widget
20
20
  * automatically adds a hidden `cf-turnstile-response` input to the form.
21
21
  *
22
+ * The widget renders in `interaction-only` appearance: for the vast majority
23
+ * of visitors the managed challenge resolves silently and nothing is ever
24
+ * drawn, so the form reads as a plain form. The checkbox appears only for the
25
+ * visitors Cloudflare cannot clear on its own. That fallback is the reason we
26
+ * stay on the `managed` widget mode rather than Cloudflare's `invisible` mode
27
+ * — invisible has no interactive escape hatch, so a visitor it cannot clear
28
+ * silently loses the ability to submit at all.
29
+ *
22
30
  * @example
23
31
  * ```tsx
24
32
  * <form action={`https://aifeatures.dev/f/${formId}`} method="POST">
@@ -97,6 +105,43 @@ interface PublicVariant {
97
105
  /** Units remaining when tracked; null when unlimited (untracked/backorder). */
98
106
  available: number | null;
99
107
  }
108
+ /**
109
+ * One subscription selling plan (subscriptions Unit 2/8). Amounts are NEVER
110
+ * localized: plans bill in the store's BASE currency, so `unit_amount` is
111
+ * base-currency minor units and `percent_off_bps` applies to the
112
+ * base-currency variant price — on a localized product response, label plan
113
+ * prices with `base_currency`, never with the converted `currency`.
114
+ */
115
+ interface PublicSubscriptionPlan {
116
+ id: string;
117
+ /** 'week' | 'month' | 'year' (stored verbatim — render unknowns as-is). */
118
+ interval: string;
119
+ interval_count: number;
120
+ /** Merchant display name ("Subscribe & save 15%"); null = derive a label. */
121
+ title: string | null;
122
+ /** Display order (the server already sorts by it). */
123
+ position: number;
124
+ /** Basis points off the one-time price (1500 = 15%); null for absolute plans. */
125
+ percent_off_bps: number | null;
126
+ /** Absolute recurring price in BASE-currency minor units; null for percent plans. */
127
+ unit_amount: number | null;
128
+ }
129
+ /**
130
+ * The product's subscription offer block. Null when there is nothing to
131
+ * render (no active plans and not subscription-only).
132
+ */
133
+ interface PublicProductSubscription {
134
+ /** Subscription-only product — no one-time purchase option. */
135
+ required: boolean;
136
+ /**
137
+ * Whether subscription checkout can be offered RIGHT NOW (payments active
138
+ * AND the published site serves /account). false → hide the plans (or, for
139
+ * a required product, render the "currently unavailable" default) — never
140
+ * explain why to a visitor.
141
+ */
142
+ ready: boolean;
143
+ plans: PublicSubscriptionPlan[];
144
+ }
100
145
  /**
101
146
  * Public (buyer-facing) product config, exactly as returned by
102
147
  * `GET {apiUrl}/v1/p/{productId}`. Field names stay snake_case to match the wire
@@ -187,6 +232,12 @@ interface PublicProduct {
187
232
  options: PublicOption[];
188
233
  /** Active, purchasable variants. Always at least one (the default variant). */
189
234
  variants: PublicVariant[];
235
+ /**
236
+ * Subscription selling plans (additive, subscriptions Unit 2). Null/absent
237
+ * when the product offers none — optional so older API deployments that
238
+ * omit the field still typecheck.
239
+ */
240
+ subscription?: PublicProductSubscription | null;
190
241
  }
191
242
  interface UseProductOptions {
192
243
  /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
@@ -394,6 +445,24 @@ interface StartCheckoutOptions {
394
445
  cancelUrl?: string;
395
446
  /** Prefills the email field on the Stripe Checkout page. */
396
447
  customerEmail?: string;
448
+ /**
449
+ * Subscription selling plan to buy (subscriptions Unit 8). Present =
450
+ * subscription-mode checkout: quantity is locked at 1 (any `quantity`
451
+ * passed is ignored), the buyer's market country is not sent (plans bill
452
+ * in the store's base currency, never localized), and no price
453
+ * expectation rides (the recurring amount is plan-derived server-side).
454
+ *
455
+ * When a session token is stored (the buyer signed in on this site), the
456
+ * purchase goes through POST /v1/account/subscribe with the bearer so a
457
+ * proven Stripe Customer can be reused. On a DEFINITIVE 401/404 from that
458
+ * twin (stale token, re-darkened /v1/account prefix) the stored token is
459
+ * cleared and the SAME purchase silently retries anonymously via /v1/p —
460
+ * one retry, no visible error (plan §Stripe Customer handling).
461
+ * Timeouts/network errors/5xx render the standard error state instead,
462
+ * token untouched, NO automatic retry: the original request may have
463
+ * succeeded, and a blind retry would double-mint sessions.
464
+ */
465
+ planId?: string;
397
466
  /**
398
467
  * The EXACT unit price the page displayed (minor units) — pass it so a
399
468
  * price the merchant edited between render and click makes the server
@@ -797,7 +866,11 @@ interface ShippingOptionConflict {
797
866
  }
798
867
  interface CartConflictItem {
799
868
  variant_id: string;
800
- code: 'unavailable' | 'insufficient_stock' | 'price_changed' | 'quantity_exceeds_max';
869
+ code: 'unavailable' | 'insufficient_stock' | 'price_changed' | 'quantity_exceeds_max'
870
+ /** The merchant made this product subscription-only after the cart was
871
+ * built. There is no quantity or price to fix — the line has to go, and
872
+ * the product is bought from its own page via PlanPicker instead. */
873
+ | 'subscription_only';
801
874
  /** insufficient_stock only: units currently available. */
802
875
  available?: number;
803
876
  /** price_changed only: the per-unit price checkout would charge NOW. */
@@ -1007,6 +1080,15 @@ interface BuyButtonProps {
1007
1080
  variantId?: string;
1008
1081
  /** Defaults to 1. Must be within [1, max_quantity]. */
1009
1082
  quantity?: number;
1083
+ /**
1084
+ * Subscription selling plan to buy (get it from `<PlanPicker onChange>`;
1085
+ * null/undefined = one-time purchase). A selected plan locks quantity at 1,
1086
+ * switches the default label to "Subscribe", and sends `plan_id` with the
1087
+ * checkout — through POST /v1/account/subscribe when the buyer has a
1088
+ * stored session, with the silent anonymous fallback on a definitive
1089
+ * 401/404 (see useCheckout's planId doc).
1090
+ */
1091
+ planId?: string | null;
1010
1092
  /** Total amount in minor units — custom-amount (tip jar) products only. */
1011
1093
  amount?: number;
1012
1094
  /** Opaque passthrough stored on the order (string values only). */
@@ -1046,7 +1128,7 @@ interface BuyButtonProps {
1046
1128
  *
1047
1129
  * Unstyled by default — pass className/style to match the site's design.
1048
1130
  */
1049
- declare function BuyButton({ productId, variantId, quantity, amount, metadata, successUrl, cancelUrl, customerEmail, apiUrl, disabled, className, style, errorClassName, spinner, children, }: BuyButtonProps): react_jsx_runtime.JSX.Element;
1131
+ 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;
1050
1132
 
1051
1133
  interface AddToCartButtonProps {
1052
1134
  /** Product ID from aifeatures */
@@ -1200,6 +1282,19 @@ interface OrderSessionLineItem {
1200
1282
  */
1201
1283
  refund_reason?: "oversold" | "merchant";
1202
1284
  }
1285
+ /**
1286
+ * Renewal terms of a subscription signup order (subscriptions Unit 3/8) —
1287
+ * locked at checkout from the order's own plan snapshot, never from live
1288
+ * plan rows.
1289
+ */
1290
+ interface OrderSessionSubscription {
1291
+ /** 'week' | 'month' | 'year' (stored verbatim). */
1292
+ interval: string;
1293
+ interval_count: number;
1294
+ /** The recurring charge in minor units of `currency` — what renews. */
1295
+ amount: number;
1296
+ currency: string;
1297
+ }
1203
1298
  /**
1204
1299
  * Response shape of `GET {apiUrl}/v1/o/session/{sessionId}` (snake_case wire
1205
1300
  * format). Deliberately carries NO buyer PII (no email/name) — the session id
@@ -1231,6 +1326,13 @@ interface OrderSession {
1231
1326
  currency?: string;
1232
1327
  /** What was bought — a receipt-style summary. */
1233
1328
  line_items?: OrderSessionLineItem[];
1329
+ /**
1330
+ * Present ONLY on subscription signup orders (append-only wire additions —
1331
+ * one-time payloads stay byte-identical): 'subscription' marks the order
1332
+ * as a signup, and `subscription` carries its renewal terms.
1333
+ */
1334
+ source?: "checkout" | "subscription";
1335
+ subscription?: OrderSessionSubscription;
1234
1336
  }
1235
1337
  interface OrderConfirmationProps {
1236
1338
  /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
@@ -1272,4 +1374,531 @@ interface OrderConfirmationProps {
1272
1374
  }
1273
1375
  declare function OrderConfirmation({ apiUrl, className, style, sessionId: sessionIdProp, pollIntervalMs, pollTimeoutMs, followRedirect, redirectDelayMs, renderNoSession, renderPending, renderPaid, renderFailed, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element | null;
1274
1376
 
1275
- 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 };
1377
+ /**
1378
+ * The recurring price a plan derives from a base one-time price, in minor
1379
+ * units.
1380
+ *
1381
+ * MIRROR: packages/api/src/lib/subscriptionPlans.ts `planRecurringAmount` is
1382
+ * the SOURCE OF TRUTH — keep this byte-equivalent. The rounding is
1383
+ * deliberate and must match exactly: percent discounts round the DISCOUNT
1384
+ * down (Math.floor), i.e. the recurring price UP — the merchant advertised
1385
+ * "up to N% off", and a price displayed here that rounds the other way would
1386
+ * differ from what checkout actually charges every cycle.
1387
+ */
1388
+ declare function planRecurringAmount(baseUnitAmount: number, plan: Pick<PublicSubscriptionPlan, 'percent_off_bps' | 'unit_amount'>): number;
1389
+ interface PlanPickerOptionContext {
1390
+ /** The plan this option represents — null for the one-time option. */
1391
+ plan: PublicSubscriptionPlan | null;
1392
+ selected: boolean;
1393
+ /**
1394
+ * Recurring price in BASE-currency minor units (one-time option: the base
1395
+ * price itself). Null when it cannot be derived — a percent plan with no
1396
+ * usable base price, e.g. a localized product response (plan prices are
1397
+ * never fx-localized) or a custom-amount product.
1398
+ */
1399
+ price: number | null;
1400
+ /** `price` formatted with the BASE currency ("$25.50"), or null. */
1401
+ priceLabel: string | null;
1402
+ /** Default display label ("Subscribe & save 15% — $21.25 every month"). */
1403
+ label: string;
1404
+ /** Select this option. */
1405
+ select: () => void;
1406
+ }
1407
+ interface PlanPickerProps {
1408
+ /**
1409
+ * The product from `useProduct` — the picker reads `product.subscription`,
1410
+ * plus the base price/currency for percent-plan math. Alternatively pass
1411
+ * `subscription` (and `baseUnitAmount`/`currency`) directly.
1412
+ */
1413
+ product?: PublicProduct | null;
1414
+ /** The subscription payload, when not passing `product`. */
1415
+ subscription?: PublicProductSubscription | null;
1416
+ /**
1417
+ * Base one-time price (BASE-currency minor units) percent plans discount.
1418
+ * Pass the SELECTED variant's price on multi-variant products so the
1419
+ * displayed plan price tracks the variant. Defaults to the product's
1420
+ * top-level `unit_amount` — but only on a NON-localized response: plan
1421
+ * prices are never fx-localized (they bill in the store's base currency),
1422
+ * so on a localized response percent plans render without a computed
1423
+ * price unless you supply the base-currency amount here.
1424
+ */
1425
+ baseUnitAmount?: number | null;
1426
+ /** Currency for plan price labels (defaults to the product's BASE currency). */
1427
+ currency?: string;
1428
+ /**
1429
+ * Controlled selection: a plan id, or null for one-time. Omit for
1430
+ * uncontrolled (defaults to one-time — or the first plan by position when
1431
+ * the product is subscription-only).
1432
+ */
1433
+ value?: string | null;
1434
+ /** Fires with the chosen plan id (null = one-time) — including the
1435
+ * automatic subscription-required default on mount. */
1436
+ onChange?: (planId: string | null) => void;
1437
+ className?: string;
1438
+ style?: CSSProperties;
1439
+ /** Class for every option row. */
1440
+ optionClassName?: string;
1441
+ /** Class added to the selected option row. */
1442
+ selectedOptionClassName?: string;
1443
+ /** Label for the one-time option (default "One-time purchase"). */
1444
+ oneTimeLabel?: ReactNode;
1445
+ /** Replace an option row entirely (both plan and one-time rows). */
1446
+ renderOption?: (ctx: PlanPickerOptionContext) => ReactNode;
1447
+ /**
1448
+ * Rendered when the product is subscription-only but subscriptions can't
1449
+ * be offered right now (`required && !ready`). The default is a
1450
+ * plain-statement "currently unavailable" — deliberately reason-free
1451
+ * (merchant configuration state never surfaces to visitors); overrides
1452
+ * should restyle it, not explain it.
1453
+ */
1454
+ renderUnavailable?: () => ReactNode;
1455
+ }
1456
+ /**
1457
+ * Headless single-select for subscription selling plans (subscriptions R2).
1458
+ * Renders the one-time option plus one row per plan — or plans only when the
1459
+ * product is subscription-required. Feed the selection to `<BuyButton
1460
+ * planId>` (a selected plan locks quantity at 1 and switches the CTA to
1461
+ * "Subscribe").
1462
+ *
1463
+ * Degraded states (plan §Unit 8, default copy is deliberate):
1464
+ * - no subscription block → renders nothing (one-time only);
1465
+ * - `ready: false`, not required → renders nothing — plans are silently
1466
+ * hidden, the one-time path is untouched, no error surface;
1467
+ * - `ready: false`, required → the "currently unavailable" default
1468
+ * (renderUnavailable), with no purchase controls and no reason given.
1469
+ */
1470
+ declare function PlanPicker({ product, subscription: subscriptionProp, baseUnitAmount, currency, value, onChange, className, style, optionClassName, selectedOptionClassName, oneTimeLabel, renderOption, renderUnavailable, }: PlanPickerProps): react_jsx_runtime.JSX.Element | null;
1471
+
1472
+ interface StoredSessionCustomer {
1473
+ email: string;
1474
+ name: string | null;
1475
+ }
1476
+
1477
+ type SessionStatus = 'signed_out' | 'pending' | 'signed_in' | 'unavailable';
1478
+ type SessionCustomer = StoredSessionCustomer;
1479
+ /** Why the hook is signed_out, when it wasn't a plain fresh visit. */
1480
+ type SessionReason = 'session_expired' | 'invalid_code' | null;
1481
+ interface UseSessionOptions {
1482
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1483
+ apiUrl?: string;
1484
+ /**
1485
+ * Whether THIS instance consumes a `?code=` magic-link param from the URL
1486
+ * on mount (default true). Exactly ONE mounted instance must own the
1487
+ * consumption — the code is single-use server-side, so a second instance
1488
+ * exchanging it burns it and strands the reason on the wrong hook.
1489
+ * AccountLogin sets this false when a parent session is passed in
1490
+ * (AccountPage owns the URL there). Read once on mount.
1491
+ */
1492
+ consumeUrlCode?: boolean;
1493
+ }
1494
+ type LoginResult =
1495
+ /** `via: 'preview'` — the editor host claimed the handshake and minted a
1496
+ * preview session (already signed in, no email was sent). */
1497
+ {
1498
+ ok: true;
1499
+ via: 'email' | 'preview';
1500
+ } | {
1501
+ ok: false;
1502
+ code: 'rate_limited' | 'unavailable' | 'error';
1503
+ error: string;
1504
+ };
1505
+ type VerifyResult = {
1506
+ ok: true;
1507
+ } | {
1508
+ ok: false;
1509
+ code: 'invalid_code' | 'rate_limited' | 'unavailable' | 'error';
1510
+ error: string;
1511
+ };
1512
+ interface UseSessionResult {
1513
+ status: SessionStatus;
1514
+ /** Display echo (email/name) — null until signed in. */
1515
+ customer: SessionCustomer | null;
1516
+ /** The session bearer — null unless signed in. */
1517
+ token: string | null;
1518
+ /** Why signed_out, when there is a why (expired session, bad code). */
1519
+ reason: SessionReason;
1520
+ /**
1521
+ * Request a magic link for `email` (uniform 200 — "sent" even for unknown
1522
+ * addresses, by server design). Inside the editor iframe this offers the
1523
+ * preview-session handshake to the host first and only falls back to the
1524
+ * real POST when nothing claims it.
1525
+ */
1526
+ login: (email: string) => Promise<LoginResult>;
1527
+ /** POST-exchange a login code (single-use) for a session. */
1528
+ verifyCode: (code: string) => Promise<VerifyResult>;
1529
+ /** Delete the server session (best-effort) and clear the stored token. */
1530
+ logout: () => Promise<void>;
1531
+ /**
1532
+ * Re-validate the stored session against GET /v1/account/me: a live session
1533
+ * refreshes the customer echo; 401 clears it (signed_out, reason
1534
+ * 'session_expired'); a whole-prefix 404 flips to 'unavailable'. Network
1535
+ * errors leave the state untouched.
1536
+ */
1537
+ refresh: () => Promise<void>;
1538
+ }
1539
+ /**
1540
+ * Customer-account session state (subscriptions Unit 8). The token lives in
1541
+ * origin-scoped storage (`aifeatures_session`, sessionStorage.ts) so every
1542
+ * mounted instance — account page, buy box — shares one signed-in answer,
1543
+ * cross-tab included.
1544
+ *
1545
+ * On mount it consumes a `?code=` magic-link param from the URL: stripped via
1546
+ * history.replaceState BEFORE the exchange (OrderConfirmation's precedent —
1547
+ * the code must not linger in history/analytics/Referer), then POSTed to
1548
+ * /v1/account/verify (POST-to-consume defeats scanner prefetch; the code is
1549
+ * single-use server-side).
1550
+ *
1551
+ * Degradations (plan §Magic-link flow): a whole-prefix 404 (dark-launched or
1552
+ * re-darkened /v1/account) maps to status 'unavailable' — components render
1553
+ * "sign-in temporarily unavailable", never a dead error.
1554
+ */
1555
+ declare function useSession(options?: UseSessionOptions): UseSessionResult;
1556
+
1557
+ interface AccountLoginFormContext {
1558
+ email: string;
1559
+ setEmail: (email: string) => void;
1560
+ submit: () => void;
1561
+ submitting: boolean;
1562
+ /** 'rate_limited' (429 from /login) or 'error' (network/unexpected). */
1563
+ errorKind: 'rate_limited' | 'error' | null;
1564
+ errorMessage: string | null;
1565
+ /** Why the visitor is signed out, when there is a why. */
1566
+ reason: SessionReason;
1567
+ }
1568
+ interface AccountLoginSentContext {
1569
+ email: string;
1570
+ /** True once the resend affordance should show (~30s after the send). */
1571
+ canResend: boolean;
1572
+ /** Re-request the link (generic copy either way — cooldowns are invisible
1573
+ * uniform 200s server-side). */
1574
+ resend: () => void;
1575
+ submitting: boolean;
1576
+ /** Go back to the email form. */
1577
+ reset: () => void;
1578
+ }
1579
+ interface AccountLoginProps {
1580
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1581
+ apiUrl?: string;
1582
+ /**
1583
+ * Share a parent's useSession() (AccountPage passes its own so the login
1584
+ * form and the page agree on status). Omit to run standalone.
1585
+ */
1586
+ session?: UseSessionResult;
1587
+ /** Delay before the resend affordance appears (default 30s). */
1588
+ resendDelayMs?: number;
1589
+ className?: string;
1590
+ style?: CSSProperties;
1591
+ /** Replace the email-entry state (also carries invalid-code / expired /
1592
+ * rate-limited context). */
1593
+ renderForm?: (ctx: AccountLoginFormContext) => ReactNode;
1594
+ /** Replace the check-your-email state. */
1595
+ renderSent?: (ctx: AccountLoginSentContext) => ReactNode;
1596
+ /** Replace the sign-in-temporarily-unavailable state (dark /v1/account
1597
+ * prefix). The default deliberately has NO resend CTA — none can work. */
1598
+ renderUnavailable?: () => ReactNode;
1599
+ }
1600
+ /**
1601
+ * Magic-link sign-in for the account page (subscriptions R6/R9). States, all
1602
+ * with working unstyled defaults and render-prop overrides:
1603
+ *
1604
+ * - email entry (with the session-expired / invalid-code notice above it —
1605
+ * an invalid or expired link's recovery IS this form: "email me a new
1606
+ * link");
1607
+ * - check-your-email, with a resend affordance after ~30s. The copy stays
1608
+ * generic on purpose: the server answers a uniform 200 whether or not it
1609
+ * sent (unknown emails, cooldowns), so this component can never promise
1610
+ * more than "if that address has orders here, a link is on its way";
1611
+ * - rate-limited (a real 429 from /login);
1612
+ * - sign-in temporarily unavailable (whole-prefix 404 — dark-launched or
1613
+ * re-darkened /v1/account): a plain statement with NO resend CTA, because
1614
+ * no resend can work.
1615
+ *
1616
+ * Inside the editor iframe, submit engages the preview-session handshake
1617
+ * (useSession.login) and signs straight in when the host claims it — the
1618
+ * check-your-email state is skipped.
1619
+ */
1620
+ declare function AccountLogin({ apiUrl, session: sessionProp, resendDelayMs, className, style, renderForm, renderSent, renderUnavailable, }: AccountLoginProps): react_jsx_runtime.JSX.Element;
1621
+
1622
+ interface AccountPagePmBannerContext {
1623
+ /** 'retrying' while a subscription is still past_due after the card
1624
+ * update; 'recovered' once nothing is. */
1625
+ state: 'retrying' | 'recovered';
1626
+ /** Manual re-check while the retry is pending. */
1627
+ checkAgain: () => void;
1628
+ checking: boolean;
1629
+ }
1630
+ interface AccountPageProps {
1631
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1632
+ apiUrl?: string;
1633
+ className?: string;
1634
+ style?: CSSProperties;
1635
+ /** Forwarded to the built-in AccountLogin (delay before resend shows). */
1636
+ resendDelayMs?: number;
1637
+ /** Override pieces of the built-in login (render props etc.). */
1638
+ loginProps?: Omit<AccountLoginProps, 'apiUrl' | 'session'>;
1639
+ /** Replace the whole-page loading state (code exchange, /me fetch). */
1640
+ renderLoading?: () => ReactNode;
1641
+ /** Replace the /me error state. */
1642
+ renderError?: (ctx: {
1643
+ error: string;
1644
+ retry: () => void;
1645
+ }) => ReactNode;
1646
+ /** Replace the signed-in-but-nothing-here state. */
1647
+ renderEmpty?: () => ReactNode;
1648
+ /** Replace the signed-in header (customer email + sign out). */
1649
+ renderHeader?: (ctx: {
1650
+ customer: {
1651
+ email: string;
1652
+ name: string | null;
1653
+ };
1654
+ site: {
1655
+ name: string;
1656
+ } | null;
1657
+ signOut: () => void;
1658
+ }) => ReactNode;
1659
+ /** Replace the `?pm=updated` portal-return banner. */
1660
+ renderPmBanner?: (ctx: AccountPagePmBannerContext) => ReactNode;
1661
+ /** Replace the manage-grant expired state (login recovery below it stays). */
1662
+ renderManageExpired?: () => ReactNode;
1663
+ }
1664
+ /**
1665
+ * The buyer account page for the site's `/account` route (subscriptions
1666
+ * R9/R14): magic-link sign-in, order history, subscription management —
1667
+ * or, arriving via `?manage_code=` (the manage-link resolver's handoff), a
1668
+ * single-subscription manage view that ignores any ambient session.
1669
+ *
1670
+ * URL consumption on mount, all stripped via history.replaceState before any
1671
+ * network use (OrderConfirmation's precedent):
1672
+ * - `?code=` → POST-exchanged for a session (useSession);
1673
+ * - `?manage_code=` → POST-exchanged for a manage grant. The grant token
1674
+ * lives in component memory ONLY — never storage, never
1675
+ * a URL (plan §Manage link);
1676
+ * - `?pm=updated` → the portal-return marker: re-fetch on mount and show
1677
+ * "card updated — retrying" (still past_due) vs
1678
+ * "recovered" (active), with a manual "check again".
1679
+ *
1680
+ * Degradations: a whole-prefix 404 anywhere maps back to the login state —
1681
+ * with the dedicated "sign-in temporarily unavailable" copy when the login
1682
+ * submit itself hits the dark prefix (AccountLogin); a 401 mid-browse clears
1683
+ * the stored token and returns to email entry with a brief message, keeping
1684
+ * the buyer on this page.
1685
+ */
1686
+ declare function AccountPage({ apiUrl, className, style, resendDelayMs, loginProps, renderLoading, renderError, renderEmpty, renderHeader, renderPmBanner, renderManageExpired, }: AccountPageProps): react_jsx_runtime.JSX.Element;
1687
+
1688
+ /**
1689
+ * INTERNAL module — shared wire types + fetch classification for the
1690
+ * /v1/account surface (subscriptions Unit 8). Not exported from the package
1691
+ * index except for the payload TYPES (re-exported by the barrel).
1692
+ *
1693
+ * The one non-obvious rule lives here: DARK-PREFIX DETECTION. The whole
1694
+ * /v1/account prefix ships behind a config flag and re-darkening is a live
1695
+ * incident-response move (plan §Magic-link flow), so every route can answer
1696
+ * an EMPTY-BODY 404 indistinguishable from a path that doesn't exist. Live
1697
+ * routes that legitimately 404 (e.g. "Subscription not found") always carry
1698
+ * a JSON `{error}` body — so `404 with a completely EMPTY body` is classified
1699
+ * `unavailable`, and components map it to the login / "temporarily
1700
+ * unavailable" states instead of a dead error. A 404 that carries ANYTHING
1701
+ * (that JSON error, or an interposed proxy/CDN's HTML page) is an ordinary
1702
+ * refusal: the session is not implicated and must not be cleared.
1703
+ */
1704
+ /** One order row from GET /v1/account/me (bounded receipt shelf). */
1705
+ interface AccountOrder {
1706
+ id: string;
1707
+ order_number: number | null;
1708
+ status: string;
1709
+ /** 'checkout' | 'cart' | 'subscription' — subscription = signup or renewal. */
1710
+ source: string;
1711
+ amount_total: number;
1712
+ shipping_total: number | null;
1713
+ tax_total: number | null;
1714
+ currency: string;
1715
+ created_at: string;
1716
+ line_items: Array<{
1717
+ name: string | null;
1718
+ quantity: number | null;
1719
+ unit_amount: number | null;
1720
+ }>;
1721
+ }
1722
+ /**
1723
+ * One subscription row, as serialized by the session surface
1724
+ * (`subscriberSubscriptionView`) — the manage-grant view
1725
+ * (`manageSubscriptionView`) is the same shape minus `product_id` /
1726
+ * `created_at` / `shipping_address`, plus `shipping_name` / `shipping_city`,
1727
+ * so the optional fields cover both doorways with one type.
1728
+ */
1729
+ interface AccountSubscription {
1730
+ id: string;
1731
+ /** Stripe status verbatim ('active', 'past_due', …) — render unmodeled
1732
+ * values generically, never throw on them. */
1733
+ status: string;
1734
+ product_id?: string;
1735
+ plan_title: string | null;
1736
+ plan_interval: string;
1737
+ plan_interval_count: number;
1738
+ /** Locked signup amount (minor units). */
1739
+ plan_amount: number;
1740
+ /** Current recurring amount mirrored from Stripe (falls back to plan_amount). */
1741
+ current_amount: number;
1742
+ currency: string;
1743
+ current_period_end: string | null;
1744
+ cancel_at_period_end: boolean;
1745
+ canceled_at: string | null;
1746
+ /** Terminal — no future invoice can arrive. "Ended — resubscribe" copy. */
1747
+ ended: boolean;
1748
+ is_test: boolean;
1749
+ created_at?: string;
1750
+ shipping_address?: {
1751
+ name?: string | null;
1752
+ address?: {
1753
+ line1?: string | null;
1754
+ line2?: string | null;
1755
+ city?: string | null;
1756
+ state?: string | null;
1757
+ postal_code?: string | null;
1758
+ country?: string | null;
1759
+ } | null;
1760
+ } | null;
1761
+ /** Manage-grant view only. */
1762
+ shipping_name?: string | null;
1763
+ shipping_city?: string | null;
1764
+ }
1765
+ /** Response of GET /v1/account/me. */
1766
+ interface AccountMePayload {
1767
+ customer: {
1768
+ email: string;
1769
+ name: string | null;
1770
+ };
1771
+ site: {
1772
+ name: string;
1773
+ };
1774
+ orders: AccountOrder[];
1775
+ subscriptions: AccountSubscription[];
1776
+ }
1777
+ /** The shipping_address input shape POST /subscriptions/:id/address accepts. */
1778
+ interface AccountShippingAddressInput {
1779
+ name?: string | null;
1780
+ address: {
1781
+ line1: string;
1782
+ line2?: string | null;
1783
+ city?: string | null;
1784
+ state?: string | null;
1785
+ postal_code?: string | null;
1786
+ country: string;
1787
+ };
1788
+ }
1789
+
1790
+ interface AccountOrdersProps {
1791
+ /** The `orders` array from GET /v1/account/me (newest first, bounded). */
1792
+ orders: AccountOrder[];
1793
+ className?: string;
1794
+ style?: CSSProperties;
1795
+ /** Section heading (default "Your orders"); null renders none. */
1796
+ heading?: ReactNode | null;
1797
+ /** Replace the no-orders state. */
1798
+ renderEmpty?: () => ReactNode;
1799
+ /** Replace one order row. */
1800
+ renderOrder?: (order: AccountOrder) => ReactNode;
1801
+ }
1802
+ /**
1803
+ * The signed-in buyer's order history (subscriptions R9) — a receipt shelf,
1804
+ * presentational only: hand it the `orders` from /v1/account/me. Unstyled
1805
+ * defaults; restyle via className or replace rows via renderOrder.
1806
+ */
1807
+ declare function AccountOrders({ orders, className, style, heading, renderEmpty, renderOrder, }: AccountOrdersProps): react_jsx_runtime.JSX.Element;
1808
+
1809
+ /**
1810
+ * Which doorway this list acts through:
1811
+ * - 'session': the signed-in account page — per-subscription
1812
+ * /v1/account/subscriptions/:id/* endpoints (cancel, reactivate, address,
1813
+ * FULL-config portal).
1814
+ * - 'manage': the emailed manage-grant — the /v1/account/manage/* endpoints,
1815
+ * scoped to exactly ONE subscription (cancel, MINIMAL-config card-update; no
1816
+ * address change, and NO REACTIVATE — the grant token lives in component
1817
+ * memory only, never in storage).
1818
+ *
1819
+ * WHY 'manage' CANNOT REACTIVATE. The grant descends from a token emailed with
1820
+ * a receipt, which proves only that someone once received an email — a shared
1821
+ * inbox, a forward, a mailbox compromised later. A magic-link sign-in proves
1822
+ * CURRENT control of the mailbox. Stopping money (cancel) and preserving money
1823
+ * (card update) are fine on the weaker proof; STARTING money is not, so the
1824
+ * server does not serve /v1/account/manage/reactivate at all. `paths()` nulls it
1825
+ * the same way it nulls `address`, and the row renders a sign-in pointer where
1826
+ * the button would be.
1827
+ */
1828
+ type SubscriptionListAuth = {
1829
+ kind: 'session';
1830
+ token: string;
1831
+ } | {
1832
+ kind: 'manage';
1833
+ token: string;
1834
+ };
1835
+ type MutationKind = 'cancel' | 'reactivate' | 'address' | 'portal';
1836
+ interface SubscriptionMutationState {
1837
+ kind: MutationKind;
1838
+ phase: 'pending' | 'error' | 'success';
1839
+ error?: string;
1840
+ }
1841
+ interface SubscriptionRowContext {
1842
+ subscription: AccountSubscription;
1843
+ /** Open panel: cancel confirmation or the address form. */
1844
+ panel: 'none' | 'confirm_cancel' | 'address';
1845
+ mutation: SubscriptionMutationState | null;
1846
+ /** True when the card-update button should not render (test rows, or the
1847
+ * server answered portal_unavailable). */
1848
+ portalHidden: boolean;
1849
+ openCancelConfirm: () => void;
1850
+ closePanel: () => void;
1851
+ confirmCancel: () => void;
1852
+ /** No-ops in the 'manage' doorway — restarting billing needs a session, so
1853
+ * `reactivateAvailable` is false there and a custom renderRow must render the
1854
+ * sign-in pointer instead of a button. */
1855
+ reactivate: () => void;
1856
+ /** False in the 'manage' doorway: the server serves no grant-scoped
1857
+ * reactivate. */
1858
+ reactivateAvailable: boolean;
1859
+ openAddressForm: () => void;
1860
+ saveAddress: (address: AccountShippingAddressInput) => void;
1861
+ openPortal: () => void;
1862
+ }
1863
+ interface SubscriptionListProps {
1864
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1865
+ apiUrl?: string;
1866
+ subscriptions: AccountSubscription[];
1867
+ auth: SubscriptionListAuth;
1868
+ /** The bearer was refused (session_expired / manage_expired) — the parent
1869
+ * should drop to its signed-out / grant-expired state. */
1870
+ onAuthError?: (failure: {
1871
+ code: string | null;
1872
+ error: string;
1873
+ }) => void;
1874
+ /** The whole /v1/account prefix answered dark 404s mid-browse. */
1875
+ onUnavailable?: () => void;
1876
+ /** A mutation returned a fresh row (also fired when a raced terminal
1877
+ * cancel comes back `ended`). */
1878
+ onSubscriptionChange?: (sub: AccountSubscription) => void;
1879
+ className?: string;
1880
+ style?: CSSProperties;
1881
+ /** Section heading (default "Your subscriptions"); null renders none. */
1882
+ heading?: ReactNode | null;
1883
+ /** Replace the no-subscriptions state. */
1884
+ renderEmpty?: () => ReactNode;
1885
+ /** Replace one subscription row (receives the full action context). */
1886
+ renderRow?: (ctx: SubscriptionRowContext) => ReactNode;
1887
+ }
1888
+ /**
1889
+ * The subscriber's subscription rows (subscriptions R9/R12): status per
1890
+ * state (active / past_due / scheduled-to-cancel with lapse date + reactivate
1891
+ * / ended with resubscribe copy), a cancel flow with an explicit confirm step
1892
+ * stating the lapse date, reactivate, shipping-address editing (session
1893
+ * doorway only), and the card-update portal handoff — hidden for test rows
1894
+ * and after a `portal_unavailable` refusal, since no working card-update
1895
+ * exists behind it.
1896
+ *
1897
+ * Mutation arcs are per-row pending / error-with-retry / success. A raced
1898
+ * terminal cancel (`ended` code) flips the row to its ended state rather
1899
+ * than erroring — the copy is "this subscription has ended", and the only
1900
+ * path onward is resubscribing on the product page.
1901
+ */
1902
+ declare function SubscriptionList({ apiUrl, subscriptions, auth, onAuthError, onUnavailable, onSubscriptionChange, className, style, heading, renderEmpty, renderRow, }: SubscriptionListProps): react_jsx_runtime.JSX.Element;
1903
+
1904
+ 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 };