@aifeatures/admin-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 +3 -1373
- package/dist/index.d.cts +1344 -2
- package/dist/index.d.ts +1344 -2
- package/dist/index.js +3 -1332
- package/dist/styles.css +1 -1
- package/package.json +1 -1
- package/dist/index.cjs.map +0 -1
- package/dist/index.js.map +0 -1
package/dist/index.d.cts
CHANGED
|
@@ -17,12 +17,17 @@ interface Form {
|
|
|
17
17
|
}
|
|
18
18
|
/**
|
|
19
19
|
* Attachment object for form submissions
|
|
20
|
+
*
|
|
21
|
+
* `id` and `field` are absent on submissions created before attachments
|
|
22
|
+
* carried stable ids; download by `id` when present, by `name` otherwise.
|
|
20
23
|
*/
|
|
21
24
|
interface Attachment {
|
|
25
|
+
id?: string;
|
|
22
26
|
name: string;
|
|
23
27
|
size: number;
|
|
24
28
|
r2_key: string;
|
|
25
29
|
content_type: string;
|
|
30
|
+
field?: string;
|
|
26
31
|
}
|
|
27
32
|
/**
|
|
28
33
|
* Submission metadata
|
|
@@ -90,6 +95,744 @@ interface ApiError {
|
|
|
90
95
|
error: string;
|
|
91
96
|
message?: string;
|
|
92
97
|
}
|
|
98
|
+
/**
|
|
99
|
+
* A site's payment readiness (sites.paymentsStatus)
|
|
100
|
+
*/
|
|
101
|
+
type PaymentsStatus = "none" | "pending" | "active" | "disabled";
|
|
102
|
+
/**
|
|
103
|
+
* Why payments are not active. Null when status is active.
|
|
104
|
+
*/
|
|
105
|
+
type PaymentsStatusReason = "needs_stripe" | "needs_paid_plan" | "account_disabled";
|
|
106
|
+
/**
|
|
107
|
+
* Response from GET /api/v1/payments/status
|
|
108
|
+
*/
|
|
109
|
+
interface PaymentsStatusResponse {
|
|
110
|
+
status: PaymentsStatus;
|
|
111
|
+
reason: PaymentsStatusReason | null;
|
|
112
|
+
stripe_account_connected: boolean;
|
|
113
|
+
currency: string;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Product fulfillment as exposed via the management API (no R2 key)
|
|
117
|
+
*/
|
|
118
|
+
type ProductFulfillmentType = "none" | "download" | "redirect";
|
|
119
|
+
interface ProductFulfillment {
|
|
120
|
+
type: ProductFulfillmentType;
|
|
121
|
+
filename: string | null;
|
|
122
|
+
url: string | null;
|
|
123
|
+
content_type: string | null;
|
|
124
|
+
size: number | null;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Price summary derived from a product's ACTIVE variants, present on LIST
|
|
128
|
+
* responses. This is what the flat `unit_amount` cannot tell you: that column
|
|
129
|
+
* is null for every variant-priced product, which is why a card used to read
|
|
130
|
+
* "Varies by variant" and dead-end there.
|
|
131
|
+
*
|
|
132
|
+
* `min_amount === max_amount` means a single price. Both null means nothing is
|
|
133
|
+
* priced at the variant level (a custom-amount product, or one with no active
|
|
134
|
+
* variants) — read the flat `min_amount`/`max_amount` for a tip jar's bounds,
|
|
135
|
+
* which live on the product, not in this summary.
|
|
136
|
+
*/
|
|
137
|
+
interface ProductPricing {
|
|
138
|
+
currency: string | null;
|
|
139
|
+
/** Lowest active-variant price in minor units. */
|
|
140
|
+
min_amount: number | null;
|
|
141
|
+
/** Highest active-variant price in minor units. */
|
|
142
|
+
max_amount: number | null;
|
|
143
|
+
/**
|
|
144
|
+
* Highest markdown reference across active variants — strike it through only
|
|
145
|
+
* when it EXCEEDS the price actually shown.
|
|
146
|
+
*/
|
|
147
|
+
compare_at_amount: number | null;
|
|
148
|
+
/** Buyer names the price (tip jar / pay-what-you-want). */
|
|
149
|
+
custom_amount: boolean;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Stock summary across a product's tracked active variants, present on LIST
|
|
153
|
+
* responses.
|
|
154
|
+
*
|
|
155
|
+
* `tracked: false` with `available: null` means stock is NOT COUNTED — it is
|
|
156
|
+
* not the same fact as "we have none", and the two must never render alike. A
|
|
157
|
+
* "0" against an untracked product is always a lie.
|
|
158
|
+
*
|
|
159
|
+
* `low_stock` / `out_of_stock` are already false when backorders are allowed:
|
|
160
|
+
* the merchant chose to keep selling past zero, so neither is a warning.
|
|
161
|
+
*/
|
|
162
|
+
interface ProductInventory {
|
|
163
|
+
tracked: boolean;
|
|
164
|
+
/** Units available across tracked variants, clamped at 0. Null when untracked. */
|
|
165
|
+
available: number | null;
|
|
166
|
+
allow_backorder: boolean;
|
|
167
|
+
low_stock: boolean;
|
|
168
|
+
out_of_stock: boolean;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Product object from aifeatures API. Amounts are integers in the
|
|
172
|
+
* currency's minor unit (cents for USD).
|
|
173
|
+
*/
|
|
174
|
+
interface Product {
|
|
175
|
+
id: string;
|
|
176
|
+
site_id: string;
|
|
177
|
+
name: string;
|
|
178
|
+
description: string | null;
|
|
179
|
+
images: string[];
|
|
180
|
+
/** Price in minor units. Null for custom-amount (tip jar) products. */
|
|
181
|
+
unit_amount: number | null;
|
|
182
|
+
currency: string;
|
|
183
|
+
type: string;
|
|
184
|
+
/** Tip-jar style: buyer picks the amount within [min_amount, max_amount]. */
|
|
185
|
+
allow_custom_amount: boolean;
|
|
186
|
+
min_amount: number | null;
|
|
187
|
+
max_amount: number | null;
|
|
188
|
+
max_quantity: number;
|
|
189
|
+
fulfillment: ProductFulfillment;
|
|
190
|
+
collect_shipping_address: boolean;
|
|
191
|
+
active: boolean;
|
|
192
|
+
metadata: Record<string, unknown>;
|
|
193
|
+
created_at: string;
|
|
194
|
+
updated_at: string;
|
|
195
|
+
/**
|
|
196
|
+
* Price summary over the active variants. Sent on LIST responses (it is
|
|
197
|
+
* catalog data, not a stats add-on) and absent on create/detail, which carry
|
|
198
|
+
* the whole variant array instead. Optional so an older API deployment — and
|
|
199
|
+
* the create/detail responses — still typecheck; renderers fall back to the
|
|
200
|
+
* flat `unit_amount` when it isn't there.
|
|
201
|
+
*/
|
|
202
|
+
pricing?: ProductPricing;
|
|
203
|
+
/** Stock summary over the active variants. Same presence rules as `pricing`. */
|
|
204
|
+
inventory?: ProductInventory;
|
|
205
|
+
/** Active variants. 1 for a simple product. Same presence rules as `pricing`. */
|
|
206
|
+
variant_count?: number;
|
|
207
|
+
/**
|
|
208
|
+
* Rolling-30-day sales stats. Present ONLY when the list was fetched with
|
|
209
|
+
* `include: 'stats'`; absent otherwise.
|
|
210
|
+
*/
|
|
211
|
+
stats?: ProductStats;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* Rolling-30-day sales stats for one product, present only when the products
|
|
215
|
+
* list was fetched with `include: 'stats'` (owner-side surfaces — editor
|
|
216
|
+
* surfaces never request them).
|
|
217
|
+
*/
|
|
218
|
+
interface ProductStats {
|
|
219
|
+
units_sold: number;
|
|
220
|
+
orders: number;
|
|
221
|
+
/** Gross per presentment currency (minor units) — never sum across entries. */
|
|
222
|
+
gross: Array<{
|
|
223
|
+
currency: string;
|
|
224
|
+
amount: number;
|
|
225
|
+
}>;
|
|
226
|
+
/** Min available across tracked variants is at or below the low-stock threshold. */
|
|
227
|
+
low_stock: boolean;
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Products list response
|
|
231
|
+
*/
|
|
232
|
+
interface ProductsListResponse {
|
|
233
|
+
products: Product[];
|
|
234
|
+
}
|
|
235
|
+
/** Options for fetching products */
|
|
236
|
+
interface GetProductsOptions {
|
|
237
|
+
/** 'stats' attaches rolling-30-day sales stats to each product (owner-side). */
|
|
238
|
+
include?: "stats";
|
|
239
|
+
}
|
|
240
|
+
/** Derived inventory summary for a variant (management view). */
|
|
241
|
+
interface VariantInventory {
|
|
242
|
+
tracked: boolean;
|
|
243
|
+
on_hand: number;
|
|
244
|
+
allow_backorder: boolean;
|
|
245
|
+
/** Units available (on_hand − held reservations). Null when untracked. */
|
|
246
|
+
available: number | null;
|
|
247
|
+
}
|
|
248
|
+
/** A variant's coordinate on the option grid. */
|
|
249
|
+
interface VariantOptionValue {
|
|
250
|
+
option_id: string;
|
|
251
|
+
option_title: string;
|
|
252
|
+
value_id: string;
|
|
253
|
+
value: string;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* A purchasable variant. Pricing and stock live here (the variant is the unit
|
|
257
|
+
* that checkout charges for). Amounts are integers in the currency's minor
|
|
258
|
+
* unit. Single-variant products expose one variant with `title: null` and an
|
|
259
|
+
* empty `option_values`.
|
|
260
|
+
*/
|
|
261
|
+
interface ProductVariant {
|
|
262
|
+
id: string;
|
|
263
|
+
product_id: string;
|
|
264
|
+
title: string | null;
|
|
265
|
+
sku: string | null;
|
|
266
|
+
unit_amount: number | null;
|
|
267
|
+
compare_at_amount: number | null;
|
|
268
|
+
currency: string;
|
|
269
|
+
allow_custom_amount: boolean;
|
|
270
|
+
min_amount: number | null;
|
|
271
|
+
max_amount: number | null;
|
|
272
|
+
position: number;
|
|
273
|
+
active: boolean;
|
|
274
|
+
metadata: Record<string, unknown>;
|
|
275
|
+
option_values: VariantOptionValue[];
|
|
276
|
+
inventory: VariantInventory | null;
|
|
277
|
+
created_at: string;
|
|
278
|
+
updated_at: string;
|
|
279
|
+
}
|
|
280
|
+
/** A product option axis (Size, Color) and its values. */
|
|
281
|
+
interface ProductOption {
|
|
282
|
+
id: string;
|
|
283
|
+
title: string;
|
|
284
|
+
position: number;
|
|
285
|
+
values: Array<{
|
|
286
|
+
id: string;
|
|
287
|
+
value: string;
|
|
288
|
+
position: number;
|
|
289
|
+
}>;
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* The full product detail returned by GET/POST/PATCH /products (the flat
|
|
293
|
+
* product plus its options and variants).
|
|
294
|
+
*/
|
|
295
|
+
interface ProductDetail extends Product {
|
|
296
|
+
options: ProductOption[];
|
|
297
|
+
variants: ProductVariant[];
|
|
298
|
+
}
|
|
299
|
+
/** Input for creating a variant on a product. */
|
|
300
|
+
interface CreateVariantInput {
|
|
301
|
+
title?: string | null;
|
|
302
|
+
sku?: string | null;
|
|
303
|
+
unit_amount?: number;
|
|
304
|
+
compare_at_amount?: number | null;
|
|
305
|
+
allow_custom_amount?: boolean;
|
|
306
|
+
min_amount?: number;
|
|
307
|
+
max_amount?: number;
|
|
308
|
+
position?: number;
|
|
309
|
+
active?: boolean;
|
|
310
|
+
/** Option title → value (e.g. { Size: "L", Color: "Black" }). */
|
|
311
|
+
option_values?: Record<string, string>;
|
|
312
|
+
inventory?: {
|
|
313
|
+
tracked: boolean;
|
|
314
|
+
on_hand?: number;
|
|
315
|
+
allow_backorder?: boolean;
|
|
316
|
+
};
|
|
317
|
+
}
|
|
318
|
+
/** Input for updating a variant (price/markdown/sku/active/position). */
|
|
319
|
+
interface UpdateVariantInput {
|
|
320
|
+
title?: string | null;
|
|
321
|
+
sku?: string | null;
|
|
322
|
+
unit_amount?: number;
|
|
323
|
+
compare_at_amount?: number | null;
|
|
324
|
+
allow_custom_amount?: boolean;
|
|
325
|
+
min_amount?: number;
|
|
326
|
+
max_amount?: number;
|
|
327
|
+
position?: number;
|
|
328
|
+
active?: boolean;
|
|
329
|
+
}
|
|
330
|
+
/** Input for creating an option (Size + its values). */
|
|
331
|
+
interface CreateOptionInput {
|
|
332
|
+
title: string;
|
|
333
|
+
values: string[];
|
|
334
|
+
}
|
|
335
|
+
/** Input for updating an option (rename, add/remove values). */
|
|
336
|
+
interface UpdateOptionInput {
|
|
337
|
+
title?: string;
|
|
338
|
+
add_values?: string[];
|
|
339
|
+
remove_values?: string[];
|
|
340
|
+
}
|
|
341
|
+
/** Input for setting a variant's inventory (upsert semantics). */
|
|
342
|
+
interface SetInventoryInput {
|
|
343
|
+
tracked: boolean;
|
|
344
|
+
on_hand?: number;
|
|
345
|
+
allow_backorder?: boolean;
|
|
346
|
+
}
|
|
347
|
+
/** Input for adjusting a variant's on_hand by a signed delta. */
|
|
348
|
+
interface AdjustInventoryInput {
|
|
349
|
+
delta: number;
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* Input for creating a product
|
|
353
|
+
*/
|
|
354
|
+
interface CreateProductInput {
|
|
355
|
+
name: string;
|
|
356
|
+
description?: string;
|
|
357
|
+
images?: string[];
|
|
358
|
+
unit_amount?: number;
|
|
359
|
+
currency?: string;
|
|
360
|
+
allow_custom_amount?: boolean;
|
|
361
|
+
min_amount?: number;
|
|
362
|
+
max_amount?: number;
|
|
363
|
+
max_quantity?: number;
|
|
364
|
+
fulfillment?: {
|
|
365
|
+
type: "none" | "redirect";
|
|
366
|
+
url?: string;
|
|
367
|
+
};
|
|
368
|
+
collect_shipping_address?: boolean;
|
|
369
|
+
active?: boolean;
|
|
370
|
+
metadata?: Record<string, unknown>;
|
|
371
|
+
}
|
|
372
|
+
/**
|
|
373
|
+
* Input for updating a product
|
|
374
|
+
*/
|
|
375
|
+
interface UpdateProductInput {
|
|
376
|
+
name?: string;
|
|
377
|
+
description?: string | null;
|
|
378
|
+
images?: string[];
|
|
379
|
+
unit_amount?: number | null;
|
|
380
|
+
currency?: string;
|
|
381
|
+
allow_custom_amount?: boolean;
|
|
382
|
+
min_amount?: number | null;
|
|
383
|
+
max_amount?: number | null;
|
|
384
|
+
max_quantity?: number;
|
|
385
|
+
fulfillment?: {
|
|
386
|
+
type: "none" | "redirect";
|
|
387
|
+
url?: string;
|
|
388
|
+
};
|
|
389
|
+
collect_shipping_address?: boolean;
|
|
390
|
+
active?: boolean;
|
|
391
|
+
metadata?: Record<string, unknown>;
|
|
392
|
+
}
|
|
393
|
+
/**
|
|
394
|
+
* An order's lifecycle state
|
|
395
|
+
*/
|
|
396
|
+
type OrderStatus = "pending" | "paid" | "failed" | "expired" | "refunded" | "partially_refunded" | "disputed";
|
|
397
|
+
/**
|
|
398
|
+
* Delivery state of ONE side of an order's emails — the buyer receipt or the
|
|
399
|
+
* merchant sale notification. The two sides are tracked, retried and reported
|
|
400
|
+
* independently (orders.buyer_email_status / orders.merchant_email_status), so
|
|
401
|
+
* there is no scope encoded in the value: the side is the field, not the
|
|
402
|
+
* status. State machine: packages/api/src/lib/fulfillment.ts.
|
|
403
|
+
*
|
|
404
|
+
* none no dispatch has run for this side yet
|
|
405
|
+
* sending a dispatch holds a claim on this side right now
|
|
406
|
+
* sent delivered
|
|
407
|
+
* failed a recorded failure; retried automatically while the order is
|
|
408
|
+
* in a sendable state ('paid' / 'partially_refunded')
|
|
409
|
+
* failed_final terminal — either the retry budget is spent, or there was no
|
|
410
|
+
* address to send to (a missing recipient no retry can invent)
|
|
411
|
+
* suppressed a dispatch ran while the order was refunded/disputed and
|
|
412
|
+
* deliberately sent nothing; it revives by itself once the order
|
|
413
|
+
* is sendable again
|
|
414
|
+
*/
|
|
415
|
+
type EmailSideStatus = "none" | "sending" | "sent" | "failed" | "failed_final" | "suppressed";
|
|
416
|
+
/**
|
|
417
|
+
* A line item snapshot on an order. The wire format is an opaque snapshot
|
|
418
|
+
* taken at checkout time — every field is optional and renderers should keep
|
|
419
|
+
* runtime type guards.
|
|
420
|
+
*/
|
|
421
|
+
interface LineItem {
|
|
422
|
+
productId?: string;
|
|
423
|
+
name?: string;
|
|
424
|
+
/** Which variant was bought (e.g. "Large / Blue") — snapshotted at checkout
|
|
425
|
+
* so the order stays fulfillable even if the variant is later edited or
|
|
426
|
+
* deleted. Absent on no-variant products and on orders that predate
|
|
427
|
+
* variants. */
|
|
428
|
+
variantId?: string;
|
|
429
|
+
variantTitle?: string;
|
|
430
|
+
/** Unit price in the currency's minor unit. */
|
|
431
|
+
unitAmount?: number;
|
|
432
|
+
quantity?: number;
|
|
433
|
+
/**
|
|
434
|
+
* The product image as it looked at checkout, snapshotted onto the line so a
|
|
435
|
+
* later product edit can't change what the order says was bought. Absent on
|
|
436
|
+
* legacy lines and on products that never had an image — renderers show a
|
|
437
|
+
* neutral placeholder tile rather than a broken image.
|
|
438
|
+
*/
|
|
439
|
+
imageUrl?: string;
|
|
440
|
+
/**
|
|
441
|
+
* Whether this line's product collected a shipping address, frozen at
|
|
442
|
+
* checkout. Fulfillment decides refunded postage from it on retries that can
|
|
443
|
+
* land days after the charge, so it deliberately does NOT track the
|
|
444
|
+
* product's current setting — a line here can say `true` for a product that
|
|
445
|
+
* no longer ships. Absent on orders written before the field existed.
|
|
446
|
+
*/
|
|
447
|
+
collectShippingAddress?: boolean;
|
|
448
|
+
/**
|
|
449
|
+
* This line's money has been returned — either an itemized refund named it,
|
|
450
|
+
* or it lost the stock race at fulfillment and was auto-refunded. A line
|
|
451
|
+
* refunds whole or not at all, so this is a marker, not an amount. Absent on
|
|
452
|
+
* every line that has not been refunded.
|
|
453
|
+
*/
|
|
454
|
+
refunded?: boolean;
|
|
455
|
+
/**
|
|
456
|
+
* WHICH of the two it was. 'oversold' = the platform auto-refunded it at
|
|
457
|
+
* fulfillment because the stock ran out — it happened without the merchant
|
|
458
|
+
* and there is nothing to ship; 'merchant' = an itemized refund taken from
|
|
459
|
+
* this dashboard. Absent reads as 'merchant' (the neutral fact), never as
|
|
460
|
+
* 'oversold' — claiming a sell-out that did not happen is the one wrong
|
|
461
|
+
* answer here.
|
|
462
|
+
*/
|
|
463
|
+
refundReason?: "oversold" | "merchant";
|
|
464
|
+
}
|
|
465
|
+
/**
|
|
466
|
+
* Order object from aifeatures API. Amounts are integers in the
|
|
467
|
+
* currency's minor unit.
|
|
468
|
+
*/
|
|
469
|
+
interface Order {
|
|
470
|
+
id: string;
|
|
471
|
+
/**
|
|
472
|
+
* The merchant-facing order number (`#1042`) — a per-site sequence assigned
|
|
473
|
+
* at creation. Null on orders written before the sequence existed; the UI
|
|
474
|
+
* falls back to a short prefix of `id` for those. Optional so older API
|
|
475
|
+
* deployments that omit the field still typecheck.
|
|
476
|
+
*/
|
|
477
|
+
order_number?: number | null;
|
|
478
|
+
site_id: string;
|
|
479
|
+
source: string;
|
|
480
|
+
/**
|
|
481
|
+
* Simulated owner-initiated test purchase (no Stripe, no money). Badged in
|
|
482
|
+
* the UI; refunds on it are simulated server-side. Optional so older API
|
|
483
|
+
* deployments that omit the field still typecheck.
|
|
484
|
+
*/
|
|
485
|
+
is_test?: boolean;
|
|
486
|
+
status: OrderStatus;
|
|
487
|
+
stripe_checkout_session_id: string | null;
|
|
488
|
+
stripe_payment_intent_id: string | null;
|
|
489
|
+
amount_total: number;
|
|
490
|
+
amount_refunded: number;
|
|
491
|
+
/**
|
|
492
|
+
* Postage Stripe charged on top of amount_total (minor units, charge
|
|
493
|
+
* currency); null means "unrecorded" — including every order placed before
|
|
494
|
+
* shipping rates existed. The refund ceiling is
|
|
495
|
+
* amount_total + (shipping_total ?? 0). Optional so older API deployments
|
|
496
|
+
* that omit the fields still typecheck.
|
|
497
|
+
*/
|
|
498
|
+
shipping_total?: number | null;
|
|
499
|
+
/** How much of amount_refunded was postage (minor units; 0 when unknown —
|
|
500
|
+
* a Stripe-dashboard refund cannot be decomposed). */
|
|
501
|
+
shipping_refunded?: number;
|
|
502
|
+
/** Tax on this order (minor units). Under exclusive automatic tax it was charged ON TOP of amount_total + shipping_total; otherwise a non-zero value is already inside them. */
|
|
503
|
+
tax_total?: number;
|
|
504
|
+
/** The tax twin of shipping_refunded — how much of amount_refunded was tax. */
|
|
505
|
+
tax_refunded?: number;
|
|
506
|
+
/** Snapshot of the site's tax behavior for this order. */
|
|
507
|
+
tax_behavior?: "inclusive" | "exclusive" | null;
|
|
508
|
+
/** The checkout session ran with Stripe automatic tax. */
|
|
509
|
+
automatic_tax?: boolean;
|
|
510
|
+
/**
|
|
511
|
+
* What the BUYER was charged in. Localized sales are charged in the buyer's
|
|
512
|
+
* own currency, so one site's order list can mix currencies — never sum
|
|
513
|
+
* amount_total across orders.
|
|
514
|
+
*/
|
|
515
|
+
currency: string;
|
|
516
|
+
/**
|
|
517
|
+
* The merchant's own pricing when the sale was localized (charged in a
|
|
518
|
+
* different currency than the merchant priced in); null otherwise. Optional
|
|
519
|
+
* so older API deployments that omit the fields still typecheck.
|
|
520
|
+
*/
|
|
521
|
+
base_currency?: string | null;
|
|
522
|
+
base_amount_total?: number | null;
|
|
523
|
+
customer_email: string | null;
|
|
524
|
+
customer_name: string | null;
|
|
525
|
+
/**
|
|
526
|
+
* The durable customer linked to this order (null for legacy orders or
|
|
527
|
+
* orders whose buyer was never upserted). The order still snapshots
|
|
528
|
+
* customer_email/name; this is the mutable CRM identity.
|
|
529
|
+
*/
|
|
530
|
+
customer: {
|
|
531
|
+
id: string;
|
|
532
|
+
email: string;
|
|
533
|
+
name: string | null;
|
|
534
|
+
} | null;
|
|
535
|
+
shipping_address: Record<string, unknown> | null;
|
|
536
|
+
line_items: LineItem[];
|
|
537
|
+
metadata: Record<string, unknown>;
|
|
538
|
+
fulfillment_status: string;
|
|
539
|
+
fulfillment_type: ProductFulfillmentType | null;
|
|
540
|
+
download_url: string | null;
|
|
541
|
+
download_count: number;
|
|
542
|
+
download_expires_at: string | null;
|
|
543
|
+
/**
|
|
544
|
+
* Per-side email delivery state. These replaced a single fused
|
|
545
|
+
* `email_delivery_status` whose value encoded BOTH the state and which side
|
|
546
|
+
* it applied to; the buyer receipt and the merchant sale notification are
|
|
547
|
+
* independent deliveries with independent recovery, so read each side's own
|
|
548
|
+
* field and never infer one from the other.
|
|
549
|
+
*/
|
|
550
|
+
buyer_email_status: EmailSideStatus;
|
|
551
|
+
merchant_email_status: EmailSideStatus;
|
|
552
|
+
/**
|
|
553
|
+
* Dispatch attempts spent on each side, against the API's per-side retry
|
|
554
|
+
* budget (24). Meaningful next to a 'failed' status: 1 attempt spent and 23
|
|
555
|
+
* spent are the same status but very different situations.
|
|
556
|
+
*/
|
|
557
|
+
buyer_email_attempts: number;
|
|
558
|
+
merchant_email_attempts: number;
|
|
559
|
+
paid_at: string | null;
|
|
560
|
+
refunded_at: string | null;
|
|
561
|
+
/**
|
|
562
|
+
* When the merchant marked this order done (shipped/handled) from the
|
|
563
|
+
* merchant view. Null = not marked. This is a merchant bookkeeping flag —
|
|
564
|
+
* it never changes the money or fulfillment pipeline state. Optional so
|
|
565
|
+
* older API deployments that omit the field still typecheck.
|
|
566
|
+
*/
|
|
567
|
+
merchant_fulfilled_at?: string | null;
|
|
568
|
+
/**
|
|
569
|
+
* Tracking number the merchant recorded at mark-done. Merchant-view-only in
|
|
570
|
+
* v1 (never flows into buyer-facing email). Charset-bound server-side to
|
|
571
|
+
* letters, digits, spaces, `-` and `_`, max 100 chars.
|
|
572
|
+
*/
|
|
573
|
+
tracking_number?: string | null;
|
|
574
|
+
created_at: string;
|
|
575
|
+
updated_at: string;
|
|
576
|
+
}
|
|
577
|
+
/**
|
|
578
|
+
* Paginated orders response
|
|
579
|
+
*/
|
|
580
|
+
interface PaginatedOrders {
|
|
581
|
+
orders: Order[];
|
|
582
|
+
total: number;
|
|
583
|
+
limit: number;
|
|
584
|
+
offset: number;
|
|
585
|
+
}
|
|
586
|
+
/**
|
|
587
|
+
* Options for fetching orders
|
|
588
|
+
*/
|
|
589
|
+
interface GetOrdersOptions {
|
|
590
|
+
status?: OrderStatus;
|
|
591
|
+
/**
|
|
592
|
+
* Statuses to omit. Used to keep abandoned checkouts
|
|
593
|
+
* (`pending` → swept to `expired`) out of the default order view — neither
|
|
594
|
+
* is a sale, and "Pending" reads as "money on the way". Ignored by the API
|
|
595
|
+
* when `status` is set.
|
|
596
|
+
*/
|
|
597
|
+
excludeStatus?: OrderStatus[];
|
|
598
|
+
/** Exact-match customer email filter */
|
|
599
|
+
customerEmail?: string;
|
|
600
|
+
from?: string;
|
|
601
|
+
to?: string;
|
|
602
|
+
/**
|
|
603
|
+
* Only orders still awaiting merchant fulfillment (paid-family shipping
|
|
604
|
+
* orders with no merchant_fulfilled_at). Sent as `unfulfilled_only=true`.
|
|
605
|
+
*/
|
|
606
|
+
unfulfilledOnly?: boolean;
|
|
607
|
+
limit?: number;
|
|
608
|
+
offset?: number;
|
|
609
|
+
}
|
|
610
|
+
/** Body for POST /orders/{orderId}/fulfillment. */
|
|
611
|
+
interface SetOrderFulfillmentInput {
|
|
612
|
+
/** True marks the WHOLE order done; false un-marks it. */
|
|
613
|
+
fulfilled: boolean;
|
|
614
|
+
/**
|
|
615
|
+
* Optional tracking number recorded with mark-done. Letters, digits,
|
|
616
|
+
* spaces, `-` and `_` only; max 100 chars (validated server-side too).
|
|
617
|
+
*/
|
|
618
|
+
trackingNumber?: string;
|
|
619
|
+
}
|
|
620
|
+
/**
|
|
621
|
+
* A durable customer — the mutable CRM/identity spine. Email is the identity
|
|
622
|
+
* (unique per site) and is not editable via the API.
|
|
623
|
+
*/
|
|
624
|
+
interface Customer {
|
|
625
|
+
id: string;
|
|
626
|
+
site_id: string;
|
|
627
|
+
email: string;
|
|
628
|
+
name: string | null;
|
|
629
|
+
phone: string | null;
|
|
630
|
+
stripe_customer_id: string | null;
|
|
631
|
+
metadata: Record<string, unknown>;
|
|
632
|
+
created_at: string;
|
|
633
|
+
updated_at: string;
|
|
634
|
+
}
|
|
635
|
+
/** A saved address on a customer. */
|
|
636
|
+
interface CustomerAddress {
|
|
637
|
+
id: string;
|
|
638
|
+
name: string | null;
|
|
639
|
+
line1: string;
|
|
640
|
+
line2: string | null;
|
|
641
|
+
city: string;
|
|
642
|
+
state: string | null;
|
|
643
|
+
postal_code: string;
|
|
644
|
+
country: string;
|
|
645
|
+
is_default: boolean;
|
|
646
|
+
}
|
|
647
|
+
/** Customer detail = the customer plus addresses and their order count. */
|
|
648
|
+
interface CustomerDetail$1 extends Customer {
|
|
649
|
+
addresses: CustomerAddress[];
|
|
650
|
+
order_count: number;
|
|
651
|
+
}
|
|
652
|
+
/** Paginated customers response */
|
|
653
|
+
interface CustomersListResponse {
|
|
654
|
+
customers: Customer[];
|
|
655
|
+
total: number;
|
|
656
|
+
limit: number;
|
|
657
|
+
offset: number;
|
|
658
|
+
}
|
|
659
|
+
/** Options for fetching customers */
|
|
660
|
+
interface GetCustomersOptions {
|
|
661
|
+
/** Exact-match email filter (case-insensitive) */
|
|
662
|
+
email?: string;
|
|
663
|
+
limit?: number;
|
|
664
|
+
offset?: number;
|
|
665
|
+
}
|
|
666
|
+
/**
|
|
667
|
+
* The settled headline for a revenue period: gross in the owner's settlement
|
|
668
|
+
* currency, exact (Stripe's own conversion, snapshotted at fulfillment).
|
|
669
|
+
* `complete: false` means at least one in-range order lacks the snapshot —
|
|
670
|
+
* the number is NOT the whole period, so render the per-currency totals
|
|
671
|
+
* instead. Never guessed, never approximated.
|
|
672
|
+
*/
|
|
673
|
+
interface SettledRevenue {
|
|
674
|
+
gross: number;
|
|
675
|
+
currency: string;
|
|
676
|
+
complete: boolean;
|
|
677
|
+
}
|
|
678
|
+
/**
|
|
679
|
+
* One presentment currency's slice of a revenue period. Amounts are minor
|
|
680
|
+
* units in `currency` — never sum across entries of different currencies.
|
|
681
|
+
*/
|
|
682
|
+
interface RevenueCurrencyTotal {
|
|
683
|
+
currency: string;
|
|
684
|
+
gross: number;
|
|
685
|
+
refunded: number;
|
|
686
|
+
net: number;
|
|
687
|
+
orders: number;
|
|
688
|
+
}
|
|
689
|
+
/**
|
|
690
|
+
* A revenue rollup window (today / last 7 days / last 30 days). `totals` is
|
|
691
|
+
* ordered primary currency first.
|
|
692
|
+
*/
|
|
693
|
+
interface RevenuePeriod {
|
|
694
|
+
orders: number;
|
|
695
|
+
settled: SettledRevenue;
|
|
696
|
+
totals: RevenueCurrencyTotal[];
|
|
697
|
+
}
|
|
698
|
+
type NeedsAttentionType = "receipt_failed" | "disputed" | "low_stock" | "unfulfilled_shipping";
|
|
699
|
+
/** One item the merchant should look at. `title` is server-written copy. */
|
|
700
|
+
interface NeedsAttentionItem {
|
|
701
|
+
type: NeedsAttentionType;
|
|
702
|
+
order_id?: string;
|
|
703
|
+
product_id?: string;
|
|
704
|
+
title: string;
|
|
705
|
+
created_at?: string;
|
|
706
|
+
}
|
|
707
|
+
/** A product at or below the low-stock threshold. */
|
|
708
|
+
interface LowStockProduct {
|
|
709
|
+
product_id: string;
|
|
710
|
+
name: string;
|
|
711
|
+
/** Units still available on the lowest tracked variant. */
|
|
712
|
+
available: number;
|
|
713
|
+
}
|
|
714
|
+
/**
|
|
715
|
+
* Response from GET /api/v1/summary — the merchant's one-look business
|
|
716
|
+
* rollup. `visitors` is reserved (always null in v1).
|
|
717
|
+
*/
|
|
718
|
+
interface BusinessSummary {
|
|
719
|
+
site_id: string;
|
|
720
|
+
currency: string;
|
|
721
|
+
revenue: {
|
|
722
|
+
today: RevenuePeriod;
|
|
723
|
+
d7: RevenuePeriod;
|
|
724
|
+
d30: RevenuePeriod;
|
|
725
|
+
};
|
|
726
|
+
needs_attention: {
|
|
727
|
+
count: number;
|
|
728
|
+
items: NeedsAttentionItem[];
|
|
729
|
+
};
|
|
730
|
+
products: {
|
|
731
|
+
count: number;
|
|
732
|
+
low_stock: LowStockProduct[];
|
|
733
|
+
};
|
|
734
|
+
visitors: null;
|
|
735
|
+
}
|
|
736
|
+
/** Options for fetching the business summary. */
|
|
737
|
+
interface GetBusinessSummaryOptions {
|
|
738
|
+
/**
|
|
739
|
+
* Minutes to ADD to UTC for the merchant's local time — i.e.
|
|
740
|
+
* `-new Date().getTimezoneOffset()`. Drives the "today" day boundary.
|
|
741
|
+
*/
|
|
742
|
+
tzOffsetMinutes: number;
|
|
743
|
+
}
|
|
744
|
+
/** Where a person row came from. */
|
|
745
|
+
type PersonSource = "customer" | "lead";
|
|
746
|
+
/**
|
|
747
|
+
* One row of the merged people list (customers ∪ form leads, grouped by
|
|
748
|
+
* email). The merge is DISPLAY GROUPING ONLY, never identity: lead emails are
|
|
749
|
+
* attacker-asserted via a public form and unverified — `sources` carries the
|
|
750
|
+
* provenance, and submission content must always be labeled unverified.
|
|
751
|
+
*
|
|
752
|
+
* A null `email` is an anonymous single-submission row (never grouped);
|
|
753
|
+
* `submission_id` is set on those.
|
|
754
|
+
*/
|
|
755
|
+
interface Person {
|
|
756
|
+
email: string | null;
|
|
757
|
+
name: string | null;
|
|
758
|
+
sources: PersonSource[];
|
|
759
|
+
order_count: number;
|
|
760
|
+
submission_count: number;
|
|
761
|
+
last_order_at: string | null;
|
|
762
|
+
last_submission_at: string | null;
|
|
763
|
+
last_activity_at: string;
|
|
764
|
+
/** Server-capped excerpt (≤200 chars) of the latest submission message. Lead-authored: render as plain text only. */
|
|
765
|
+
latest_message_excerpt: string | null;
|
|
766
|
+
customer_id: string | null;
|
|
767
|
+
submission_id: string | null;
|
|
768
|
+
}
|
|
769
|
+
/** Response from GET /api/v1/people. */
|
|
770
|
+
interface PeopleListResponse {
|
|
771
|
+
people: Person[];
|
|
772
|
+
limit: number;
|
|
773
|
+
offset: number;
|
|
774
|
+
}
|
|
775
|
+
/** Options for fetching the people list. */
|
|
776
|
+
interface GetPeopleOptions {
|
|
777
|
+
/** Only people active since this ISO datetime. */
|
|
778
|
+
since?: string;
|
|
779
|
+
/** Free-text filter (email/name). */
|
|
780
|
+
q?: string;
|
|
781
|
+
limit?: number;
|
|
782
|
+
offset?: number;
|
|
783
|
+
}
|
|
784
|
+
/** An order row inside a person detail (a compact projection, not the full Order). */
|
|
785
|
+
interface PersonOrder {
|
|
786
|
+
id: string;
|
|
787
|
+
/**
|
|
788
|
+
* The merchant-facing order number (`#1042`). Null on orders written before
|
|
789
|
+
* the sequence existed — those fall back to a short id prefix. Optional so
|
|
790
|
+
* older API deployments that omit the field still typecheck.
|
|
791
|
+
*/
|
|
792
|
+
order_number?: number | null;
|
|
793
|
+
status: OrderStatus;
|
|
794
|
+
/** GOODS ONLY — postage and exclusive tax sit outside it. Not the display figure. */
|
|
795
|
+
amount_total: number;
|
|
796
|
+
/**
|
|
797
|
+
* What the buyer actually paid: goods + postage + exclusive automatic tax.
|
|
798
|
+
* RENDER THIS ONE. It is the same figure the Orders view shows for the same
|
|
799
|
+
* order, and showing `amount_total` here instead is what made a person's
|
|
800
|
+
* purchase history disagree with their own order. Optional so older API
|
|
801
|
+
* deployments that omit the field still typecheck — renderers fall back to
|
|
802
|
+
* `amount_total`, which is right for every order without postage or added
|
|
803
|
+
* tax and is the only number those deployments have.
|
|
804
|
+
*/
|
|
805
|
+
charged_total?: number;
|
|
806
|
+
currency: string;
|
|
807
|
+
created_at: string;
|
|
808
|
+
}
|
|
809
|
+
/** A form submission inside a person detail. `data` is lead-authored: plain text only. */
|
|
810
|
+
interface PersonSubmission {
|
|
811
|
+
id: string;
|
|
812
|
+
form_id: string;
|
|
813
|
+
form_name: string | null;
|
|
814
|
+
created_at: string;
|
|
815
|
+
data: Record<string, unknown>;
|
|
816
|
+
}
|
|
817
|
+
/**
|
|
818
|
+
* Response from GET /api/v1/people/{email}: everything known about one
|
|
819
|
+
* person — the durable customer record (when they ever bought), their orders,
|
|
820
|
+
* and their form submissions (unverified — anyone can submit a form claiming
|
|
821
|
+
* any email).
|
|
822
|
+
*/
|
|
823
|
+
interface PersonDetail {
|
|
824
|
+
email: string;
|
|
825
|
+
name: string | null;
|
|
826
|
+
customer: {
|
|
827
|
+
id: string;
|
|
828
|
+
email: string;
|
|
829
|
+
name: string | null;
|
|
830
|
+
phone: string | null;
|
|
831
|
+
created_at: string;
|
|
832
|
+
} | null;
|
|
833
|
+
orders: PersonOrder[];
|
|
834
|
+
submissions: PersonSubmission[];
|
|
835
|
+
}
|
|
93
836
|
|
|
94
837
|
declare class AifeaturesApiError extends Error {
|
|
95
838
|
status: number;
|
|
@@ -105,7 +848,44 @@ interface AifeaturesApiClient {
|
|
|
105
848
|
getSubmissions(formId: string, options?: GetSubmissionsOptions): Promise<PaginatedSubmissions>;
|
|
106
849
|
getSubmission(submissionId: string): Promise<Submission>;
|
|
107
850
|
deleteSubmission(submissionId: string): Promise<void>;
|
|
108
|
-
downloadAttachment(submissionId: string,
|
|
851
|
+
downloadAttachment(submissionId: string, attachment: string | Pick<Attachment, 'id' | 'name'>): Promise<void>;
|
|
852
|
+
getPaymentsStatus(): Promise<PaymentsStatusResponse>;
|
|
853
|
+
/** Pass `{ include: 'stats' }` to attach rolling-30-day sales stats (owner-side surfaces only). */
|
|
854
|
+
getProducts(options?: GetProductsOptions): Promise<Product[]>;
|
|
855
|
+
/** Returns the product detail (flat fields + options + variants). */
|
|
856
|
+
getProduct(productId: string): Promise<ProductDetail>;
|
|
857
|
+
createProduct(input: CreateProductInput): Promise<ProductDetail>;
|
|
858
|
+
updateProduct(productId: string, input: UpdateProductInput): Promise<Product>;
|
|
859
|
+
deleteProduct(productId: string): Promise<void>;
|
|
860
|
+
attachProductFile(productId: string, file: File): Promise<Product>;
|
|
861
|
+
attachProductFileFromUrl(productId: string, sourceUrl: string): Promise<Product>;
|
|
862
|
+
createOption(productId: string, input: CreateOptionInput): Promise<ProductOption>;
|
|
863
|
+
updateOption(optionId: string, input: UpdateOptionInput): Promise<ProductOption>;
|
|
864
|
+
deleteOption(optionId: string): Promise<void>;
|
|
865
|
+
createVariant(productId: string, input: CreateVariantInput): Promise<ProductVariant>;
|
|
866
|
+
updateVariant(variantId: string, input: UpdateVariantInput): Promise<ProductVariant>;
|
|
867
|
+
deleteVariant(variantId: string): Promise<void>;
|
|
868
|
+
setVariantInventory(variantId: string, input: SetInventoryInput): Promise<VariantInventory>;
|
|
869
|
+
adjustVariantInventory(variantId: string, input: AdjustInventoryInput): Promise<VariantInventory>;
|
|
870
|
+
getCustomers(options?: GetCustomersOptions): Promise<CustomersListResponse>;
|
|
871
|
+
getCustomer(customerId: string): Promise<CustomerDetail$1>;
|
|
872
|
+
getOrders(options?: GetOrdersOptions): Promise<PaginatedOrders>;
|
|
873
|
+
getOrder(orderId: string): Promise<Order>;
|
|
874
|
+
resendOrderReceipt(orderId: string): Promise<void>;
|
|
875
|
+
resetOrderDownloads(orderId: string): Promise<Order>;
|
|
876
|
+
/**
|
|
877
|
+
* Mark the WHOLE order done (or un-mark it), optionally recording a
|
|
878
|
+
* tracking number. Merchant bookkeeping only — never moves money. The API
|
|
879
|
+
* answers 409 when the order's status is not paid / partially_refunded /
|
|
880
|
+
* disputed.
|
|
881
|
+
*/
|
|
882
|
+
setOrderFulfillment(orderId: string, input: SetOrderFulfillmentInput): Promise<Order>;
|
|
883
|
+
/** One-look business summary: revenue windows, needs-attention list, product counts. */
|
|
884
|
+
getBusinessSummary(options: GetBusinessSummaryOptions): Promise<BusinessSummary>;
|
|
885
|
+
/** Merged people list (customers ∪ form leads, grouped by email). */
|
|
886
|
+
getPeople(options?: GetPeopleOptions): Promise<PeopleListResponse>;
|
|
887
|
+
/** Everything known about one person (customer record, orders, submissions). */
|
|
888
|
+
getPerson(email: string): Promise<PersonDetail>;
|
|
109
889
|
}
|
|
110
890
|
declare function createApiClient(siteToken: string, apiUrl?: string): AifeaturesApiClient;
|
|
111
891
|
|
|
@@ -170,6 +950,354 @@ interface SubmissionDetailProps {
|
|
|
170
950
|
}
|
|
171
951
|
declare function SubmissionDetail({ submission, onBack, }: SubmissionDetailProps): react_jsx_runtime.JSX.Element;
|
|
172
952
|
|
|
953
|
+
/**
|
|
954
|
+
* What the merchant chose to refund — the body of POST /orders/:id/refund,
|
|
955
|
+
* verbatim. It carries a SELECTION, never a total: the API prices lines and
|
|
956
|
+
* postage from the order's own snapshot, so nothing here is computed in the
|
|
957
|
+
* browser beyond what the dialog displays.
|
|
958
|
+
*
|
|
959
|
+
* { amount } free-form escape hatch
|
|
960
|
+
* { line_items?, shipping? } named lines and/or the un-refunded postage
|
|
961
|
+
* { full: true } everything still outstanding
|
|
962
|
+
*/
|
|
963
|
+
type RefundRequest = {
|
|
964
|
+
amount: number;
|
|
965
|
+
} | {
|
|
966
|
+
line_items?: number[];
|
|
967
|
+
shipping?: boolean;
|
|
968
|
+
} | {
|
|
969
|
+
full: true;
|
|
970
|
+
};
|
|
971
|
+
interface OrderDetailProps {
|
|
972
|
+
order: Order;
|
|
973
|
+
onBack: () => void;
|
|
974
|
+
/**
|
|
975
|
+
* Host-app refund relay. Refunds are org-key-only at the API — the site
|
|
976
|
+
* token this dashboard holds cannot issue them, so the host app must relay
|
|
977
|
+
* the refund through its own backend. Called with the order, the refund
|
|
978
|
+
* amount in the currency's minor units, and the request body to relay. Omit
|
|
979
|
+
* to disable the refund button.
|
|
980
|
+
*
|
|
981
|
+
* `request` is the authoritative one — forward it as the POST body. `amount`
|
|
982
|
+
* is what this refund is EXPECTED to move, kept as the second parameter so
|
|
983
|
+
* an existing amount-only relay keeps compiling and keeps working: such a
|
|
984
|
+
* host still returns the right money, it just records no per-line or postage
|
|
985
|
+
* bookkeeping (the same degradation as a refund taken from the Stripe
|
|
986
|
+
* dashboard).
|
|
987
|
+
*/
|
|
988
|
+
onRefund?: (order: Order, amount: number, request: RefundRequest) => void | Promise<void>;
|
|
989
|
+
/** Called with the fresh order after any action that changes it */
|
|
990
|
+
onOrderUpdated?: (order: Order) => void;
|
|
991
|
+
/**
|
|
992
|
+
* Merchant-view mode (plan Unit 5): shows the shipping-fulfillment action
|
|
993
|
+
* ("Mark as shipped" + optional tracking, and the undo) on orders that
|
|
994
|
+
* collected a shipping address. Off by default so existing surfaces are
|
|
995
|
+
* unchanged.
|
|
996
|
+
*/
|
|
997
|
+
allowFulfillment?: boolean;
|
|
998
|
+
/**
|
|
999
|
+
* Walk to the neighbouring order in the list's CURRENTLY LOADED page.
|
|
1000
|
+
* Omitted at the edges — this deliberately does not page across a boundary.
|
|
1001
|
+
*/
|
|
1002
|
+
onPrevOrder?: () => void;
|
|
1003
|
+
onNextOrder?: () => void;
|
|
1004
|
+
hasPrevOrder?: boolean;
|
|
1005
|
+
hasNextOrder?: boolean;
|
|
1006
|
+
}
|
|
1007
|
+
declare function OrderDetail({ order: initialOrder, onBack, onRefund, onOrderUpdated, allowFulfillment, onPrevOrder, onNextOrder, hasPrevOrder, hasNextOrder, }: OrderDetailProps): react_jsx_runtime.JSX.Element;
|
|
1008
|
+
|
|
1009
|
+
/**
|
|
1010
|
+
* Back-compat alias — the name the rest of the package (and any host app)
|
|
1011
|
+
* already imports. Identical rendering to PaymentStatusBadge.
|
|
1012
|
+
*/
|
|
1013
|
+
declare function OrderStatusBadge({ status }: {
|
|
1014
|
+
status: OrderStatus;
|
|
1015
|
+
}): react_jsx_runtime.JSX.Element;
|
|
1016
|
+
|
|
1017
|
+
interface OrdersListProps {
|
|
1018
|
+
/**
|
|
1019
|
+
* Host-app refund relay. Refunds are org-key-only at the API — the site
|
|
1020
|
+
* token this dashboard holds cannot issue them. Omit to disable the refund
|
|
1021
|
+
* button. Signature (including the itemized request body) is OrderDetail's,
|
|
1022
|
+
* restated nowhere so the two cannot drift.
|
|
1023
|
+
*/
|
|
1024
|
+
onRefund?: OrderDetailProps["onRefund"];
|
|
1025
|
+
/** Optional className */
|
|
1026
|
+
className?: string;
|
|
1027
|
+
/** Bump to force a refetch with the current filters (view freshness, plan D11). */
|
|
1028
|
+
refreshKey?: number;
|
|
1029
|
+
/**
|
|
1030
|
+
* Deep-open this order's detail on mount (the merchant view's
|
|
1031
|
+
* `params.orderId`, plan D2). The order is fetched by id, so it opens even
|
|
1032
|
+
* when it isn't on the first page.
|
|
1033
|
+
*/
|
|
1034
|
+
initialOrderId?: string;
|
|
1035
|
+
/**
|
|
1036
|
+
* Merchant-view mode (plan Unit 5): shows the "Needs shipping" tab,
|
|
1037
|
+
* per-row shipping badges, and the shipping actions in the detail. Off by
|
|
1038
|
+
* default so existing surfaces are unchanged.
|
|
1039
|
+
*/
|
|
1040
|
+
showFulfillment?: boolean;
|
|
1041
|
+
/**
|
|
1042
|
+
* Replaces the default unfiltered empty-state copy (the filtered copy is
|
|
1043
|
+
* unchanged).
|
|
1044
|
+
*/
|
|
1045
|
+
emptyMessage?: React.ReactNode;
|
|
1046
|
+
/**
|
|
1047
|
+
* Told whenever this list swaps between its index and an order's detail.
|
|
1048
|
+
* The detail owns the single back affordance ("← Orders"), so the wrapping
|
|
1049
|
+
* shell suppresses its own "Back to website" button while it is open —
|
|
1050
|
+
* two stacked back buttons taught nobody anything.
|
|
1051
|
+
*/
|
|
1052
|
+
onDetailOpenChange?: (open: boolean) => void;
|
|
1053
|
+
}
|
|
1054
|
+
declare function OrdersList({ onRefund, className, refreshKey, initialOrderId, showFulfillment, emptyMessage, onDetailOpenChange, }: OrdersListProps): react_jsx_runtime.JSX.Element;
|
|
1055
|
+
|
|
1056
|
+
interface PaymentsDashboardProps {
|
|
1057
|
+
/** Optional className */
|
|
1058
|
+
className?: string;
|
|
1059
|
+
/** Which tab to open initially */
|
|
1060
|
+
defaultTab?: "products" | "orders" | "customers" | "setup";
|
|
1061
|
+
/**
|
|
1062
|
+
* Host-app callback that starts (or resumes) Stripe Connect onboarding —
|
|
1063
|
+
* shown on the Setup tab when the site still needs Stripe.
|
|
1064
|
+
*/
|
|
1065
|
+
onConnectStripe?: () => void;
|
|
1066
|
+
/**
|
|
1067
|
+
* Host-app refund relay. Refunds are ORG-KEY-ONLY at the aifeatures API —
|
|
1068
|
+
* the site token this dashboard holds cannot issue them, so the host app
|
|
1069
|
+
* must relay refunds through its own backend. Called with the order, the
|
|
1070
|
+
* refund amount in the currency's minor units, and the request body to
|
|
1071
|
+
* relay (see OrderDetail's RefundRequest — it carries the itemized
|
|
1072
|
+
* selection). When omitted, the refund button renders disabled with a note.
|
|
1073
|
+
*/
|
|
1074
|
+
onRefund?: OrdersListProps["onRefund"];
|
|
1075
|
+
/** Host-app callback for the needs_paid_plan upgrade CTA on the Setup tab */
|
|
1076
|
+
onUpgradePlan?: () => void;
|
|
1077
|
+
}
|
|
1078
|
+
declare function PaymentsDashboard({ className, defaultTab, onConnectStripe, onRefund, onUpgradePlan, }: PaymentsDashboardProps): react_jsx_runtime.JSX.Element;
|
|
1079
|
+
|
|
1080
|
+
interface UseProductsReturn {
|
|
1081
|
+
products: Product[];
|
|
1082
|
+
isLoading: boolean;
|
|
1083
|
+
error: Error | null;
|
|
1084
|
+
refetch: () => Promise<void>;
|
|
1085
|
+
createProduct: (input: CreateProductInput) => Promise<Product>;
|
|
1086
|
+
updateProduct: (productId: string, input: UpdateProductInput) => Promise<Product>;
|
|
1087
|
+
/** Soft delete — the product disappears from the list but order history survives. */
|
|
1088
|
+
deleteProduct: (productId: string) => Promise<void>;
|
|
1089
|
+
/** Attach a digital file via multipart upload. Sets fulfillment type to download. */
|
|
1090
|
+
attachProductFile: (productId: string, file: File) => Promise<Product>;
|
|
1091
|
+
/** Attach a digital file fetched server-side from a public https URL. */
|
|
1092
|
+
attachProductFileFromUrl: (productId: string, sourceUrl: string) => Promise<Product>;
|
|
1093
|
+
}
|
|
1094
|
+
interface UseProductsOptions {
|
|
1095
|
+
/**
|
|
1096
|
+
* Attach rolling-30-day sales stats to each product (`include=stats`).
|
|
1097
|
+
* Owner-side surfaces only — when false/omitted, stats are never requested.
|
|
1098
|
+
*/
|
|
1099
|
+
includeStats?: boolean;
|
|
1100
|
+
/**
|
|
1101
|
+
* Bump to force a refetch (view data freshness, plan D11). Optional and
|
|
1102
|
+
* additive; leaving it undefined changes nothing.
|
|
1103
|
+
*/
|
|
1104
|
+
refreshKey?: number;
|
|
1105
|
+
}
|
|
1106
|
+
declare function useProducts({ includeStats, refreshKey, }?: UseProductsOptions): UseProductsReturn;
|
|
1107
|
+
|
|
1108
|
+
interface ProductsListProps {
|
|
1109
|
+
/** Products state from useProducts (owned by the parent so edits stay in sync) */
|
|
1110
|
+
productsState: UseProductsReturn;
|
|
1111
|
+
/** Called when a product's edit action is selected */
|
|
1112
|
+
onSelectProduct?: (product: Product) => void;
|
|
1113
|
+
/** Called when the create-product action is selected */
|
|
1114
|
+
onCreateProduct?: () => void;
|
|
1115
|
+
/** Optional className */
|
|
1116
|
+
className?: string;
|
|
1117
|
+
}
|
|
1118
|
+
declare function ProductsList({ productsState, onSelectProduct, onCreateProduct, className, }: ProductsListProps): react_jsx_runtime.JSX.Element;
|
|
1119
|
+
|
|
1120
|
+
interface ProductSettingsProps {
|
|
1121
|
+
/** Products state from useProducts (owned by the parent so edits stay in sync) */
|
|
1122
|
+
productsState: UseProductsReturn;
|
|
1123
|
+
/** The product to edit. Omit to create a new product. */
|
|
1124
|
+
product?: Product | null;
|
|
1125
|
+
/** The site currency (read-only; products are priced in the site currency) */
|
|
1126
|
+
currency: string;
|
|
1127
|
+
/** Called after a successful create or update */
|
|
1128
|
+
onSaved?: (product: Product) => void;
|
|
1129
|
+
/** Optional className */
|
|
1130
|
+
className?: string;
|
|
1131
|
+
}
|
|
1132
|
+
declare function ProductSettings({ productsState, product, currency: siteCurrency, onSaved, className, }: ProductSettingsProps): react_jsx_runtime.JSX.Element;
|
|
1133
|
+
|
|
1134
|
+
interface VariantsEditorProps {
|
|
1135
|
+
/** The product to manage options/variants for (must already exist). */
|
|
1136
|
+
productId: string;
|
|
1137
|
+
/** The site currency (variants are priced in the site currency). */
|
|
1138
|
+
currency: string;
|
|
1139
|
+
/** Optional className */
|
|
1140
|
+
className?: string;
|
|
1141
|
+
}
|
|
1142
|
+
/**
|
|
1143
|
+
* Options + variants + per-variant inventory editor for a product. Self-
|
|
1144
|
+
* contained: it loads the product detail and issues option/variant/inventory
|
|
1145
|
+
* calls itself (mirrors OrderDetail's direct-api pattern). Simple products
|
|
1146
|
+
* (no options) keep their single default variant — add an option to start
|
|
1147
|
+
* selling variants.
|
|
1148
|
+
*/
|
|
1149
|
+
declare function VariantsEditor({ productId, currency, className, }: VariantsEditorProps): react_jsx_runtime.JSX.Element;
|
|
1150
|
+
|
|
1151
|
+
interface CustomersListProps {
|
|
1152
|
+
/** Optional className */
|
|
1153
|
+
className?: string;
|
|
1154
|
+
}
|
|
1155
|
+
/**
|
|
1156
|
+
* Read-only list of a site's customers (the durable CRM identities upserted at
|
|
1157
|
+
* checkout). Filter by email, page through, and open a customer to see their
|
|
1158
|
+
* addresses and orders.
|
|
1159
|
+
*/
|
|
1160
|
+
declare function CustomersList({ className }: CustomersListProps): react_jsx_runtime.JSX.Element;
|
|
1161
|
+
|
|
1162
|
+
interface CustomerDetailProps {
|
|
1163
|
+
/** The customer to show (from the list row). */
|
|
1164
|
+
customer: Customer;
|
|
1165
|
+
onBack: () => void;
|
|
1166
|
+
/** Optional className */
|
|
1167
|
+
className?: string;
|
|
1168
|
+
}
|
|
1169
|
+
/**
|
|
1170
|
+
* Read-only customer profile: identity, saved addresses, and their orders.
|
|
1171
|
+
* Order count comes from the customer detail endpoint; the orders themselves
|
|
1172
|
+
* are fetched by the customer's email (exact match).
|
|
1173
|
+
*/
|
|
1174
|
+
declare function CustomerDetail({ customer, onBack, className }: CustomerDetailProps): react_jsx_runtime.JSX.Element;
|
|
1175
|
+
|
|
1176
|
+
interface PaymentsSetupProps {
|
|
1177
|
+
/**
|
|
1178
|
+
* Host-app callback that starts (or resumes) Stripe Connect onboarding.
|
|
1179
|
+
* Onboarding runs through the host app's backend — the dashboard can't
|
|
1180
|
+
* start it itself.
|
|
1181
|
+
*/
|
|
1182
|
+
onConnectStripe?: () => void;
|
|
1183
|
+
/** Host-app callback for the needs_paid_plan upgrade CTA */
|
|
1184
|
+
onUpgradePlan?: () => void;
|
|
1185
|
+
/** Optional className */
|
|
1186
|
+
className?: string;
|
|
1187
|
+
}
|
|
1188
|
+
declare function PaymentsSetup({ onConnectStripe, onUpgradePlan, className, }: PaymentsSetupProps): react_jsx_runtime.JSX.Element;
|
|
1189
|
+
|
|
1190
|
+
interface ViewShellProps {
|
|
1191
|
+
/** The view's title ("Orders", "Products", "Leads"). */
|
|
1192
|
+
title: string;
|
|
1193
|
+
/**
|
|
1194
|
+
* Host-app callback that swaps the panel back to the website preview. The
|
|
1195
|
+
* strip's "Back to website" button renders only when provided — the host
|
|
1196
|
+
* page owns the panel swap, this component only asks for it.
|
|
1197
|
+
*/
|
|
1198
|
+
onBackToWebsite?: () => void;
|
|
1199
|
+
/**
|
|
1200
|
+
* Suppress the strip's own "Back to website" button. A view that opens a
|
|
1201
|
+
* detail screen owns the single back affordance on it ("← Orders"); two
|
|
1202
|
+
* stacked back buttons, one above the other, taught nobody which was which.
|
|
1203
|
+
* The title stays, so the strip is still the view indicator.
|
|
1204
|
+
*/
|
|
1205
|
+
hideBackButton?: boolean;
|
|
1206
|
+
children: React.ReactNode;
|
|
1207
|
+
className?: string;
|
|
1208
|
+
}
|
|
1209
|
+
/**
|
|
1210
|
+
* The view strip + content wrapper every merchant view mounts inside
|
|
1211
|
+
* (plan D13). The strip is the sole view indicator: title on the left,
|
|
1212
|
+
* "Back to website" on the right, pinned to the top on small screens (D9) so
|
|
1213
|
+
* the way out is always reachable.
|
|
1214
|
+
*
|
|
1215
|
+
* Accessibility: the panel's content is replaced out from under screen-reader
|
|
1216
|
+
* users when a view opens, so the heading is an `aria-live="polite"` region
|
|
1217
|
+
* and receives focus on mount.
|
|
1218
|
+
*/
|
|
1219
|
+
declare function ViewShell({ title, onBackToWebsite, hideBackButton, children, className, }: ViewShellProps): react_jsx_runtime.JSX.Element;
|
|
1220
|
+
|
|
1221
|
+
interface OrdersViewProps {
|
|
1222
|
+
/**
|
|
1223
|
+
* Bump to refetch everything on screen (view data freshness, plan D11) —
|
|
1224
|
+
* the host increments it when a turn's tools changed business data.
|
|
1225
|
+
*/
|
|
1226
|
+
refreshKey?: number;
|
|
1227
|
+
/**
|
|
1228
|
+
* Deep-open this order's detail on mount (`show_view` params.orderId,
|
|
1229
|
+
* plan D2). The refund flow depends on this: "refund Jane's order" opens
|
|
1230
|
+
* straight onto the order the human is asked to confirm.
|
|
1231
|
+
*/
|
|
1232
|
+
initialOrderId?: string;
|
|
1233
|
+
/**
|
|
1234
|
+
* The host says whether the viewer is owner-side. Fail-closed: refunds are
|
|
1235
|
+
* offered only when true. (The view itself mounts owner-side only per the
|
|
1236
|
+
* plan's gating — this prop is the belt for those suspenders.)
|
|
1237
|
+
*/
|
|
1238
|
+
isOwner?: boolean;
|
|
1239
|
+
/**
|
|
1240
|
+
* Host-app refund relay (see OrderDetail.onRefund). Only honored when
|
|
1241
|
+
* `isOwner` — the refund authority is the owner's.
|
|
1242
|
+
*/
|
|
1243
|
+
onRefund?: OrdersListProps["onRefund"];
|
|
1244
|
+
/** Host-app callback that swaps the panel back to the website preview (plan D13). */
|
|
1245
|
+
onBackToWebsite?: () => void;
|
|
1246
|
+
className?: string;
|
|
1247
|
+
}
|
|
1248
|
+
/**
|
|
1249
|
+
* OrdersView — the merchant view the AI swaps in for "show me my orders"
|
|
1250
|
+
* (plan Unit 5). A read-only projection: the only buttons are the sanctioned
|
|
1251
|
+
* ones (refund relay, resend receipt, reset downloads, Mark done) plus
|
|
1252
|
+
* navigation. Ephemeral by design (plan D12): it mounts at top-level list
|
|
1253
|
+
* state and keeps no filters or scroll across swaps — except the
|
|
1254
|
+
* `initialOrderId` deep-open.
|
|
1255
|
+
*/
|
|
1256
|
+
declare function OrdersView({ refreshKey, initialOrderId, isOwner, onRefund, onBackToWebsite, className, }: OrdersViewProps): react_jsx_runtime.JSX.Element;
|
|
1257
|
+
|
|
1258
|
+
interface ProductsViewProps {
|
|
1259
|
+
/**
|
|
1260
|
+
* Bump to refetch (view data freshness, plan D11) — the host increments it
|
|
1261
|
+
* when a turn's tools changed business data.
|
|
1262
|
+
*/
|
|
1263
|
+
refreshKey?: number;
|
|
1264
|
+
/**
|
|
1265
|
+
* Owner-side sales stats (sold count + gross, rolling 30 days). The host
|
|
1266
|
+
* decides (plan decision A: stats are owner-side; editors see the catalog,
|
|
1267
|
+
* not the revenue). When false, stats are never even requested.
|
|
1268
|
+
*/
|
|
1269
|
+
showStats?: boolean;
|
|
1270
|
+
/** Host-app callback that swaps the panel back to the website preview (plan D13). */
|
|
1271
|
+
onBackToWebsite?: () => void;
|
|
1272
|
+
className?: string;
|
|
1273
|
+
}
|
|
1274
|
+
/**
|
|
1275
|
+
* ProductsView — the read-only catalog (plan Unit 5). No edit forms: changes
|
|
1276
|
+
* happen in conversation with the AI, and this view shows the result.
|
|
1277
|
+
* Ephemeral (plan D12).
|
|
1278
|
+
*/
|
|
1279
|
+
declare function ProductsView({ refreshKey, showStats, onBackToWebsite, className, }: ProductsViewProps): react_jsx_runtime.JSX.Element;
|
|
1280
|
+
|
|
1281
|
+
interface LeadsViewProps {
|
|
1282
|
+
/**
|
|
1283
|
+
* Bump to refetch (view data freshness, plan D11) — the host increments it
|
|
1284
|
+
* when a turn's tools changed business data.
|
|
1285
|
+
*/
|
|
1286
|
+
refreshKey?: number;
|
|
1287
|
+
/** Host-app callback that swaps the panel back to the website preview (plan D13). */
|
|
1288
|
+
onBackToWebsite?: () => void;
|
|
1289
|
+
className?: string;
|
|
1290
|
+
}
|
|
1291
|
+
/**
|
|
1292
|
+
* LeadsView — the merged people list (customers ∪ form leads) with in-view
|
|
1293
|
+
* detail navigation (plan Unit 5). All lead-authored content renders as plain
|
|
1294
|
+
* text and is labeled unverified (plan D7/D15). Ephemeral (plan D12).
|
|
1295
|
+
*
|
|
1296
|
+
* The one thing it does beyond looking: hand a reply to the merchant's own mail
|
|
1297
|
+
* client. Nothing is ever sent from here.
|
|
1298
|
+
*/
|
|
1299
|
+
declare function LeadsView({ refreshKey, onBackToWebsite, className, }: LeadsViewProps): react_jsx_runtime.JSX.Element;
|
|
1300
|
+
|
|
173
1301
|
interface UseFormsReturn {
|
|
174
1302
|
forms: Form[];
|
|
175
1303
|
isLoading: boolean;
|
|
@@ -201,4 +1329,218 @@ interface UseSubmissionsOptions {
|
|
|
201
1329
|
}
|
|
202
1330
|
declare function useSubmissions({ formId, initialPageSize, }: UseSubmissionsOptions): UseSubmissionsReturn;
|
|
203
1331
|
|
|
204
|
-
|
|
1332
|
+
interface UseOrdersReturn {
|
|
1333
|
+
orders: Order[];
|
|
1334
|
+
total: number;
|
|
1335
|
+
isLoading: boolean;
|
|
1336
|
+
error: Error | null;
|
|
1337
|
+
page: number;
|
|
1338
|
+
pageSize: number;
|
|
1339
|
+
hasNextPage: boolean;
|
|
1340
|
+
hasPreviousPage: boolean;
|
|
1341
|
+
setPage: (page: number) => void;
|
|
1342
|
+
setPageSize: (size: number) => void;
|
|
1343
|
+
/** Status filter. Undefined = all statuses. Resets to the first page. */
|
|
1344
|
+
status: OrderStatus | undefined;
|
|
1345
|
+
setStatus: (status: OrderStatus | undefined) => void;
|
|
1346
|
+
/**
|
|
1347
|
+
* Restrict the list to this SET of statuses — the saved-view tabs ("Paid",
|
|
1348
|
+
* "Refunds & disputes") each cover several. Sent server-side as the
|
|
1349
|
+
* complement via `exclude_status`, so paging and totals stay truthful; a
|
|
1350
|
+
* client-side filter over the fetched page would silently hide matches that
|
|
1351
|
+
* live on page 2. Undefined = unrestricted. Ignored while `status` is set
|
|
1352
|
+
* (the API gives `status` precedence too). Resets to the first page.
|
|
1353
|
+
*/
|
|
1354
|
+
statusIn: OrderStatus[] | undefined;
|
|
1355
|
+
setStatusIn: (statuses: OrderStatus[] | undefined) => void;
|
|
1356
|
+
/** Exact-match customer email filter. Resets to the first page. */
|
|
1357
|
+
customerEmail: string;
|
|
1358
|
+
setCustomerEmail: (email: string) => void;
|
|
1359
|
+
/**
|
|
1360
|
+
* Inclusive created-at lower bound, 'YYYY-MM-DD' (the shape an
|
|
1361
|
+
* `<input type="date">` produces). Empty = unbounded. Resets to the first
|
|
1362
|
+
* page. The API accepts a full ISO datetime too, and treats a date-only `to`
|
|
1363
|
+
* as the whole of that day.
|
|
1364
|
+
*/
|
|
1365
|
+
from: string;
|
|
1366
|
+
setFrom: (from: string) => void;
|
|
1367
|
+
/** Inclusive created-at upper bound, 'YYYY-MM-DD'. Empty = unbounded. */
|
|
1368
|
+
to: string;
|
|
1369
|
+
setTo: (to: string) => void;
|
|
1370
|
+
/**
|
|
1371
|
+
* Whether abandoned checkouts (`pending`/`expired`) are listed. False by
|
|
1372
|
+
* default: a buyer who closes the Stripe page leaves a `pending` order that
|
|
1373
|
+
* the sweeper later marks `expired`, and neither is a sale — "Pending" in a
|
|
1374
|
+
* sales list reads as "money on the way". Ignored while an explicit `status`
|
|
1375
|
+
* filter is set, so picking "Pending" from the dropdown still works.
|
|
1376
|
+
*/
|
|
1377
|
+
showAbandoned: boolean;
|
|
1378
|
+
setShowAbandoned: (show: boolean) => void;
|
|
1379
|
+
/**
|
|
1380
|
+
* Only orders still awaiting merchant fulfillment (server-side
|
|
1381
|
+
* `unfulfilled_only=true`). Resets to the first page.
|
|
1382
|
+
*/
|
|
1383
|
+
unfulfilledOnly: boolean;
|
|
1384
|
+
setUnfulfilledOnly: (only: boolean) => void;
|
|
1385
|
+
/** Clears every filter (status, email, dates) and returns to the first page. */
|
|
1386
|
+
clearFilters: () => void;
|
|
1387
|
+
refetch: () => Promise<void>;
|
|
1388
|
+
}
|
|
1389
|
+
interface UseOrdersOptions {
|
|
1390
|
+
initialPageSize?: number;
|
|
1391
|
+
/**
|
|
1392
|
+
* Bump to force a refetch with the current filters (view data freshness,
|
|
1393
|
+
* plan D11) — the host increments it when a turn's tools changed business
|
|
1394
|
+
* data. Optional and additive; leaving it undefined changes nothing.
|
|
1395
|
+
*/
|
|
1396
|
+
refreshKey?: number;
|
|
1397
|
+
}
|
|
1398
|
+
declare function useOrders({ initialPageSize, refreshKey, }?: UseOrdersOptions): UseOrdersReturn;
|
|
1399
|
+
|
|
1400
|
+
interface UsePaymentsStatusReturn {
|
|
1401
|
+
status: PaymentsStatusResponse | null;
|
|
1402
|
+
isLoading: boolean;
|
|
1403
|
+
error: Error | null;
|
|
1404
|
+
refetch: () => Promise<void>;
|
|
1405
|
+
}
|
|
1406
|
+
declare function usePaymentsStatus(): UsePaymentsStatusReturn;
|
|
1407
|
+
|
|
1408
|
+
interface UseCustomersReturn {
|
|
1409
|
+
customers: Customer[];
|
|
1410
|
+
total: number;
|
|
1411
|
+
isLoading: boolean;
|
|
1412
|
+
error: Error | null;
|
|
1413
|
+
page: number;
|
|
1414
|
+
pageSize: number;
|
|
1415
|
+
hasNextPage: boolean;
|
|
1416
|
+
hasPreviousPage: boolean;
|
|
1417
|
+
setPage: (page: number) => void;
|
|
1418
|
+
setPageSize: (size: number) => void;
|
|
1419
|
+
/** Exact-match email filter. Resets to the first page. */
|
|
1420
|
+
email: string;
|
|
1421
|
+
setEmail: (email: string) => void;
|
|
1422
|
+
refetch: () => Promise<void>;
|
|
1423
|
+
}
|
|
1424
|
+
interface UseCustomersOptions {
|
|
1425
|
+
initialPageSize?: number;
|
|
1426
|
+
}
|
|
1427
|
+
declare function useCustomers({ initialPageSize, }?: UseCustomersOptions): UseCustomersReturn;
|
|
1428
|
+
|
|
1429
|
+
interface UseBusinessSummaryOptions {
|
|
1430
|
+
/**
|
|
1431
|
+
* Bump to force a refetch (view data freshness, plan D11) — the host
|
|
1432
|
+
* increments it when a turn's tools changed business data. Optional and
|
|
1433
|
+
* additive; leaving it undefined changes nothing.
|
|
1434
|
+
*/
|
|
1435
|
+
refreshKey?: number;
|
|
1436
|
+
}
|
|
1437
|
+
interface UseBusinessSummaryReturn {
|
|
1438
|
+
summary: BusinessSummary | null;
|
|
1439
|
+
isLoading: boolean;
|
|
1440
|
+
error: Error | null;
|
|
1441
|
+
refetch: () => Promise<void>;
|
|
1442
|
+
}
|
|
1443
|
+
/**
|
|
1444
|
+
* The merchant's one-look business rollup (GET /api/v1/summary). The browser's
|
|
1445
|
+
* timezone offset rides along so "today" means the merchant's today, not UTC's
|
|
1446
|
+
* — a Saturday-evening sale must never read as "yesterday, $0".
|
|
1447
|
+
*/
|
|
1448
|
+
declare function useBusinessSummary({ refreshKey, }?: UseBusinessSummaryOptions): UseBusinessSummaryReturn;
|
|
1449
|
+
|
|
1450
|
+
interface UsePeopleOptions {
|
|
1451
|
+
initialPageSize?: number;
|
|
1452
|
+
/**
|
|
1453
|
+
* Bump to force a refetch with the current filters (view data freshness,
|
|
1454
|
+
* plan D11). Optional and additive; leaving it undefined changes nothing.
|
|
1455
|
+
*/
|
|
1456
|
+
refreshKey?: number;
|
|
1457
|
+
}
|
|
1458
|
+
interface UsePeopleReturn {
|
|
1459
|
+
people: Person[];
|
|
1460
|
+
isLoading: boolean;
|
|
1461
|
+
error: Error | null;
|
|
1462
|
+
page: number;
|
|
1463
|
+
pageSize: number;
|
|
1464
|
+
/**
|
|
1465
|
+
* The people list has no server total (the merge is computed on read), so
|
|
1466
|
+
* "next" is inferred from a full page: a page shorter than pageSize is the
|
|
1467
|
+
* last one. A period-boundary edge case (an exactly-full last page) costs
|
|
1468
|
+
* one empty next page — accepted.
|
|
1469
|
+
*/
|
|
1470
|
+
hasNextPage: boolean;
|
|
1471
|
+
hasPreviousPage: boolean;
|
|
1472
|
+
setPage: (page: number) => void;
|
|
1473
|
+
/** Free-text filter (email/name). Resets to the first page. */
|
|
1474
|
+
q: string;
|
|
1475
|
+
setQ: (q: string) => void;
|
|
1476
|
+
refetch: () => Promise<void>;
|
|
1477
|
+
}
|
|
1478
|
+
/**
|
|
1479
|
+
* The merged people list (customers ∪ form leads, grouped by email — display
|
|
1480
|
+
* grouping only, never identity; see the Person type's provenance notes).
|
|
1481
|
+
*/
|
|
1482
|
+
declare function usePeople({ initialPageSize, refreshKey, }?: UsePeopleOptions): UsePeopleReturn;
|
|
1483
|
+
|
|
1484
|
+
interface UsePersonOptions {
|
|
1485
|
+
/**
|
|
1486
|
+
* Bump to force a refetch (view data freshness, plan D11). Optional and
|
|
1487
|
+
* additive; leaving it undefined changes nothing.
|
|
1488
|
+
*/
|
|
1489
|
+
refreshKey?: number;
|
|
1490
|
+
}
|
|
1491
|
+
interface UsePersonReturn {
|
|
1492
|
+
person: PersonDetail | null;
|
|
1493
|
+
isLoading: boolean;
|
|
1494
|
+
error: Error | null;
|
|
1495
|
+
refetch: () => Promise<void>;
|
|
1496
|
+
}
|
|
1497
|
+
/**
|
|
1498
|
+
* One person's detail (GET /api/v1/people/{email}): customer record, orders,
|
|
1499
|
+
* and form submissions. Pass `null` to skip fetching (e.g. an anonymous
|
|
1500
|
+
* submission row, which has no email to look up).
|
|
1501
|
+
*/
|
|
1502
|
+
declare function usePerson(email: string | null, { refreshKey }?: UsePersonOptions): UsePersonReturn;
|
|
1503
|
+
|
|
1504
|
+
declare function isZeroDecimalCurrency(currency: string): boolean;
|
|
1505
|
+
/**
|
|
1506
|
+
* Format a minor-unit amount for display ("$29.00", "¥1,500").
|
|
1507
|
+
* Zero-decimal currencies (JPY, KRW, …) pass through; others divide by 100.
|
|
1508
|
+
* Uses the browser locale unless one is given. Display only — never feed the
|
|
1509
|
+
* result back into money math.
|
|
1510
|
+
*/
|
|
1511
|
+
declare function formatPrice(amount: number, currency: string, locale?: string): string;
|
|
1512
|
+
/**
|
|
1513
|
+
* What the buyer's card was actually charged: goods (`amount_total`) plus
|
|
1514
|
+
* postage (`shipping_total`). The API keeps the two apart because the platform
|
|
1515
|
+
* fee base is pinned to the goods figure, so `amount_total` alone UNDER-states
|
|
1516
|
+
* every shipped order — a merchant reconciling a Stripe payout against it
|
|
1517
|
+
* would see a smaller number than the one Stripe moved.
|
|
1518
|
+
*
|
|
1519
|
+
* One definition, because the same sum drives the order list, the customer's
|
|
1520
|
+
* order history, the detail panel and the refund ceiling; four copies of
|
|
1521
|
+
* `a + (b ?? 0)` is exactly how one of them gets missed.
|
|
1522
|
+
*
|
|
1523
|
+
* A null `shipping_total` means UNRECORDED (including every order that
|
|
1524
|
+
* predates shipping rates), so it reads as 0 — the same coalesce the server
|
|
1525
|
+
* makes, and the same direction of error.
|
|
1526
|
+
*/
|
|
1527
|
+
declare function chargedTotal(order: {
|
|
1528
|
+
amount_total: number;
|
|
1529
|
+
shipping_total?: number | null;
|
|
1530
|
+
tax_total?: number;
|
|
1531
|
+
tax_behavior?: 'inclusive' | 'exclusive' | null;
|
|
1532
|
+
automatic_tax?: boolean;
|
|
1533
|
+
}): number;
|
|
1534
|
+
/**
|
|
1535
|
+
* Convert a major-unit amount ("29.99") to the currency's integer minor unit
|
|
1536
|
+
* (2999). Zero-decimal currencies pass through. Returns null for values that
|
|
1537
|
+
* don't parse to a finite non-negative number.
|
|
1538
|
+
*/
|
|
1539
|
+
declare function toMinorUnits(major: string | number, currency: string): number | null;
|
|
1540
|
+
/**
|
|
1541
|
+
* Convert a minor-unit amount (2999) to a major-unit number (29.99) for
|
|
1542
|
+
* editing in inputs. Display formatting should use formatPrice instead.
|
|
1543
|
+
*/
|
|
1544
|
+
declare function toMajorUnits(minor: number, currency: string): number;
|
|
1545
|
+
|
|
1546
|
+
export { type AdjustInventoryInput, type AifeaturesApiClient, AifeaturesApiError, type AifeaturesContextValue, AifeaturesProvider, type AifeaturesProviderProps, type ApiError, type Attachment, type BusinessSummary, type CreateFormInput, type CreateOptionInput, type CreateProductInput, type CreateVariantInput, type Customer, type CustomerAddress, CustomerDetail, type CustomerDetail$1 as CustomerDetailData, type CustomerDetailProps, CustomersList, type CustomersListProps, type CustomersListResponse, type EmailSideStatus, type Form, FormSettings, type FormSettingsProps, FormSubmissions, type FormSubmissionsProps, FormsDashboard, type FormsDashboardProps, FormsList, type FormsListProps, type FormsListResponse, type GetBusinessSummaryOptions, type GetCustomersOptions, type GetOrdersOptions, type GetPeopleOptions, type GetProductsOptions, type GetSubmissionsOptions, LeadsView, type LeadsViewProps, type LowStockProduct, type NeedsAttentionItem, type NeedsAttentionType, type Order, OrderDetail, type OrderDetailProps, type OrderStatus, OrderStatusBadge, OrdersList, type OrdersListProps, OrdersView, type OrdersViewProps, type PaginatedOrders, type PaginatedSubmissions, PaymentsDashboard, type PaymentsDashboardProps, PaymentsSetup, type PaymentsSetupProps, type PaymentsStatus, type PaymentsStatusReason, type PaymentsStatusResponse, type PeopleListResponse, type Person, type PersonDetail, type PersonOrder, type PersonSource, type PersonSubmission, type Product, type ProductDetail, type ProductFulfillment, type ProductFulfillmentType, type ProductOption, ProductSettings, type ProductSettingsProps, type ProductStats, type ProductVariant, ProductsList, type ProductsListProps, type ProductsListResponse, ProductsView, type ProductsViewProps, type RefundRequest, type RevenueCurrencyTotal, type RevenuePeriod, type SetInventoryInput, type SetOrderFulfillmentInput, type SettledRevenue, type Submission, SubmissionDetail, type SubmissionDetailProps, type SubmissionMetadata, type UpdateFormInput, type UpdateOptionInput, type UpdateProductInput, type UpdateVariantInput, type UseBusinessSummaryOptions, type UseBusinessSummaryReturn, type UseCustomersOptions, type UseCustomersReturn, type UseFormsReturn, type UseOrdersOptions, type UseOrdersReturn, type UsePaymentsStatusReturn, type UsePeopleOptions, type UsePeopleReturn, type UsePersonOptions, type UsePersonReturn, type UseProductsOptions, type UseProductsReturn, type UseSubmissionsOptions, type UseSubmissionsReturn, type VariantInventory, type VariantOptionValue, VariantsEditor, type VariantsEditorProps, ViewShell, type ViewShellProps, chargedTotal, createApiClient, formatPrice, isZeroDecimalCurrency, toMajorUnits, toMinorUnits, useAifeaturesContext as useAifeatures, useAifeaturesContext, useBusinessSummary, useCustomers, useForms, useOrders, usePaymentsStatus, usePeople, usePerson, useProducts, useSubmissions };
|