@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.cjs +1 -67
- package/dist/index.d.cts +1225 -1
- package/dist/index.d.ts +1225 -1
- package/dist/index.js +1 -41
- package/package.json +2 -2
- package/dist/index.cjs.map +0 -1
- package/dist/index.js.map +0 -1
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,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
|
-
|
|
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 };
|