@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.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, filename: string): Promise<void>;
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
- export { type AifeaturesApiClient, AifeaturesApiError, type AifeaturesContextValue, AifeaturesProvider, type AifeaturesProviderProps, type ApiError, type Attachment, type CreateFormInput, type Form, FormSettings, type FormSettingsProps, FormSubmissions, type FormSubmissionsProps, FormsDashboard, type FormsDashboardProps, FormsList, type FormsListProps, type FormsListResponse, type GetSubmissionsOptions, type PaginatedSubmissions, type Submission, SubmissionDetail, type SubmissionDetailProps, type SubmissionMetadata, type UpdateFormInput, type UseFormsReturn, type UseSubmissionsOptions, type UseSubmissionsReturn, createApiClient, useAifeaturesContext as useAifeatures, useAifeaturesContext, useForms, useSubmissions };
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 };