@aifeatures/react 0.1.8 → 0.3.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.cts CHANGED
@@ -1,4 +1,5 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import { CSSProperties, ReactNode } from 'react';
2
3
 
3
4
  interface AifeaturesCaptchaProps {
4
5
  /** Form ID from aifeatures - used to fetch the Turnstile sitekey */
@@ -30,4 +31,1227 @@ interface AifeaturesCaptchaProps {
30
31
  */
31
32
  declare function AifeaturesCaptcha({ formId, apiUrl, onVerify, onError, className, }: AifeaturesCaptchaProps): react_jsx_runtime.JSX.Element | null;
32
33
 
33
- export { AifeaturesCaptcha, type AifeaturesCaptchaProps };
34
+ /** One selectable value of an option (e.g. "L" of "Size"). */
35
+ interface PublicOptionValue {
36
+ id: string;
37
+ value: string;
38
+ /**
39
+ * Images to show when this value is selected (e.g. model shots of the
40
+ * Black colorway), in display order. Empty for values that carry no
41
+ * imagery of their own — fall back to `product.images` (or just use
42
+ * `selectedImages()`, which applies that rule for you).
43
+ */
44
+ images: string[];
45
+ }
46
+ /** A product option axis (e.g. "Size", "Color") the buyer chooses from. */
47
+ interface PublicOption {
48
+ id: string;
49
+ title: string;
50
+ values: PublicOptionValue[];
51
+ }
52
+ /** The coordinates of a variant on the option grid (one entry per option). */
53
+ interface PublicVariantOptionValue {
54
+ option_id: string;
55
+ option_title: string;
56
+ value_id: string;
57
+ value: string;
58
+ }
59
+ /**
60
+ * A purchasable variant of a product. Pricing and stock live here — the
61
+ * variant is the unit that checkout charges for. Single-variant products
62
+ * (digital downloads, tips) still expose one variant, with an empty
63
+ * `option_values`.
64
+ */
65
+ interface PublicVariant {
66
+ id: string;
67
+ /** Null for the default variant of a single-variant product. */
68
+ title: string | null;
69
+ sku: string | null;
70
+ /** Price in minor units. Null for custom-amount (tip jar) variants. */
71
+ unit_amount: number | null;
72
+ /** Strike-through "was" price when marked down; null otherwise. */
73
+ compare_at_amount: number | null;
74
+ currency: string;
75
+ allow_custom_amount: boolean;
76
+ min_amount: number | null;
77
+ max_amount: number | null;
78
+ option_values: PublicVariantOptionValue[];
79
+ /** False when tracked and sold out — show it, but block purchase. */
80
+ in_stock: boolean;
81
+ /** Units remaining when tracked; null when unlimited (untracked/backorder). */
82
+ available: number | null;
83
+ }
84
+ /**
85
+ * Public (buyer-facing) product config, exactly as returned by
86
+ * `GET {apiUrl}/v1/p/{productId}`. Field names stay snake_case to match the wire
87
+ * format — the same convention the package already uses for form config.
88
+ * All amounts are integers in the currency's minor unit (cents for USD).
89
+ */
90
+ interface PublicProduct {
91
+ id: string;
92
+ name: string;
93
+ description: string | null;
94
+ images: string[];
95
+ /**
96
+ * Price in minor units. Null for custom-amount (tip jar) products. For a
97
+ * multi-variant product this mirrors the default (first active) variant —
98
+ * use `variants` for per-variant prices and a range.
99
+ */
100
+ unit_amount: number | null;
101
+ currency: string;
102
+ /**
103
+ * Set only when the prices in this response were converted to your
104
+ * visitor's currency (localized pricing); the value is the merchant's own
105
+ * currency. Null/undefined = native response. Optional so older API
106
+ * deployments that omit the field still typecheck.
107
+ */
108
+ base_currency?: string | null;
109
+ /** Tip-jar style: buyer picks the amount within [min_amount, max_amount]. */
110
+ allow_custom_amount: boolean;
111
+ min_amount: number | null;
112
+ max_amount: number | null;
113
+ max_quantity: number;
114
+ fulfillment_type: "none" | "download" | "redirect";
115
+ collect_shipping_address: boolean;
116
+ /**
117
+ * Where the STORE ships, as uppercase ISO 3166-1 alpha-2 codes. Show it near
118
+ * the buy button when present — an address outside the list cannot complete
119
+ * checkout, and Stripe is a late place to find that out.
120
+ *
121
+ * Absent means there is nothing to show: the store ships anywhere Stripe
122
+ * serves, this product collects no shipping address, or the API predates the
123
+ * field. Never treat undefined as "ships nowhere". It is a property of the
124
+ * store, not of the viewer — it does not change with `country`.
125
+ */
126
+ shipping_countries?: string[];
127
+ /**
128
+ * Flat shipping options checkout will offer, in the order the buyer sees
129
+ * them (Stripe preselects the first). Amounts are integers in minor units
130
+ * of THIS response's `currency` — unlike `shipping_countries`, this field
131
+ * DOES vary with `country`: on a localized response the amounts were
132
+ * converted with the same rate as the prices, so render them exactly as
133
+ * returned and never convert them yourself.
134
+ *
135
+ * Absent means show no postage copy at all: the store charges nothing for
136
+ * shipping, this product collects no shipping address, the API predates
137
+ * the field, or (on a localized response) a rate could not convert. Never
138
+ * render undefined as "free shipping" — say nothing instead.
139
+ */
140
+ shipping_rates?: {
141
+ label: string;
142
+ amount: number;
143
+ }[];
144
+ /**
145
+ * Order subtotal (shippable items) at or above which the cheapest rate
146
+ * becomes free. Unlike `shipping_rates`, this does NOT vary with
147
+ * `country`: it is minor units of the SITE's own currency
148
+ * (`base_currency` when the response is localized, else `currency`),
149
+ * because checkout compares the merchant's base-currency subtotal against
150
+ * exactly this number — showing a converted threshold would promise a
151
+ * discount checkout doesn't grant. On a localized page, format it with
152
+ * `base_currency` ("Free shipping over US$50") rather than converting.
153
+ * Present only alongside `shipping_rates`.
154
+ */
155
+ free_shipping_over?: number;
156
+ /** False for deactivated or deleted products — render a disabled buy button. */
157
+ active: boolean;
158
+ /**
159
+ * False exactly when the product has variant rows but none is active (an
160
+ * all-deactivated product) — render a disabled buy button. True for normal
161
+ * and legacy products. Absent on older API responses: treat undefined as
162
+ * true.
163
+ */
164
+ purchasable?: boolean;
165
+ /** Whether the site's Stripe account can currently take payments. */
166
+ payments_ready: boolean;
167
+ /**
168
+ * Option axes for a multi-variant product (empty for single-variant). Feed
169
+ * these plus `variants` to `<VariantPicker>` to resolve a variant id.
170
+ */
171
+ options: PublicOption[];
172
+ /** Active, purchasable variants. Always at least one (the default variant). */
173
+ variants: PublicVariant[];
174
+ }
175
+ interface UseProductOptions {
176
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
177
+ apiUrl?: string;
178
+ /**
179
+ * Buyer-declared market country (ISO 3166-1 alpha-2) — pass `useMarket()`'s
180
+ * `market` to display prices in the buyer's chosen currency. Omitted/null:
181
+ * the site's own currency (the default; prices are never auto-converted by
182
+ * geography). When set and the product supports that market, amounts come
183
+ * back converted with `base_currency` set.
184
+ */
185
+ country?: string | null;
186
+ }
187
+ interface UseProductResult {
188
+ product: PublicProduct | null;
189
+ loading: boolean;
190
+ error: string | null;
191
+ /** Refetch the product config. */
192
+ refresh: () => void;
193
+ }
194
+ /**
195
+ * Fetches live product config from aifeatures. Render prices and availability
196
+ * from this — never hard-code them — so the page can't drift from what the
197
+ * server will actually charge.
198
+ */
199
+ declare function useProduct(productId: string, options?: UseProductOptions): UseProductResult;
200
+ /**
201
+ * Public API (re-exported from the package index): generated site code that
202
+ * converts a buyer-typed major-unit amount to minor units (tip jars, custom
203
+ * checkout controls) must consult this set — multiplying by 100 for a
204
+ * zero-decimal currency charges 100x the typed amount.
205
+ */
206
+ declare const ZERO_DECIMAL_CURRENCIES: Set<string>;
207
+ /**
208
+ * Format a minor-unit amount for display ("$29.00", "¥1,500").
209
+ * Zero-decimal currencies (JPY, KRW, …) pass through; others divide by 100.
210
+ * Uses the browser locale unless one is given. Display only — never feed the
211
+ * result back into money math.
212
+ */
213
+ declare function formatPrice(amount: number, currency: string, locale?: string): string;
214
+
215
+ /**
216
+ * Pure helpers for resolving an option-value selection to a concrete variant.
217
+ * Buyer-facing, plain data in / data out — no fetching, no SDK.
218
+ *
219
+ * A "selection" maps optionId → valueId. A variant is identified by its
220
+ * `option_values` coordinates; all variants of a product cover the same set of
221
+ * options, so a fully-specified selection resolves to at most one variant.
222
+ */
223
+ type VariantSelection = Record<string, string>;
224
+ /** Variants of a product (empty-safe for legacy/cached responses). */
225
+ declare function getVariants(product: PublicProduct): PublicVariant[];
226
+ /** Options of a product (empty-safe). */
227
+ declare function getOptions(product: Pick<PublicProduct, 'options'>): PublicOption[];
228
+ /**
229
+ * True when the product has option axes to choose from (apparel, physical).
230
+ * Single-variant products (downloads, tips, services) are NOT multi-variant
231
+ * and need no picker.
232
+ */
233
+ declare function isMultiVariant(product: PublicProduct): boolean;
234
+ /**
235
+ * Resolve a selection to its variant, or null when the selection is
236
+ * incomplete (not every option chosen) or no such combination exists.
237
+ */
238
+ declare function resolveVariant(variants: PublicVariant[], selection: VariantSelection): PublicVariant | null;
239
+ /**
240
+ * Whether choosing `valueId` for `optionId` yields a real variant given the
241
+ * OTHER currently-selected options — i.e. the combination exists at all.
242
+ * Out-of-stock variants still count as available coordinates (they're shown
243
+ * but blocked at purchase); use `resolveVariant(...).in_stock` for stock.
244
+ */
245
+ declare function isValueAvailable(variants: PublicVariant[], selection: VariantSelection, optionId: string, valueId: string): boolean;
246
+ /**
247
+ * Whether `valueId` for `optionId` appears in ANY variant at all, ignoring the
248
+ * current selection. A value failing this exists on the option axis but on no
249
+ * variant — it's a dead coordinate and should be truly disabled. A value that
250
+ * passes this but fails `isValueAvailable` is merely blocked by the OTHER
251
+ * current picks and should stay clickable (see `reanchorSelection`), or a
252
+ * sparse catalog (e.g. only L/Red and M/Blue) deadlocks the picker.
253
+ */
254
+ declare function isValueInCatalog(variants: PublicVariant[], optionId: string, valueId: string): boolean;
255
+ /**
256
+ * Selection after clicking `valueId` for `optionId`, re-anchoring on the
257
+ * clicked value: every OTHER selected option keeps its value only if some
258
+ * variant pairs it with the clicked value; incompatible picks are cleared for
259
+ * the buyer to re-pick. Clicking an already-compatible value degenerates to a
260
+ * plain merge (nothing is cleared), so this is safe to use for every click.
261
+ *
262
+ * Guarantee: the returned selection is always jointly extendable to a real
263
+ * variant (as long as the clicked value exists on some variant). The pairwise
264
+ * keeps above are checked per option, so on 3+ option axes with a sparse
265
+ * catalog they can each be justified by a DIFFERENT variant while no single
266
+ * variant matches them all — a complete-but-dead selection. When that
267
+ * happens, everything but the clicked value is cleared (deterministic; the
268
+ * buyer re-picks the rest) so the picker can never strand a selection no
269
+ * variant satisfies.
270
+ */
271
+ declare function reanchorSelection(variants: PublicVariant[], selection: VariantSelection, optionId: string, valueId: string): VariantSelection;
272
+ /**
273
+ * Min/max fixed unit_amount across variants (custom-amount variants ignored),
274
+ * or null when no variant has a fixed price. Use to show a price range.
275
+ */
276
+ declare function variantPriceRange(variants: PublicVariant[]): {
277
+ min: number;
278
+ max: number;
279
+ } | null;
280
+ /**
281
+ * The buyer's current picks keyed by option TITLE — `{ Color: 'Black', Size:
282
+ * 'M' }` — from a possibly PARTIAL selection.
283
+ *
284
+ * This is what page code wants whenever the page itself reacts to a pick:
285
+ * swapping the hero image per colour, captioning a swatch, gating copy on a
286
+ * material. It exists to close two traps that both fail silently:
287
+ *
288
+ * - `<VariantPicker>`'s `onVariantChange` fires null until EVERY option is
289
+ * chosen, so keying page state off the resolved variant means a lone
290
+ * "Black" click does nothing on a Colour+Size product. `onChange` fires on
291
+ * every pick — pass its selection here.
292
+ * - A variant's own `option_values` is an ARRAY of `{ option_title, value }`,
293
+ * not an object, so `variant.option_values.Color` is always undefined — and
294
+ * a TypeScript cast makes the compiler agree with the mistake.
295
+ *
296
+ * Unpicked options and unknown ids are simply absent from the result.
297
+ */
298
+ declare function selectedValues(product: Pick<PublicProduct, 'options'>, selection: VariantSelection): Record<string, string>;
299
+ /**
300
+ * URL-safe slug of an option title or value: "Forest Green" → "forest-green".
301
+ * This is the canonical deep-link vocabulary — slugs are derived from the
302
+ * human-readable text (stable across matrix edits that keep the wording),
303
+ * never from ids (which churn when a catalog is rebuilt and would make shared
304
+ * links rot).
305
+ */
306
+ declare function valueSlug(text: string): string;
307
+ /**
308
+ * Rebuild a selection from URL query params — the deep-link entry point, so
309
+ * `/shop?color=black&size=m` opens with Black/M already picked.
310
+ *
311
+ * Params are matched by slug on BOTH sides (key ↔ option title, value ↔ value
312
+ * text), so `?color=forest-green` and `?Color=Forest%20Green` both resolve.
313
+ * Unknown params, unknown values, and unpicked options are simply absent from
314
+ * the result — a stale shared link degrades to "nothing preselected", never an
315
+ * error. Pair with `searchFromSelection` to write the URL on change:
316
+ *
317
+ * const [params, setParams] = useSearchParams();
318
+ * const [selection, setSelection] = useState(() => selectionFromSearch(product, params));
319
+ * // in VariantPicker onChange: setSelection(s); setParams(prev => ({...Object.fromEntries(prev), ...searchFromSelection(product, s)}), { replace: true });
320
+ */
321
+ declare function selectionFromSearch(product: Pick<PublicProduct, 'options'>, search: URLSearchParams | string | Record<string, string>): VariantSelection;
322
+ /**
323
+ * The query params describing a selection — slugged, one `title → value` pair
324
+ * per picked option: `{ color: 'black', size: 'm' }`. Inverse of
325
+ * `selectionFromSearch`. Merge into the existing params rather than replacing
326
+ * them wholesale, so unrelated params (utm_*, etc.) survive.
327
+ */
328
+ declare function searchFromSelection(product: Pick<PublicProduct, 'options'>, selection: VariantSelection): Record<string, string>;
329
+ /**
330
+ * The image gallery for the CURRENT selection — bind the page's product
331
+ * imagery to this and per-colour photos "just work":
332
+ *
333
+ * const images = selectedImages(product, selection); // gallery for the picked colour
334
+ * <img src={images[0]} /> // hero = first image
335
+ *
336
+ * Resolution rule (mirrored by checkout, which shows the same images on the
337
+ * Stripe payment page): every picked value's `images` concatenated in option
338
+ * order; when no picked value carries any — including the nothing-picked-yet
339
+ * initial state — fall back to `product.images`. Works on PARTIAL selections
340
+ * (a lone "Black" click swaps the gallery even before a size is chosen), so
341
+ * drive it from `onChange`'s selection, not from the resolved variant.
342
+ */
343
+ declare function selectedImages(product: Pick<PublicProduct, 'options' | 'images'>, selection: VariantSelection): string[];
344
+ /**
345
+ * Write a selection into the CURRENT URL's query params (replaceState, so the
346
+ * back button isn't spammed by every pick). Every option's param is cleared
347
+ * first, then picked ones are re-set — a pick cleared by re-anchoring
348
+ * disappears from the URL too. Unrelated params (utm_*, …) are untouched, and
349
+ * `history.state` is preserved (react-router keys scroll restoration on it).
350
+ * No-op outside the browser. `<VariantPicker>` calls this on every pick by
351
+ * default (`syncUrl`); it's exported for custom pickers.
352
+ */
353
+ declare function applySelectionToUrl(product: Pick<PublicProduct, 'options'>, selection: VariantSelection): void;
354
+
355
+ interface UseCheckoutOptions {
356
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
357
+ apiUrl?: string;
358
+ }
359
+ interface StartCheckoutOptions {
360
+ productId: string;
361
+ /**
362
+ * The variant to buy. Required for multi-variant products; omit for
363
+ * single-variant products (the server defaults the sole variant).
364
+ */
365
+ variantId?: string;
366
+ /** Defaults to 1. Must be within [1, max_quantity]. */
367
+ quantity?: number;
368
+ /**
369
+ * Total amount in minor units. Only for allow_custom_amount (tip jar)
370
+ * products; the server validates it against [min_amount, max_amount].
371
+ */
372
+ amount?: number;
373
+ /** Opaque passthrough stored on the order (string values only). */
374
+ metadata?: Record<string, string>;
375
+ /** Defaults to `${window.location.origin}/order/confirmation`. */
376
+ successUrl?: string;
377
+ /** Defaults to the current page URL. */
378
+ cancelUrl?: string;
379
+ /** Prefills the email field on the Stripe Checkout page. */
380
+ customerEmail?: string;
381
+ /**
382
+ * The EXACT unit price the page displayed (minor units) — pass it so a
383
+ * price the merchant edited between render and click makes the server
384
+ * refuse with 409 price_changed instead of silently charging a price the
385
+ * buyer never saw. Both `expectedUnitAmount` and `expectedCurrency` or
386
+ * neither; a lone half is not sent. Never pass one for custom-amount (tip
387
+ * jar) buys — the buyer typed the amount, there is no displayed price to
388
+ * defend.
389
+ */
390
+ expectedUnitAmount?: number;
391
+ /**
392
+ * Lowercase ISO currency code of `expectedUnitAmount` (the wire format the
393
+ * product API returns prices in) — see `expectedUnitAmount`.
394
+ */
395
+ expectedCurrency?: string;
396
+ }
397
+ interface UseCheckoutResult {
398
+ /**
399
+ * Starts a Stripe Checkout session and redirects the buyer to it.
400
+ * On failure, the server's error message lands in `error` (no throw).
401
+ */
402
+ startCheckout: (options: StartCheckoutOptions) => Promise<void>;
403
+ loading: boolean;
404
+ error: string | null;
405
+ /**
406
+ * Set when the last attempt was refused because the server-computed price
407
+ * no longer matched the passed expectation (409 price_changed): the
408
+ * per-unit price checkout would charge NOW. Null when the last attempt
409
+ * didn't conflict; cleared at the start of the next attempt. `error` also
410
+ * carries a buyer-readable message naming the new price — this is the
411
+ * structured form for callers that want to react (BuyButton refreshes the
412
+ * product so the displayed price catches up), mirroring useCartCheckout's
413
+ * `conflicts`.
414
+ */
415
+ priceChange: {
416
+ currentUnitAmount: number;
417
+ currency: string;
418
+ } | null;
419
+ }
420
+ /**
421
+ * Starts hosted Stripe Checkout for an aifeatures product. Amounts are
422
+ * server-authoritative — the only client-sent amount is the explicit
423
+ * custom-amount (tip jar) case, which the server re-validates.
424
+ */
425
+ declare function useCheckout(options?: UseCheckoutOptions): UseCheckoutResult;
426
+
427
+ /** Display snapshot captured at add time and refreshed on every successful
428
+ * resolution — the only thing left to render when the product later 404s. */
429
+ interface CartLineDisplay {
430
+ name: string;
431
+ variantTitle: string | null;
432
+ image: string | null;
433
+ }
434
+ /** One cart line. One line per variant; prices are NEVER stored (plan D1). */
435
+ interface CartLine {
436
+ productId: string;
437
+ variantId: string;
438
+ quantity: number;
439
+ /** Variant coordinates at add time — the re-anchor key after a merchant
440
+ * matrix restructure retires the stored variant id. */
441
+ selection: VariantSelection;
442
+ display: CartLineDisplay;
443
+ }
444
+
445
+ /**
446
+ * The cart refuses new DISTINCT lines beyond this (quantity increments on an
447
+ * existing line are always allowed). Mirrors the server's cap:
448
+ * packages/api/src/lib/money.ts MAX_CART_LINES — the checkout route 400s
449
+ * anything longer, so the client refuses first with a machine-readable
450
+ * result the UI can surface.
451
+ */
452
+ declare const MAX_CART_LINES = 20;
453
+ /** What `add` needs — quantity defaults to 1, selection to {} (single-variant
454
+ * products have no coordinates). */
455
+ interface AddCartLineInput {
456
+ productId: string;
457
+ variantId: string;
458
+ quantity?: number;
459
+ selection?: VariantSelection;
460
+ display: CartLineDisplay;
461
+ }
462
+ type AddToCartResult = {
463
+ ok: true;
464
+ } | {
465
+ ok: false;
466
+ reason: 'cart_full';
467
+ };
468
+ interface UseCartResult {
469
+ /** Cart lines — empty until `hydrated` (prerender safety, plan D1). */
470
+ items: CartLine[];
471
+ /** Total units across all lines — the badge number. 0 until hydrated. */
472
+ count: number;
473
+ /**
474
+ * False until a post-mount effect has read storage. Prerendered HTML
475
+ * always shows an empty cart; gate badges and drawers on this so the
476
+ * server-rendered markup can't mismatch the client.
477
+ */
478
+ hydrated: boolean;
479
+ /**
480
+ * Add a line. Merges by variantId (existing line's quantity increments and
481
+ * its selection/display refresh); a NEW line beyond MAX_CART_LINES distinct
482
+ * lines is refused with `{ ok: false, reason: 'cart_full' }`.
483
+ */
484
+ add: (line: AddCartLineInput) => AddToCartResult;
485
+ /** Remove the line for a variant (no-op when absent). */
486
+ remove: (variantId: string) => void;
487
+ /**
488
+ * Set a line's quantity. 0 (or less) REMOVES the line — canonical stepper
489
+ * behavior; other values clamp to a positive integer.
490
+ */
491
+ setQuantity: (variantId: string, quantity: number) => void;
492
+ /** Empty the cart. */
493
+ clear: () => void;
494
+ }
495
+ /**
496
+ * Client-side cart state (plan D1): origin-scoped localStorage (one origin =
497
+ * one site), with an in-memory fallback when storage is unavailable, synced
498
+ * across tabs and components. Prices are NEVER stored — display prices come
499
+ * from live reads (`useCartItems`) and checkout reconciles server-side.
500
+ *
501
+ * Mutations read the LATEST stored cart (not this hook's render state), so
502
+ * two components in the SAME tab never clobber each other. Across tabs the
503
+ * guarantee is narrower: each mutation is still a read-modify-write of the
504
+ * whole array, so two tabs mutating in the same instant race and the last
505
+ * write wins — the same small window the useCartItems merge write-back has.
506
+ */
507
+ declare function useCart(): UseCartResult;
508
+
509
+ /**
510
+ * Per-line resolution status:
511
+ * - `ok` — variant resolved against live data (also the optimistic
512
+ * default while the first resolution pass is still loading).
513
+ * - `reanchored` — the stored variant id was stale but the same option
514
+ * coordinates found an active variant; the swap has been
515
+ * persisted. INFORMATIONAL — render a one-line notice.
516
+ * - `unavailable`— the product 404s, is inactive, or the coordinates no
517
+ * longer exist. Rendered from the `display` snapshot;
518
+ * persists until the buyer removes it (checkout would 409).
519
+ * - `error` — a TRANSIENT fetch failure. Retryable (see `refresh`),
520
+ * never auto-pruned, and does NOT block checkout — the
521
+ * server is the authority.
522
+ */
523
+ type CartLineStatus = 'ok' | 'reanchored' | 'unavailable' | 'error';
524
+ /** A cart line enriched with live, display-ready commerce data. */
525
+ interface CartItemLine extends CartLine {
526
+ /** Image for the line's selection (selectedImages rule: picked values'
527
+ * images, else product images), falling back to the stored snapshot. */
528
+ image: string | null;
529
+ /** Current per-unit price in `currency` minor units; null when the line
530
+ * has no live resolution (unavailable/error/still loading). */
531
+ unitAmount: number | null;
532
+ currency: string | null;
533
+ /** The merchant's own currency when the price was localized for the chosen
534
+ * market; null for a native (site-currency) price. */
535
+ baseCurrency: string | null;
536
+ inStock: boolean;
537
+ /** Units remaining when tracked; null when unlimited. Advisory display
538
+ * only — checkout and the webhook commit are the authorities. */
539
+ available: number | null;
540
+ maxQuantity: number | null;
541
+ /** Query params (from searchFromSelection) deep-linking the PDP with this
542
+ * line's options preselected. */
543
+ pdpSearch: Record<string, string>;
544
+ status: CartLineStatus;
545
+ }
546
+ interface UseCartItemsOptions {
547
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
548
+ apiUrl?: string;
549
+ }
550
+ interface UseCartItemsResult {
551
+ lines: CartItemLine[];
552
+ /** Sum of unitAmount × quantity over resolved lines, in `currency`. */
553
+ subtotal: number;
554
+ /** The (uniform) currency of the resolved lines; null with none resolved. */
555
+ currency: string | null;
556
+ /**
557
+ * ORDER-LEVEL flat shipping options checkout will offer for this cart —
558
+ * the first non-null `shipping_rates` from any resolved line's product.
559
+ * Rates are a SITE-level fact surfaced per product, so every product that
560
+ * carries them carries the same values; "first" is a tiebreak, not a
561
+ * choice. Amounts are minor units of the cart's display currency
562
+ * (localized the same way as the line prices). Null when no resolved
563
+ * product carries rates — render no postage copy, never "free shipping".
564
+ */
565
+ shippingRates: {
566
+ label: string;
567
+ amount: number;
568
+ }[] | null;
569
+ /**
570
+ * ORDER-LEVEL free-shipping threshold — first non-null
571
+ * `free_shipping_over` from any resolved line's product (site-level, same
572
+ * agreement rule as `shippingRates`). Minor units of the SITE's own base
573
+ * currency, deliberately NOT localized: checkout compares the
574
+ * base-currency subtotal against exactly this number (see
575
+ * PublicProduct.free_shipping_over). Null when no threshold is set.
576
+ */
577
+ freeShippingOver: number | null;
578
+ /**
579
+ * ORDER-LEVEL shipping reach — the first non-null `shipping_countries` from
580
+ * any resolved line's product, as uppercase ISO country codes (site-level,
581
+ * same agreement rule as `shippingRates`). A buyer whose delivery address is
582
+ * outside this list cannot complete checkout AT ALL, so a restricted store
583
+ * should say so on the cart page before the buyer reaches Stripe.
584
+ *
585
+ * Scanned across every line rather than read off one, because
586
+ * `shipping_countries` rides only on products that COLLECT an address:
587
+ * reading it from `lines[0]` renders nothing on a cart whose first item is a
588
+ * download, while checkout still enforces the restriction for the shirt
589
+ * behind it (one shippable line makes the whole order shippable).
590
+ *
591
+ * Null when no resolved product carries a restriction — either the store
592
+ * ships anywhere Stripe serves, or nothing in this cart ships. Render
593
+ * nothing in both cases, and NEVER read null as "ships nowhere".
594
+ */
595
+ shippingCountries: string[] | null;
596
+ /** True while a resolution pass is running. */
597
+ loading: boolean;
598
+ /** Set when some product reads failed transiently (lines marked `error`). */
599
+ error: string | null;
600
+ /** Re-run the resolution pass (retries `error` lines). */
601
+ refresh: () => void;
602
+ }
603
+ /**
604
+ * Display-ready cart lines (plan D6): fetches each DISTINCT product once per
605
+ * resolution pass (threading the chosen market's country), re-anchors stale
606
+ * variant ids from their stored option coordinates (persisting the swap —
607
+ * merging quantities if the target id already has a line), refreshes the
608
+ * stored display snapshots, and returns lines enriched with live price,
609
+ * stock, image, and deep-link data.
610
+ *
611
+ * Localization divergence self-heals (plan D8): when SOME products localized
612
+ * for the chosen market and others declined, the whole cart is re-resolved
613
+ * with no country (site currency) so display is uniform — matching the
614
+ * uniform-outcome rule checkout applies to the charge.
615
+ */
616
+ declare function useCartItems(options?: UseCartItemsOptions): UseCartItemsResult;
617
+
618
+ /** One postage option exactly as Stripe will offer it. */
619
+ interface CartSummaryShippingOption {
620
+ label: string;
621
+ /** What this option costs, free-shipping threshold already applied. */
622
+ amount: number;
623
+ /**
624
+ * What it would have cost WITHOUT the threshold. Equal to `amount` unless
625
+ * this option was waived — the pair is what lets a cart strike through the
626
+ * postage it just saved instead of showing a bare "Free".
627
+ */
628
+ undiscountedAmount: number;
629
+ }
630
+ interface CartSummaryShipping {
631
+ options: CartSummaryShippingOption[];
632
+ /** The amount included in `total` — the selected option, or the default. */
633
+ selectedAmount: number;
634
+ /**
635
+ * Which option `total` assumes. Null ONLY when the selection you passed no
636
+ * longer exists: clear your stored choice and make the buyer pick again,
637
+ * before checkout answers the same label with a 409.
638
+ */
639
+ selectedLabel: string | null;
640
+ /** Threshold in minor units of `freeShippingCurrency`, or null when unset. */
641
+ freeShippingOver: number | null;
642
+ /**
643
+ * The denomination of `freeShippingOver` — the SITE's base currency,
644
+ * deliberately not localized, because that is what checkout compares.
645
+ */
646
+ freeShippingCurrency: string;
647
+ /**
648
+ * Whether THIS cart cleared the threshold. Decided server-side, over the
649
+ * lines that actually ship, in base currency. Never recompute it in page
650
+ * code: the browser can see neither the per-line shipping flag nor the base
651
+ * amounts, so any local comparison promises what checkout will not honor.
652
+ */
653
+ thresholdMet: boolean;
654
+ collectsAddress: boolean;
655
+ }
656
+ /**
657
+ * How tax behaves for this store's checkout (Stripe Tax). Null when the store
658
+ * does not run Stripe Tax.
659
+ * - 'included': prices already contain tax; totals here are final in that
660
+ * respect and Stripe itemizes the included tax on its checkout page.
661
+ * - 'added_at_checkout': prices are pre-tax; Stripe ADDS tax on its checkout
662
+ * page after the buyer enters their address. `totalIsFinal` is false, and
663
+ * the page must never estimate the amount — render a note like
664
+ * "Taxes will be shown on the checkout page, if any."
665
+ */
666
+ type CartSummaryTax = {
667
+ mode: "included" | "added_at_checkout";
668
+ };
669
+ interface CartSummary {
670
+ /** Denomination of every amount here. Null only when nothing resolved. */
671
+ currency: string | null;
672
+ /** Line items only, minor units. Excludes postage. */
673
+ subtotal: number;
674
+ /** Null when no postage rides on this cart — render NO shipping row. */
675
+ shipping: CartSummaryShipping | null;
676
+ /** `subtotal + shipping.selectedAmount`. */
677
+ total: number;
678
+ /**
679
+ * True when `total` cannot change at Stripe. When FALSE the buyer can still
680
+ * pick a dearer option, so the page must label this number "Subtotal" —
681
+ * a "Total" with postage still payable is the concealment case.
682
+ */
683
+ totalIsFinal: boolean;
684
+ /** Lines that no longer resolve; excluded from every amount above. */
685
+ unavailableVariantIds: string[];
686
+ /** Stripe Tax display contract — see CartSummaryTax. Null = no Stripe Tax. */
687
+ tax: CartSummaryTax | null;
688
+ }
689
+ interface UseCartSummaryOptions {
690
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
691
+ apiUrl?: string;
692
+ /**
693
+ * Milliseconds to wait after a cart change before pricing it. Quantity
694
+ * steppers fire in bursts; without this each click is a request.
695
+ */
696
+ debounceMs?: number;
697
+ /**
698
+ * The postage option the buyer picked, by label. The total is priced for it
699
+ * and `totalIsFinal` becomes true — checkout sends only this option, so
700
+ * Stripe has nothing to change. Pass the SAME label to `startCheckout`.
701
+ */
702
+ shippingOption?: string | null;
703
+ }
704
+ interface UseCartSummaryResult {
705
+ /** Null until the first successful pass, and on an empty cart. */
706
+ summary: CartSummary | null;
707
+ loading: boolean;
708
+ /** Transient failure text. The last good `summary` is KEPT alongside it. */
709
+ error: string | null;
710
+ refresh: () => void;
711
+ }
712
+ /**
713
+ * The cart's money, priced by the server that will charge it.
714
+ *
715
+ * Every amount here — subtotal, each postage option, whether free shipping
716
+ * applied, the total — comes from the same code path checkout runs, so the
717
+ * number beside the button is the number taken after it. Page code renders
718
+ * these fields; it must never compute them. In particular the free-shipping
719
+ * threshold CANNOT be evaluated in the browser: checkout compares the
720
+ * base-currency subtotal of the lines that SHIP, and the cart knows neither.
721
+ *
722
+ * Two accepted drifts, both display-only: a near-cap order may lose an option
723
+ * at checkout that this listed, and the FX quote is pinned per day, so a cart
724
+ * rendered before a rollover reprices after it.
725
+ *
726
+ * Prices are never read from storage (plan D1) — an empty or unhydrated cart
727
+ * returns `null`, not a stale total.
728
+ */
729
+ declare function useCartSummary(options?: UseCartSummaryOptions): UseCartSummaryResult;
730
+
731
+ interface UseCartCheckoutOptions {
732
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
733
+ apiUrl?: string;
734
+ }
735
+ /**
736
+ * One line of the cart to check out — structurally satisfied by
737
+ * `useCartItems`' lines, which is what you should pass: their `unitAmount` /
738
+ * `currency` become the per-line price expectations the server reconciles
739
+ * against. Lines without a current resolution (null price) POST without
740
+ * expectations — the server stays authoritative either way.
741
+ */
742
+ interface CartCheckoutLine {
743
+ productId: string;
744
+ variantId: string;
745
+ quantity: number;
746
+ unitAmount?: number | null;
747
+ currency?: string | null;
748
+ }
749
+ interface StartCartCheckoutOptions {
750
+ /** Defaults to `${window.location.origin}/order/confirmation`. */
751
+ successUrl?: string;
752
+ /** Defaults to the current page URL. */
753
+ cancelUrl?: string;
754
+ /** Prefills the email field on the Stripe Checkout page. */
755
+ customerEmail?: string;
756
+ /** Opaque passthrough stored on the order (string values only). */
757
+ metadata?: Record<string, string>;
758
+ /**
759
+ * The postage option the buyer chose in the cart, by label — the SAME label
760
+ * passed to `useCartSummary({ shippingOption })`. Only that option is sent
761
+ * to Stripe, so its page shows a fixed shipping cost with nothing to change
762
+ * and the total the cart displayed is the total charged. Omit to send every
763
+ * option and let Stripe preselect the first.
764
+ */
765
+ shippingOption?: string;
766
+ }
767
+ /** One conflicted line of a 409 cart_conflict response, as returned by the
768
+ * server (wire shape — see POST /v1/p/checkout). */
769
+ /**
770
+ * The buyer's chosen postage no longer exists — the merchant changed rates
771
+ * while this cart sat open. Not a per-line conflict: nothing about the ITEMS
772
+ * is wrong, and it is resolved by choosing again from `available`.
773
+ */
774
+ interface ShippingOptionConflict {
775
+ requested: string;
776
+ available: {
777
+ label: string;
778
+ amount: number;
779
+ }[];
780
+ currency: string;
781
+ }
782
+ interface CartConflictItem {
783
+ variant_id: string;
784
+ code: 'unavailable' | 'insufficient_stock' | 'price_changed' | 'quantity_exceeds_max';
785
+ /** insufficient_stock only: units currently available. */
786
+ available?: number;
787
+ /** price_changed only: the per-unit price checkout would charge NOW. */
788
+ current_unit_amount?: number;
789
+ /** price_changed only: the currency checkout would charge NOW. */
790
+ currency?: string;
791
+ /** quantity_exceeds_max only: the largest accepted quantity. */
792
+ max_quantity?: number;
793
+ }
794
+ interface UseCartCheckoutResult {
795
+ /**
796
+ * Starts a multi-item Stripe Checkout session for the given lines (pass
797
+ * `useCartItems().lines`) and redirects the buyer to it. On a 409 the
798
+ * per-line conflicts land in `conflicts`; other failures land in `error`.
799
+ * Never throws.
800
+ */
801
+ startCheckout: (items: CartCheckoutLine[], options?: StartCartCheckoutOptions) => Promise<void>;
802
+ loading: boolean;
803
+ error: string | null;
804
+ /**
805
+ * The last attempt's cart_conflict items keyed by variant_id — EVERY
806
+ * currently-known conflict in one batch. Null when the last attempt didn't
807
+ * conflict; cleared at the start of the next attempt. Resolve the listed
808
+ * lines (the per-line UX is the site's job), then retry.
809
+ */
810
+ conflicts: Record<string, CartConflictItem> | null;
811
+ /**
812
+ * Set when the last attempt was refused because the buyer's selected postage
813
+ * is gone. Clear the stored selection, render `available`, and let them pick
814
+ * again — never silently substitute a rate they did not choose.
815
+ */
816
+ shippingConflict: ShippingOptionConflict | null;
817
+ }
818
+ /**
819
+ * Multi-item checkout for the cart (plan D6): POSTs /v1/p/checkout with the
820
+ * lines' current price expectations and the chosen market's country, then
821
+ * redirects to Stripe. Mirrors `useCheckout`'s hardening verbatim:
822
+ * synchronous in-flight guard, bfcache repair, framed redirect ladder, and
823
+ * the editor test-checkout handoff (nonce-correlated).
824
+ */
825
+ declare function useCartCheckout(options?: UseCartCheckoutOptions): UseCartCheckoutResult;
826
+
827
+ /** A supported market: a country the buyer can shop "as", and the currency
828
+ * that choice displays and charges in. */
829
+ interface MarketCountry {
830
+ /** ISO 3166-1 alpha-2, uppercase. */
831
+ country: string;
832
+ /** Lowercase ISO 4217 — the currency this market localizes into. */
833
+ currency: string;
834
+ }
835
+ /**
836
+ * The supported markets (plan D8) — the fixed list of countries the API will
837
+ * localize for. MIRROR: packages/api/src/lib/fx.ts COUNTRY_TO_CURRENCY is the
838
+ * SOURCE OF TRUTH — keep this list entry-identical to the server's map (same
839
+ * convention as ZERO_DECIMAL_CURRENCIES in useProduct). A country the server
840
+ * doesn't support is simply ignored (site currency), so drift degrades
841
+ * gracefully, but the picker should not offer dead choices.
842
+ */
843
+ declare const MARKET_COUNTRIES: readonly MarketCountry[];
844
+ interface UseMarketOptions {
845
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
846
+ apiUrl?: string;
847
+ }
848
+ interface UseMarketResult {
849
+ /**
850
+ * The buyer's chosen market country, or null when none is chosen — the
851
+ * default, which displays and charges the site's own currency (plan D8:
852
+ * explicit markets, never auto-convert). Null until hydrated.
853
+ */
854
+ market: string | null;
855
+ /** The visitor's country per GET /v1/geo — a SUGGESTION for the market
856
+ * prompt, never applied automatically. Null until loaded / unknown. */
857
+ suggestedCountry: string | null;
858
+ /** Choose a market (persisted, synced across tabs); null returns to the
859
+ * site's own currency. */
860
+ setMarket: (country: string | null) => void;
861
+ /** The supported markets, for rendering the picker. */
862
+ markets: readonly MarketCountry[];
863
+ /**
864
+ * True when the visitor's geo maps to a supported currency different from
865
+ * the active market's — the "shop in your local currency?" prompt trigger.
866
+ * With no market chosen the client can't know the SITE's currency, so the
867
+ * prompt may also fire for a visitor already in the site's currency; the
868
+ * modal copy stays honest either way ("confirm your location"), and a
869
+ * dismissal is the modal's own state to keep.
870
+ */
871
+ shouldPrompt: boolean;
872
+ }
873
+ /**
874
+ * The buyer's market choice (plan D8). The site defaults to its own currency
875
+ * for every visitor worldwide; conversion happens only when the buyer
876
+ * explicitly chooses a market — persisted beside the cart and threaded
877
+ * through product reads and checkout by `useCartItems`/`useCartCheckout`
878
+ * (pass it to `useProduct`'s `country` option for PDPs).
879
+ */
880
+ declare function useMarket(options?: UseMarketOptions): UseMarketResult;
881
+
882
+ interface ProductPriceProps {
883
+ /** Product ID from aifeatures */
884
+ productId: string;
885
+ /**
886
+ * Show this specific variant's price (with its markdown), instead of the
887
+ * product-level price/range. Pass the id resolved by `<VariantPicker>` so
888
+ * the price tracks the buyer's selection.
889
+ */
890
+ variantId?: string;
891
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
892
+ apiUrl?: string;
893
+ /** Optional BCP 47 locale for formatting (defaults to the browser locale) */
894
+ locale?: string;
895
+ className?: string;
896
+ style?: CSSProperties;
897
+ /** Class for the struck-through compare-at ("was") price. */
898
+ compareAtClassName?: string;
899
+ }
900
+ /**
901
+ * Renders a product's live price, formatted for its currency ("$29.00",
902
+ * "¥1,500"). Always use this instead of a hard-coded price literal — the
903
+ * price shown then can't drift from what checkout will actually charge.
904
+ *
905
+ * - Single-variant product: one price, with a struck-through compare-at when
906
+ * the variant is marked down.
907
+ * - Multi-variant product with no `variantId`: a range ("$25 – $40"), or a
908
+ * single price when every variant costs the same.
909
+ * - With `variantId`: that variant's price (+ its compare-at).
910
+ *
911
+ * Renders nothing while loading, on error, or for custom-amount products
912
+ * (which have no fixed price).
913
+ */
914
+ declare function ProductPrice({ productId, variantId, apiUrl, locale, className, style, compareAtClassName, }: ProductPriceProps): react_jsx_runtime.JSX.Element | null;
915
+
916
+ interface VariantPickerProps {
917
+ /** The product's option axes (from `useProduct` / GET /v1/p/:id). */
918
+ options: PublicOption[];
919
+ /** The product's active variants. */
920
+ variants: PublicVariant[];
921
+ /** Controlled selection (optionId → valueId). Omit for uncontrolled. */
922
+ value?: VariantSelection;
923
+ /**
924
+ * Deep-link the selection through the URL's query params (default true, in
925
+ * uncontrolled mode): on mount, `?color=black&size=m` preselects Black/M
926
+ * (slug-matched against option titles/values, so shared links survive
927
+ * catalog edits that keep the wording); every pick rewrites the params via
928
+ * replaceState (back button unaffected, unrelated params untouched). In
929
+ * CONTROLLED mode (`value` given) the parent owns selection state and this
930
+ * prop is ignored — wire `selectionFromSearch`/`applySelectionToUrl`
931
+ * yourself.
932
+ */
933
+ syncUrl?: boolean;
934
+ /** Fires on every selection change with the full optionId → valueId map. */
935
+ onChange?: (selection: VariantSelection) => void;
936
+ /**
937
+ * Fires with the resolved variant whenever the selection resolves to one,
938
+ * or null while the selection is incomplete / an impossible combination.
939
+ * This is how the parent gets the `variantId` for `<BuyButton>`.
940
+ */
941
+ onVariantChange?: (variant: PublicVariant | null) => void;
942
+ className?: string;
943
+ style?: CSSProperties;
944
+ /** Class for each option group (label + its values). */
945
+ optionClassName?: string;
946
+ /** Class for the option title label. */
947
+ optionLabelClassName?: string;
948
+ /** Class for every value button. */
949
+ valueClassName?: string;
950
+ /** Class added to the currently selected value button. */
951
+ selectedValueClassName?: string;
952
+ /**
953
+ * Class added to values with no variant under the current other selections.
954
+ * Most of these stay clickable (clicking re-anchors the selection around
955
+ * them); only values in no variant at all are also `disabled`.
956
+ */
957
+ unavailableValueClassName?: string;
958
+ }
959
+ /**
960
+ * Renders one selector per product option (Size, Color…) and resolves the
961
+ * chosen combination to a concrete variant, handing the parent the resolved
962
+ * variant via `onVariantChange`.
963
+ *
964
+ * - Combinations blocked by the other picks (no variant at that coordinate,
965
+ * but the value exists on some variant) are greyed yet stay clickable —
966
+ * clicking re-anchors: incompatible other picks are cleared for re-picking.
967
+ * Without this, a sparse catalog (only L/Red and M/Blue) would deadlock the
968
+ * picker after the first full selection. Only values in no variant at all
969
+ * are truly disabled.
970
+ * - Out-of-stock variants stay selectable (so the buyer sees the option) but
971
+ * surface `in_stock: false` on the resolved variant — `<BuyButton>` blocks
972
+ * the actual purchase.
973
+ * - A single-variant product (no options) renders nothing — there's nothing to
974
+ * choose; use `<BuyButton productId>` directly.
975
+ *
976
+ * Unstyled-first: pass the *ClassName props (or target the data-selected /
977
+ * data-available attributes) to match the site's design.
978
+ */
979
+ declare function VariantPicker({ options, variants, value, syncUrl, onChange, onVariantChange, className, style, optionClassName, optionLabelClassName, valueClassName, selectedValueClassName, unavailableValueClassName, }: VariantPickerProps): react_jsx_runtime.JSX.Element | null;
980
+
981
+ interface BuyButtonProps {
982
+ /** Product ID from aifeatures */
983
+ productId: string;
984
+ /**
985
+ * The variant to buy. Required for multi-variant products (get it from
986
+ * `<VariantPicker onVariantChange>`); the button stays disabled until a
987
+ * variant is chosen and in stock. Omit for single-variant products.
988
+ */
989
+ variantId?: string;
990
+ /** Defaults to 1. Must be within [1, max_quantity]. */
991
+ quantity?: number;
992
+ /** Total amount in minor units — custom-amount (tip jar) products only. */
993
+ amount?: number;
994
+ /** Opaque passthrough stored on the order (string values only). */
995
+ metadata?: Record<string, string>;
996
+ /** Defaults to `${window.location.origin}/order/confirmation`. */
997
+ successUrl?: string;
998
+ /** Defaults to the current page URL. */
999
+ cancelUrl?: string;
1000
+ /** Prefills the email field on the Stripe Checkout page. */
1001
+ customerEmail?: string;
1002
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1003
+ apiUrl?: string;
1004
+ /** Force-disable the button (combined with the automatic disabled states). */
1005
+ disabled?: boolean;
1006
+ /** Class name for the <button> element */
1007
+ className?: string;
1008
+ style?: CSSProperties;
1009
+ /** Class name for the inline error element (rendered after the button) */
1010
+ errorClassName?: string;
1011
+ /**
1012
+ * Show the built-in busy spinner while checkout is starting (default true).
1013
+ * Set false only when the site renders its own busy indicator.
1014
+ */
1015
+ spinner?: boolean;
1016
+ /** Custom label for the ready-to-buy state (default "Buy now"). Disabled-state labels ("Payments not set up", "Out of stock", …) always win — they explain WHY the button is dead. */
1017
+ children?: ReactNode;
1018
+ }
1019
+ /**
1020
+ * A headless buy button: fetches live product config, starts Stripe Checkout
1021
+ * on click, and redirects the buyer to the hosted payment page.
1022
+ *
1023
+ * Automatically disabled while the product loads, when the store can't take
1024
+ * payments yet ("Payments not set up"), when the product is inactive, and
1025
+ * when nothing is purchasable (variant rows exist but all are deactivated).
1026
+ * Checkout errors (e.g. the product was deactivated between page load and
1027
+ * click) render inline after the button with role="alert".
1028
+ *
1029
+ * Unstyled by default — pass className/style to match the site's design.
1030
+ */
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;
1032
+
1033
+ interface AddToCartButtonProps {
1034
+ /** Product ID from aifeatures */
1035
+ productId: string;
1036
+ /**
1037
+ * The variant to add. Required for multi-variant products unless
1038
+ * `selection` is given (get either from `<VariantPicker>`); the button
1039
+ * stays disabled until a variant resolves and is in stock. Omit for
1040
+ * single-variant products.
1041
+ */
1042
+ variantId?: string;
1043
+ /**
1044
+ * The buyer's option picks (from `<VariantPicker onChange>`). Used to
1045
+ * resolve the variant when `variantId` is absent, and stored on the cart
1046
+ * line so it can re-anchor after a merchant matrix restructure. When
1047
+ * omitted, the resolved variant's own coordinates are stored.
1048
+ */
1049
+ selection?: VariantSelection;
1050
+ /** Units to add per click (default 1). */
1051
+ quantity?: number;
1052
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1053
+ apiUrl?: string;
1054
+ /** Force-disable the button (combined with the automatic disabled states). */
1055
+ disabled?: boolean;
1056
+ /** Class name for the <button> element */
1057
+ className?: string;
1058
+ style?: CSSProperties;
1059
+ /** Class name for the inline message element (rendered after the button) */
1060
+ errorClassName?: string;
1061
+ /**
1062
+ * Show the built-in busy spinner while the product loads (default true).
1063
+ * Set false only when the site renders its own busy indicator.
1064
+ */
1065
+ spinner?: boolean;
1066
+ /** Custom label for the ready state (default "Add to cart"). Disabled-state labels ("Out of stock", …) always win — they explain WHY the button is dead. */
1067
+ children?: ReactNode;
1068
+ }
1069
+ /**
1070
+ * A headless add-to-cart button: fetches live product config and pushes a
1071
+ * line into the client-side cart (`useCart`) on click — no network on click,
1072
+ * no checkout; pair with `<CartCheckoutButton>` on the cart surface.
1073
+ *
1074
+ * Automatically disabled while the product loads, when the store can't take
1075
+ * payments, when the product is inactive/unpurchasable, until a variant
1076
+ * resolves, and when the resolved variant is out of stock per the loaded
1077
+ * data (advisory — the cart surface re-checks with fresh data, and checkout
1078
+ * is the authority). Custom-amount (tip jar) products and legacy products
1079
+ * with NO variants are never cart-eligible (plan scope) — the button renders
1080
+ * disabled for them; use `<BuyButton>` instead.
1081
+ *
1082
+ * A full cart (20 distinct lines) surfaces an inline message with
1083
+ * role="alert". Unstyled by default — pass className/style.
1084
+ */
1085
+ declare function AddToCartButton({ productId, variantId, selection, quantity, apiUrl, disabled, className, style, errorClassName, spinner, children, }: AddToCartButtonProps): react_jsx_runtime.JSX.Element;
1086
+
1087
+ interface CartCheckoutButtonProps {
1088
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1089
+ apiUrl?: string;
1090
+ /** Defaults to `${window.location.origin}/order/confirmation`. */
1091
+ successUrl?: string;
1092
+ /** Defaults to the current page URL. */
1093
+ cancelUrl?: string;
1094
+ /** Prefills the email field on the Stripe Checkout page. */
1095
+ customerEmail?: string;
1096
+ /** Opaque passthrough stored on the order (string values only). */
1097
+ metadata?: Record<string, string>;
1098
+ /**
1099
+ * The postage option the buyer chose in the cart, by label — pass the SAME
1100
+ * label the site gave `useCartSummary({ shippingOption })`, so the total the
1101
+ * cart displayed is the total checkout charges. Only that option is sent to
1102
+ * Stripe; omit to send every option and let Stripe preselect the first.
1103
+ */
1104
+ shippingOption?: string;
1105
+ /** Force-disable the button (combined with the automatic disabled states). */
1106
+ disabled?: boolean;
1107
+ /** Class name for the <button> element */
1108
+ className?: string;
1109
+ style?: CSSProperties;
1110
+ /** Class name for the inline error/conflict elements (rendered after the button) */
1111
+ errorClassName?: string;
1112
+ /**
1113
+ * Show the built-in busy spinner while checkout is starting (default true).
1114
+ * Set false only when the site renders its own busy indicator.
1115
+ */
1116
+ spinner?: boolean;
1117
+ /** Custom label for the ready state (default "Checkout"). Disabled-state labels always win — they explain WHY the button is dead. */
1118
+ children?: ReactNode;
1119
+ }
1120
+ /**
1121
+ * A headless checkout button for the cart: resolves the cart's lines
1122
+ * (`useCartItems`) and starts a multi-item Stripe Checkout session
1123
+ * (`useCartCheckout`) on click.
1124
+ *
1125
+ * Disabled iff: not yet hydrated, the cart is empty, any line is
1126
+ * `unavailable` (a known-futile POST — the buyer must remove it first), or a
1127
+ * checkout is already in flight. Lines still loading or in transient `error`
1128
+ * do NOT block — the server is the authority (plan D6).
1129
+ *
1130
+ * A 409 cart_conflict renders a summary with role="alert"; the per-line
1131
+ * conflict UX (highlighting affected cart rows via `useCartCheckout`'s
1132
+ * `conflicts`) is the site's job. Unstyled by default — pass className/style.
1133
+ */
1134
+ declare function CartCheckoutButton({ apiUrl, successUrl, cancelUrl, customerEmail, metadata, shippingOption, disabled, className, style, errorClassName, spinner, children, }: CartCheckoutButtonProps): react_jsx_runtime.JSX.Element;
1135
+
1136
+ type OrderStatus = "pending" | "paid" | "failed" | "expired" | "refunded" | "partially_refunded" | "disputed";
1137
+ interface OrderFulfillment {
1138
+ /** `mixed` only when a cart genuinely combines types (download + redirect). */
1139
+ type: "none" | "download" | "redirect" | "mixed";
1140
+ /** Durable download link — present when exactly one line is downloadable. */
1141
+ download_url?: string;
1142
+ /** Merchant redirect target — present for paid redirect-type orders. */
1143
+ redirect_url?: string;
1144
+ /**
1145
+ * Per-file download links — present instead of `download_url` when a cart
1146
+ * order has more than one downloadable line.
1147
+ */
1148
+ files?: Array<{
1149
+ name: string;
1150
+ download_url: string;
1151
+ }>;
1152
+ }
1153
+ /** Line item as snapshotted at checkout (display name includes the variant title). */
1154
+ interface OrderSessionLineItem {
1155
+ name: string;
1156
+ quantity: number;
1157
+ /**
1158
+ * The product bought — a stable id for branching the confirmation page per
1159
+ * product type (tip thanks vs download delivery). Absent only on legacy
1160
+ * orders; prefer this over matching on `name`, which changes on rename.
1161
+ */
1162
+ product_id?: string;
1163
+ /**
1164
+ * The variant bought — the cart-clearing key: this page decrements cart
1165
+ * lines by the purchased quantity, keyed by this id. Absent on legacy
1166
+ * no-variant lines.
1167
+ */
1168
+ variant_id?: string;
1169
+ /**
1170
+ * Present (true) only when this line's money was returned in full — the
1171
+ * rest of the order still stands. A refund is NOT evidence the item sold
1172
+ * out; read `refund_reason` before saying anything to the buyer.
1173
+ */
1174
+ refunded?: boolean;
1175
+ /**
1176
+ * Why the line was refunded — sent whenever `refunded` is true.
1177
+ * 'oversold': it lost the stock race at fulfillment and was auto-refunded,
1178
+ * so it was never fulfilled and the buyer also gets an email explaining.
1179
+ * 'merchant': the seller refunded it themselves (a return, goodwill, a
1180
+ * mistake) and the item did not sell out. Absent only from an older API —
1181
+ * treat it as 'merchant', the reading that is true either way.
1182
+ */
1183
+ refund_reason?: "oversold" | "merchant";
1184
+ }
1185
+ /**
1186
+ * Response shape of `GET {apiUrl}/v1/o/session/{sessionId}` (snake_case wire
1187
+ * format). Deliberately carries NO buyer PII (no email/name) — the session id
1188
+ * rides in URLs. The receipt-style fields are optional only because an older
1189
+ * API may omit them; current servers always send them.
1190
+ */
1191
+ interface OrderSession {
1192
+ status: OrderStatus;
1193
+ fulfillment: OrderFulfillment;
1194
+ /** Order reference — the same id the receipt email prints as "Order ID". */
1195
+ order_id?: string;
1196
+ /** True for a simulated owner-initiated test purchase (no money moved). */
1197
+ is_test?: boolean;
1198
+ /**
1199
+ * What the buyer was CHARGED, in minor units of `currency` — goods plus
1200
+ * postage, the number on their card statement. The server composes it, so
1201
+ * "Total paid" below is correct on a shipped order without this component
1202
+ * (or the site embedding it) being rebuilt. Never add `shipping_total` to
1203
+ * it: that postage is already inside.
1204
+ */
1205
+ amount_total?: number;
1206
+ /**
1207
+ * The postage portion of `amount_total`, for pages that want to show a
1208
+ * breakdown row. `0` means postage was offered and came out free (a met
1209
+ * free-shipping threshold) and should read "Free"; `undefined`/`null` means
1210
+ * none was charged or recorded — show no shipping row at all.
1211
+ */
1212
+ shipping_total?: number | null;
1213
+ currency?: string;
1214
+ /** What was bought — a receipt-style summary. */
1215
+ line_items?: OrderSessionLineItem[];
1216
+ }
1217
+ interface OrderConfirmationProps {
1218
+ /** Base URL for the aifeatures API (defaults to https://aifeatures.dev) */
1219
+ apiUrl?: string;
1220
+ /** Class name for the container of the default-rendered states */
1221
+ className?: string;
1222
+ style?: CSSProperties;
1223
+ /**
1224
+ * Override the Stripe Checkout session id. By default it is read from the
1225
+ * `session_id` URL query param (and immediately stripped from the URL).
1226
+ * Mainly for previews/tests.
1227
+ */
1228
+ sessionId?: string;
1229
+ /** Poll interval while the order is pending (default 2000 ms) */
1230
+ pollIntervalMs?: number;
1231
+ /** Give up polling after this long (default 60000 ms) */
1232
+ pollTimeoutMs?: number;
1233
+ /** Automatically follow redirect-type fulfillment (default true) */
1234
+ followRedirect?: boolean;
1235
+ /** Delay before following a fulfillment redirect (default 1500 ms) */
1236
+ redirectDelayMs?: number;
1237
+ /**
1238
+ * Rendered when no session is available: the URL has no session_id (it is
1239
+ * stripped on first render) AND this tab has no recent restorable session.
1240
+ * A refresh or back-navigation within ~30 minutes in the SAME tab restores
1241
+ * the session from sessionStorage and re-renders the live order instead;
1242
+ * a new tab or a later visit lands here (default: a generic "order
1243
+ * confirmed, check your email" message).
1244
+ */
1245
+ renderNoSession?: () => ReactNode;
1246
+ /** Rendered while the payment is being confirmed */
1247
+ renderPending?: (ctx: {
1248
+ timedOut: boolean;
1249
+ }) => ReactNode;
1250
+ /** Rendered once the order is paid (covers download/redirect/plain) */
1251
+ renderPaid?: (session: OrderSession) => ReactNode;
1252
+ /** Rendered for failed/expired (and refunded/disputed) orders */
1253
+ renderFailed?: (session: OrderSession) => ReactNode;
1254
+ }
1255
+ declare function OrderConfirmation({ apiUrl, className, style, sessionId: sessionIdProp, pollIntervalMs, pollTimeoutMs, followRedirect, redirectDelayMs, renderNoSession, renderPending, renderPaid, renderFailed, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element | null;
1256
+
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 };