@aifeatures/react 0.2.0 → 0.3.1

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