@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.cjs +1 -1
- package/dist/index.d.cts +632 -3
- package/dist/index.d.ts +632 -3
- package/dist/index.js +1 -1
- package/package.json +11 -10
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
|
-
|
|
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 };
|