@aifeatures/admin-react 0.5.5 → 0.7.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 +4 -3
- package/dist/index.d.cts +849 -5
- package/dist/index.d.ts +849 -5
- package/dist/index.js +4 -3
- package/dist/styles.css +1 -1
- package/package.json +7 -2
package/dist/index.d.cts
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
2
2
|
import * as React from 'react';
|
|
3
3
|
|
|
4
|
+
/** Latest send attempt per kind; delivered means accepted by the recipient's mail server. */
|
|
5
|
+
interface EmailDelivery {
|
|
6
|
+
id: string;
|
|
7
|
+
kind: string;
|
|
8
|
+
recipients: string[];
|
|
9
|
+
state: 'sending' | 'sent' | 'delivered' | 'delivery_delayed' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'unknown';
|
|
10
|
+
created_at: string;
|
|
11
|
+
updated_at: string;
|
|
12
|
+
}
|
|
4
13
|
/**
|
|
5
14
|
* Form object from aifeatures API
|
|
6
15
|
*/
|
|
@@ -40,6 +49,7 @@ interface SubmissionMetadata {
|
|
|
40
49
|
* Form submission object from aifeatures API
|
|
41
50
|
*/
|
|
42
51
|
interface Submission {
|
|
52
|
+
email_deliveries?: EmailDelivery[];
|
|
43
53
|
id: string;
|
|
44
54
|
form_id: string;
|
|
45
55
|
data: Record<string, unknown>;
|
|
@@ -91,6 +101,16 @@ interface GetSubmissionsOptions {
|
|
|
91
101
|
interface ApiError {
|
|
92
102
|
error: string;
|
|
93
103
|
message?: string;
|
|
104
|
+
/**
|
|
105
|
+
* A machine-readable reason, when the failure is an EXPECTED consequence of
|
|
106
|
+
* the request rather than a fault.
|
|
107
|
+
*
|
|
108
|
+
* `filter_unsupported` is the one that matters to the panel: the filter
|
|
109
|
+
* cannot be answered for this site and period, which is a thing the merchant
|
|
110
|
+
* can act on. Rendering it as "we can't reach analytics" strands them with a
|
|
111
|
+
* filter applied, every report gone, and a Retry that repeats the failure.
|
|
112
|
+
*/
|
|
113
|
+
code?: 'filter_unsupported';
|
|
94
114
|
}
|
|
95
115
|
/**
|
|
96
116
|
* A site's payment readiness (sites.paymentsStatus)
|
|
@@ -390,7 +410,15 @@ interface UpdateProductInput {
|
|
|
390
410
|
/**
|
|
391
411
|
* An order's lifecycle state
|
|
392
412
|
*/
|
|
393
|
-
type OrderStatus = "pending" | "paid" | "failed" | "expired" | "refunded" | "partially_refunded" | "disputed"
|
|
413
|
+
type OrderStatus = "pending" | "paid" | "failed" | "expired" | "refunded" | "partially_refunded" | "disputed"
|
|
414
|
+
/** Invoice orders only: cancelled before it was paid. */
|
|
415
|
+
| "voided";
|
|
416
|
+
/**
|
|
417
|
+
* Where an order came from. `invoice` rows (one-off invoices and retainer
|
|
418
|
+
* cycles) are a different surface — the Invoices view — and are excluded
|
|
419
|
+
* from the Orders list unless asked for by `source`.
|
|
420
|
+
*/
|
|
421
|
+
type OrderSource = "checkout" | "subscription" | "invoice";
|
|
394
422
|
/**
|
|
395
423
|
* Delivery state of ONE side of an order's emails — the buyer receipt or the
|
|
396
424
|
* merchant sale notification. The two sides are tracked, retried and reported
|
|
@@ -464,6 +492,7 @@ interface LineItem {
|
|
|
464
492
|
* currency's minor unit.
|
|
465
493
|
*/
|
|
466
494
|
interface Order {
|
|
495
|
+
email_deliveries?: EmailDelivery[];
|
|
467
496
|
id: string;
|
|
468
497
|
/**
|
|
469
498
|
* The merchant-facing order number (`#1042`) — a per-site sequence assigned
|
|
@@ -585,6 +614,11 @@ interface PaginatedOrders {
|
|
|
585
614
|
*/
|
|
586
615
|
interface GetOrdersOptions {
|
|
587
616
|
status?: OrderStatus;
|
|
617
|
+
/**
|
|
618
|
+
* Restrict to one source. Omitted = checkout + subscription orders (the
|
|
619
|
+
* API's default — invoices live in the Invoices view); `all` = everything.
|
|
620
|
+
*/
|
|
621
|
+
source?: OrderSource | "all";
|
|
588
622
|
/**
|
|
589
623
|
* Statuses to omit. Used to keep abandoned checkouts
|
|
590
624
|
* (`pending` → swept to `expired`) out of the default order view — neither
|
|
@@ -628,6 +662,10 @@ interface Customer {
|
|
|
628
662
|
metadata: Record<string, unknown>;
|
|
629
663
|
created_at: string;
|
|
630
664
|
updated_at: string;
|
|
665
|
+
/** Remembered language for this customer's invoices and receipts. */
|
|
666
|
+
locale?: string | null;
|
|
667
|
+
/** Remembered bill-to identity (company, name, address, tax id, PO). */
|
|
668
|
+
bill_to?: InvoiceBillTo | null;
|
|
631
669
|
}
|
|
632
670
|
/** A saved address on a customer. */
|
|
633
671
|
interface CustomerAddress {
|
|
@@ -643,6 +681,7 @@ interface CustomerAddress {
|
|
|
643
681
|
}
|
|
644
682
|
/** Customer detail = the customer plus addresses and their order count. */
|
|
645
683
|
interface CustomerDetail$1 extends Customer {
|
|
684
|
+
email_deliveries?: EmailDelivery[];
|
|
646
685
|
addresses: CustomerAddress[];
|
|
647
686
|
order_count: number;
|
|
648
687
|
}
|
|
@@ -657,6 +696,8 @@ interface CustomersListResponse {
|
|
|
657
696
|
interface GetCustomersOptions {
|
|
658
697
|
/** Exact-match email filter (case-insensitive) */
|
|
659
698
|
email?: string;
|
|
699
|
+
/** Case-insensitive substring on email or name (ignored when `email` is set). */
|
|
700
|
+
q?: string;
|
|
660
701
|
limit?: number;
|
|
661
702
|
offset?: number;
|
|
662
703
|
}
|
|
@@ -708,9 +749,32 @@ interface LowStockProduct {
|
|
|
708
749
|
/** Units still available on the lowest tracked variant. */
|
|
709
750
|
available: number;
|
|
710
751
|
}
|
|
752
|
+
/**
|
|
753
|
+
* The Overview hero tile: a 7-day visitor count with a sparkline.
|
|
754
|
+
*
|
|
755
|
+
* Null when the site has no analytics id or the source is unreachable — a
|
|
756
|
+
* traffic outage costs this tile and nothing else on the summary.
|
|
757
|
+
*/
|
|
758
|
+
interface BusinessVisitors {
|
|
759
|
+
/**
|
|
760
|
+
* DISTINCT visitors across the window, NOT the sum of `sparkline`: someone
|
|
761
|
+
* who visited on two days is one visitor and two daily buckets.
|
|
762
|
+
*/
|
|
763
|
+
d7: number;
|
|
764
|
+
/** One entry per local day, zero-filled — quiet days are present, not omitted. */
|
|
765
|
+
sparkline: {
|
|
766
|
+
date: string;
|
|
767
|
+
visitors: number;
|
|
768
|
+
}[];
|
|
769
|
+
/** The same window `GET /analytics/summary?period=7` resolves. */
|
|
770
|
+
window: {
|
|
771
|
+
from: string;
|
|
772
|
+
to: string;
|
|
773
|
+
};
|
|
774
|
+
}
|
|
711
775
|
/**
|
|
712
776
|
* Response from GET /api/v1/summary — the merchant's one-look business
|
|
713
|
-
* rollup.
|
|
777
|
+
* rollup.
|
|
714
778
|
*/
|
|
715
779
|
interface BusinessSummary {
|
|
716
780
|
site_id: string;
|
|
@@ -728,7 +792,7 @@ interface BusinessSummary {
|
|
|
728
792
|
count: number;
|
|
729
793
|
low_stock: LowStockProduct[];
|
|
730
794
|
};
|
|
731
|
-
visitors: null;
|
|
795
|
+
visitors: BusinessVisitors | null;
|
|
732
796
|
}
|
|
733
797
|
/** Options for fetching the business summary. */
|
|
734
798
|
interface GetBusinessSummaryOptions {
|
|
@@ -837,6 +901,7 @@ interface PersonDetail {
|
|
|
837
901
|
* dashboard's site token cannot call them.
|
|
838
902
|
*/
|
|
839
903
|
interface Subscription {
|
|
904
|
+
email_deliveries?: EmailDelivery[];
|
|
840
905
|
id: string;
|
|
841
906
|
/**
|
|
842
907
|
* Mirrored Stripe status, stored VERBATIM — a full-Dashboard merchant can
|
|
@@ -962,6 +1027,408 @@ interface EventDelivery {
|
|
|
962
1027
|
interface EventDeliveriesListResponse {
|
|
963
1028
|
deliveries: EventDelivery[];
|
|
964
1029
|
}
|
|
1030
|
+
type InvoiceLabel = "creating" | "failed" | "awaiting_payment" | "overdue" | "payment_processing" | "awaiting_authentication" | "paid" | "paid_outside_stripe" | "paid_by_credit" | "partially_refunded" | "refunded" | "disputed" | "voided" | "uncollectible";
|
|
1031
|
+
type InvoiceDeliveryState = "queued" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "unknown";
|
|
1032
|
+
interface InvoiceLineItem {
|
|
1033
|
+
description: string;
|
|
1034
|
+
quantity: number;
|
|
1035
|
+
/** Line total, minor units. */
|
|
1036
|
+
amount: number;
|
|
1037
|
+
}
|
|
1038
|
+
interface InvoiceBillTo {
|
|
1039
|
+
company?: string | null;
|
|
1040
|
+
name?: string | null;
|
|
1041
|
+
address?: {
|
|
1042
|
+
line1?: string | null;
|
|
1043
|
+
line2?: string | null;
|
|
1044
|
+
city?: string | null;
|
|
1045
|
+
state?: string | null;
|
|
1046
|
+
postal_code?: string | null;
|
|
1047
|
+
country?: string | null;
|
|
1048
|
+
} | null;
|
|
1049
|
+
tax_id?: {
|
|
1050
|
+
type: string;
|
|
1051
|
+
value: string;
|
|
1052
|
+
} | null;
|
|
1053
|
+
po_number?: string | null;
|
|
1054
|
+
service_period?: string | null;
|
|
1055
|
+
}
|
|
1056
|
+
interface Invoice {
|
|
1057
|
+
id: string;
|
|
1058
|
+
invoice_number: string | null;
|
|
1059
|
+
status: OrderStatus;
|
|
1060
|
+
label: InvoiceLabel;
|
|
1061
|
+
days_overdue: number | null;
|
|
1062
|
+
customer_id: string | null;
|
|
1063
|
+
customer_email: string | null;
|
|
1064
|
+
customer_name: string | null;
|
|
1065
|
+
currency: string;
|
|
1066
|
+
amount_subtotal: number;
|
|
1067
|
+
tax_total: number;
|
|
1068
|
+
/** Whether tax is already inside the subtotal, or charged on top. */
|
|
1069
|
+
tax_behavior?: "inclusive" | "exclusive" | null;
|
|
1070
|
+
/** Discount already reflected in amount_total (minor currency units). */
|
|
1071
|
+
discount_total?: number;
|
|
1072
|
+
/** The charged total — subtotal less discounts, plus tax when added on top. */
|
|
1073
|
+
amount_total: number;
|
|
1074
|
+
credit_applied: number;
|
|
1075
|
+
amount_due: number | null;
|
|
1076
|
+
amount_paid: number | null;
|
|
1077
|
+
amount_paid_off_stripe: number;
|
|
1078
|
+
amount_refunded: number;
|
|
1079
|
+
line_items: InvoiceLineItem[];
|
|
1080
|
+
note: string | null;
|
|
1081
|
+
footer: string | null;
|
|
1082
|
+
bill_to: InvoiceBillTo | null;
|
|
1083
|
+
locale: string | null;
|
|
1084
|
+
due_at: string | null;
|
|
1085
|
+
created_at: string;
|
|
1086
|
+
paid_at: string | null;
|
|
1087
|
+
payment_state: string;
|
|
1088
|
+
payment_method: string | null;
|
|
1089
|
+
paid_out_of_band: boolean;
|
|
1090
|
+
paid_by_credit: boolean;
|
|
1091
|
+
marked_uncollectible_at: string | null;
|
|
1092
|
+
reminders: {
|
|
1093
|
+
schedule: number[];
|
|
1094
|
+
disabled: boolean;
|
|
1095
|
+
count: number;
|
|
1096
|
+
next_at: string | null;
|
|
1097
|
+
paused_until: string | null;
|
|
1098
|
+
final_sent_at: string | null;
|
|
1099
|
+
};
|
|
1100
|
+
delivery: {
|
|
1101
|
+
state: InvoiceDeliveryState;
|
|
1102
|
+
at: string | null;
|
|
1103
|
+
recipient: string;
|
|
1104
|
+
kind: string;
|
|
1105
|
+
} | null;
|
|
1106
|
+
pay_url: string | null;
|
|
1107
|
+
pdf_url: string | null;
|
|
1108
|
+
payment_methods: Array<"card" | "bank" | "link"> | null;
|
|
1109
|
+
replaces_order_id: string | null;
|
|
1110
|
+
replaced_by_order_id: string | null;
|
|
1111
|
+
correction_reason: string | null;
|
|
1112
|
+
retainer_id: string | null;
|
|
1113
|
+
collection_method?: "send_invoice" | "charge_automatically";
|
|
1114
|
+
operation: {
|
|
1115
|
+
step: string;
|
|
1116
|
+
last_error: string | null;
|
|
1117
|
+
attempts: number;
|
|
1118
|
+
} | null;
|
|
1119
|
+
stripe_invoice_id: string | null;
|
|
1120
|
+
/** Every refund on this invoice and the Stripe credit note that mirrors it (null id while the note is still being created). */
|
|
1121
|
+
credit_notes: InvoiceCreditNote[];
|
|
1122
|
+
/** GET /invoices/{id} only: every buyer-facing send, oldest first, with its delivery state. */
|
|
1123
|
+
communications?: InvoiceCommunication[];
|
|
1124
|
+
}
|
|
1125
|
+
interface InvoiceCreditNote {
|
|
1126
|
+
id: string;
|
|
1127
|
+
stripe_credit_note_id: string | null;
|
|
1128
|
+
stripe_refund_id: string;
|
|
1129
|
+
amount: number;
|
|
1130
|
+
currency: string;
|
|
1131
|
+
origin: "api" | "dashboard";
|
|
1132
|
+
created_at: string;
|
|
1133
|
+
}
|
|
1134
|
+
interface InvoiceCommunication {
|
|
1135
|
+
id: string;
|
|
1136
|
+
/** invoice_sent | reminder | void | receipt */
|
|
1137
|
+
kind: string;
|
|
1138
|
+
slot: number | null;
|
|
1139
|
+
recipient: string;
|
|
1140
|
+
state: InvoiceDeliveryState;
|
|
1141
|
+
state_at: string | null;
|
|
1142
|
+
error: string | null;
|
|
1143
|
+
created_at: string;
|
|
1144
|
+
}
|
|
1145
|
+
interface InvoiceAggregates {
|
|
1146
|
+
currency: string;
|
|
1147
|
+
outstanding: {
|
|
1148
|
+
amount: number;
|
|
1149
|
+
count: number;
|
|
1150
|
+
};
|
|
1151
|
+
overdue: {
|
|
1152
|
+
amount: number;
|
|
1153
|
+
count: number;
|
|
1154
|
+
};
|
|
1155
|
+
paid_this_month: {
|
|
1156
|
+
amount: number;
|
|
1157
|
+
count: number;
|
|
1158
|
+
};
|
|
1159
|
+
}
|
|
1160
|
+
interface PaginatedInvoices {
|
|
1161
|
+
invoices: Invoice[];
|
|
1162
|
+
total: number;
|
|
1163
|
+
limit: number;
|
|
1164
|
+
offset: number;
|
|
1165
|
+
aggregates?: InvoiceAggregates;
|
|
1166
|
+
}
|
|
1167
|
+
interface GetInvoicesOptions {
|
|
1168
|
+
/** Derived labels to keep (sent comma-separated). */
|
|
1169
|
+
labels?: InvoiceLabel[];
|
|
1170
|
+
customerEmail?: string;
|
|
1171
|
+
customerId?: string;
|
|
1172
|
+
/** Case-insensitive substring on the invoice number, the recipient's name or email. */
|
|
1173
|
+
q?: string;
|
|
1174
|
+
from?: string;
|
|
1175
|
+
to?: string;
|
|
1176
|
+
includeAggregates?: boolean;
|
|
1177
|
+
/** Only the cycles of one retainer. */
|
|
1178
|
+
retainerId?: string;
|
|
1179
|
+
limit?: number;
|
|
1180
|
+
offset?: number;
|
|
1181
|
+
}
|
|
1182
|
+
interface InvoiceSettings {
|
|
1183
|
+
due_days: number;
|
|
1184
|
+
reminder_schedule: number[];
|
|
1185
|
+
footer: string | null;
|
|
1186
|
+
locale: string | null;
|
|
1187
|
+
timezone: string | null;
|
|
1188
|
+
blocked: {
|
|
1189
|
+
at: string;
|
|
1190
|
+
reason: string | null;
|
|
1191
|
+
} | null;
|
|
1192
|
+
budget: {
|
|
1193
|
+
per_hour: number;
|
|
1194
|
+
per_day: number;
|
|
1195
|
+
};
|
|
1196
|
+
payments_active: boolean;
|
|
1197
|
+
}
|
|
1198
|
+
interface InvoicePreview {
|
|
1199
|
+
subject: string;
|
|
1200
|
+
html: string;
|
|
1201
|
+
text: string;
|
|
1202
|
+
from: string;
|
|
1203
|
+
reply_to: string | null;
|
|
1204
|
+
}
|
|
1205
|
+
type RetainerStatus = "creating" | "active" | "paused" | "canceling" | "canceled" | "failed";
|
|
1206
|
+
type RetainerPauseReason = "merchant" | "plan" | "suspension";
|
|
1207
|
+
/** A recurring invoice: one Stripe subscription, one unpaid invoice order per cycle. */
|
|
1208
|
+
interface Retainer {
|
|
1209
|
+
id: string;
|
|
1210
|
+
customer_id: string | null;
|
|
1211
|
+
customer_email: string | null;
|
|
1212
|
+
customer_name: string | null;
|
|
1213
|
+
description: string;
|
|
1214
|
+
/** Per cycle, minor units. */
|
|
1215
|
+
amount: number;
|
|
1216
|
+
currency: string;
|
|
1217
|
+
interval: "month" | "year";
|
|
1218
|
+
/** Day of the month each cycle bills on; null = the creation day. */
|
|
1219
|
+
anchor_day: number | null;
|
|
1220
|
+
days_until_due: number;
|
|
1221
|
+
locale: string | null;
|
|
1222
|
+
bill_to: InvoiceBillTo | null;
|
|
1223
|
+
status: RetainerStatus;
|
|
1224
|
+
/** Every reason it is paused; it resumes only when this is empty. */
|
|
1225
|
+
paused_by: RetainerPauseReason[];
|
|
1226
|
+
skip_next_cycle: boolean;
|
|
1227
|
+
next_cycle_at: string | null;
|
|
1228
|
+
cycles: {
|
|
1229
|
+
count: number;
|
|
1230
|
+
open: number;
|
|
1231
|
+
paid: number;
|
|
1232
|
+
};
|
|
1233
|
+
stripe_subscription_id: string | null;
|
|
1234
|
+
collection_method?: "send_invoice" | "charge_automatically";
|
|
1235
|
+
created_at: string;
|
|
1236
|
+
canceled_at: string | null;
|
|
1237
|
+
operation: {
|
|
1238
|
+
step: string;
|
|
1239
|
+
last_error: string | null;
|
|
1240
|
+
attempts: number;
|
|
1241
|
+
} | null;
|
|
1242
|
+
}
|
|
1243
|
+
interface PaginatedRetainers {
|
|
1244
|
+
retainers: Retainer[];
|
|
1245
|
+
total: number;
|
|
1246
|
+
limit: number;
|
|
1247
|
+
offset: number;
|
|
1248
|
+
}
|
|
1249
|
+
interface GetRetainersOptions {
|
|
1250
|
+
statuses?: RetainerStatus[];
|
|
1251
|
+
customerEmail?: string;
|
|
1252
|
+
limit?: number;
|
|
1253
|
+
offset?: number;
|
|
1254
|
+
}
|
|
1255
|
+
/**
|
|
1256
|
+
* Every analytics report is wrapped so an unreachable SOURCE is a value, not a
|
|
1257
|
+
* thrown error. The panel must render that state rather than zeros: zeros say
|
|
1258
|
+
* "no traffic", which is a different and much worse claim than "we could not
|
|
1259
|
+
* ask". One card failing therefore never blanks the panel (R7).
|
|
1260
|
+
*/
|
|
1261
|
+
type AnalyticsSourced<T> = {
|
|
1262
|
+
status: 'ok';
|
|
1263
|
+
data: T;
|
|
1264
|
+
window: {
|
|
1265
|
+
from: string;
|
|
1266
|
+
to: string;
|
|
1267
|
+
};
|
|
1268
|
+
} | {
|
|
1269
|
+
status: 'unreachable';
|
|
1270
|
+
};
|
|
1271
|
+
/** Days a report covers. Presets only, per R4. */
|
|
1272
|
+
type AnalyticsPeriod = 7 | 30 | 90;
|
|
1273
|
+
interface AnalyticsStatus {
|
|
1274
|
+
/** False means no analytics identity: nothing will EVER arrive for this site. */
|
|
1275
|
+
collecting: boolean;
|
|
1276
|
+
analytics_id: string | null;
|
|
1277
|
+
/** Always a usable IANA zone; UTC when the site has none stored. */
|
|
1278
|
+
timezone: string;
|
|
1279
|
+
/** True when the zone above is the UTC fallback, not a merchant's choice. */
|
|
1280
|
+
timezone_defaulted: boolean;
|
|
1281
|
+
/** Earliest event ever recorded, or null if nothing has been collected. */
|
|
1282
|
+
first_seen: string | null;
|
|
1283
|
+
/**
|
|
1284
|
+
* True when the first-seen LOOKUP failed, so `first_seen` is null because we
|
|
1285
|
+
* could not ask — not because nothing has arrived. Never treat a null
|
|
1286
|
+
* `first_seen` as "no traffic yet" without checking this first.
|
|
1287
|
+
*/
|
|
1288
|
+
first_seen_unavailable?: boolean;
|
|
1289
|
+
/**
|
|
1290
|
+
* Whether the first recorded event is inside the window the reports cover.
|
|
1291
|
+
* Optional: an older API does not send it, and its ABSENCE must never be
|
|
1292
|
+
* read as false — that would hide a working panel behind the first-day
|
|
1293
|
+
* screen for every site.
|
|
1294
|
+
*/
|
|
1295
|
+
first_seen_in_reports?: boolean;
|
|
1296
|
+
}
|
|
1297
|
+
interface AnalyticsSummaryMetrics {
|
|
1298
|
+
visitors: number;
|
|
1299
|
+
visits: number;
|
|
1300
|
+
pageviews: number;
|
|
1301
|
+
views_per_visit: number;
|
|
1302
|
+
/** Fraction in [0,1]. */
|
|
1303
|
+
bounce_rate: number;
|
|
1304
|
+
visit_duration_seconds: number;
|
|
1305
|
+
}
|
|
1306
|
+
interface AnalyticsSummaryData {
|
|
1307
|
+
current: AnalyticsSummaryMetrics;
|
|
1308
|
+
/** Null when the previous window is not fully covered by collection (R15). */
|
|
1309
|
+
previous: AnalyticsSummaryMetrics | null;
|
|
1310
|
+
/**
|
|
1311
|
+
* True when the comparison could not be COMPUTED, rather than not existing.
|
|
1312
|
+
*
|
|
1313
|
+
* A channel filter resolves per window, so the previous one can hold more
|
|
1314
|
+
* distinct acquisition tuples than can be resolved while the current one is
|
|
1315
|
+
* fine. The current reports are then perfectly good and only the delta is
|
|
1316
|
+
* lost — which is why this does not fail the panel. Null `previous` alone
|
|
1317
|
+
* cannot say that: it already means "deliberately not comparable".
|
|
1318
|
+
*/
|
|
1319
|
+
previous_unavailable?: boolean;
|
|
1320
|
+
/**
|
|
1321
|
+
* WHY it could not be computed, when it could not.
|
|
1322
|
+
*
|
|
1323
|
+
* `coverage` is an outage — the first-seen lookup failed, so whether the
|
|
1324
|
+
* previous window is covered is unknown, and it will pass. `filter` will
|
|
1325
|
+
* not: the previous window holds more distinct traffic sources than a
|
|
1326
|
+
* channel filter can resolve there, until the period is narrowed or the
|
|
1327
|
+
* filter changed. The two suggest different actions, so one sentence for
|
|
1328
|
+
* both names a cause that may not apply.
|
|
1329
|
+
*/
|
|
1330
|
+
previous_unavailable_reason?: 'coverage' | 'filter';
|
|
1331
|
+
}
|
|
1332
|
+
interface AnalyticsTimeseriesRow {
|
|
1333
|
+
date: string;
|
|
1334
|
+
visitors: number;
|
|
1335
|
+
visits: number;
|
|
1336
|
+
pageviews: number;
|
|
1337
|
+
/**
|
|
1338
|
+
* Pageviews per visit over the visits this day OWNS — deliberately not
|
|
1339
|
+
* `pageviews / visits` from this same row. `pageviews` is event-scoped and
|
|
1340
|
+
* includes pageviews belonging to a visit that started the day before, so
|
|
1341
|
+
* the two adjacent fields describe different sets of visits and dividing
|
|
1342
|
+
* them averages a numerator and denominator that do not correspond.
|
|
1343
|
+
*/
|
|
1344
|
+
views_per_visit: number;
|
|
1345
|
+
/** Fraction in [0,1] of the day's visits that saw a single page. */
|
|
1346
|
+
bounce_rate: number;
|
|
1347
|
+
/** Mean visit length in seconds over the visits this day owns. */
|
|
1348
|
+
visit_duration_seconds: number;
|
|
1349
|
+
}
|
|
1350
|
+
/**
|
|
1351
|
+
* Channels carry VISITS only. Visitor counts are computed per acquisition
|
|
1352
|
+
* tuple upstream, so they do not sum across the tuples that fold into one
|
|
1353
|
+
* channel — offering a visitors number here would be offering an overcount.
|
|
1354
|
+
*/
|
|
1355
|
+
interface AnalyticsChannelRow {
|
|
1356
|
+
channel: string;
|
|
1357
|
+
visits: number;
|
|
1358
|
+
}
|
|
1359
|
+
/**
|
|
1360
|
+
* A breakdown row. The dimension key varies by report (`source`, `pathname`,
|
|
1361
|
+
* `country`…) and is nullable, because a dimension that was never set stays
|
|
1362
|
+
* null on the wire — rendering it as "(none)" or "(not set)" is this layer's
|
|
1363
|
+
* decision, not the server's.
|
|
1364
|
+
*/
|
|
1365
|
+
/**
|
|
1366
|
+
* One ranked row. Values are the dimension plus its metrics, except `sources`.
|
|
1367
|
+
*
|
|
1368
|
+
* `sources` appears only on the Sources card, where the server folds the many
|
|
1369
|
+
* spellings of one platform into a single row (U15). It carries the RAW values
|
|
1370
|
+
* that folded in, because those are what the pipe stores — a click on "Google"
|
|
1371
|
+
* has to filter on `www.google.com`, `google.com` and the rest, or it asks a
|
|
1372
|
+
* question about a value that was never stored and matches nothing.
|
|
1373
|
+
*/
|
|
1374
|
+
type AnalyticsBreakdownRow = Record<string, string | number | null | string[]>;
|
|
1375
|
+
type AnalyticsSummary = AnalyticsSourced<AnalyticsSummaryData>;
|
|
1376
|
+
type AnalyticsTimeseries = AnalyticsSourced<AnalyticsTimeseriesRow[]> & {
|
|
1377
|
+
/**
|
|
1378
|
+
* The zone the dates are bucketed in, present on the OK branch. Read it from
|
|
1379
|
+
* here rather than from /status: the two are separate requests, and pairing
|
|
1380
|
+
* them means a status failure silently reburies the chart in UTC.
|
|
1381
|
+
*/
|
|
1382
|
+
timezone?: string;
|
|
1383
|
+
};
|
|
1384
|
+
type AnalyticsChannels = AnalyticsSourced<AnalyticsChannelRow[]>;
|
|
1385
|
+
type AnalyticsBreakdown = AnalyticsSourced<AnalyticsBreakdownRow[]>;
|
|
1386
|
+
/** Realtime sits outside the historical window, so it carries an as-of instant. */
|
|
1387
|
+
type AnalyticsRealtime = {
|
|
1388
|
+
status: 'ok';
|
|
1389
|
+
data: {
|
|
1390
|
+
current_visitors: number;
|
|
1391
|
+
};
|
|
1392
|
+
as_of: string;
|
|
1393
|
+
} | {
|
|
1394
|
+
status: 'unreachable';
|
|
1395
|
+
};
|
|
1396
|
+
/**
|
|
1397
|
+
* A drill-down filter (U13).
|
|
1398
|
+
*
|
|
1399
|
+
* Filters are ANDed with each other; `values` are ORed within one filter. The
|
|
1400
|
+
* SAME list must go to every report on the page — a filtered chart beside an
|
|
1401
|
+
* unfiltered tile is worse than no filtering at all, because the tiles are the
|
|
1402
|
+
* numbers a merchant quotes.
|
|
1403
|
+
*/
|
|
1404
|
+
interface AnalyticsFilter {
|
|
1405
|
+
dimension: AnalyticsFilterDimension;
|
|
1406
|
+
/** Defaults to `is` when omitted. */
|
|
1407
|
+
operator?: 'is' | 'is_not';
|
|
1408
|
+
values: string[];
|
|
1409
|
+
}
|
|
1410
|
+
/**
|
|
1411
|
+
* What a filter can be about.
|
|
1412
|
+
*
|
|
1413
|
+
* `channel` is here even though it is not a stored column: the server resolves
|
|
1414
|
+
* it against the window's real acquisition tuples with the same classifier the
|
|
1415
|
+
* Channels card uses, so a channel pill cannot select a different set than the
|
|
1416
|
+
* row it came from claimed.
|
|
1417
|
+
*/
|
|
1418
|
+
type AnalyticsFilterDimension = 'page' | 'entry_page' | 'exit_page' | 'country' | 'region' | 'city' | 'browser' | 'os' | 'device' | 'source' | 'campaign' | 'utm_source' | 'utm_medium' | 'utm_content' | 'utm_term' | 'channel';
|
|
1419
|
+
/** The server takes at most this many filters at once. */
|
|
1420
|
+
declare const MAX_ANALYTICS_FILTERS = 3;
|
|
1421
|
+
/**
|
|
1422
|
+
* Values one filter may carry, matching the server's own limit.
|
|
1423
|
+
*
|
|
1424
|
+
* The picker needs it because the remembered suggestion set deliberately
|
|
1425
|
+
* unions successive top-N responses and can therefore grow past it — and a
|
|
1426
|
+
* selection the server rejects fails EVERY report on the panel, not just the
|
|
1427
|
+
* filter.
|
|
1428
|
+
*/
|
|
1429
|
+
declare const MAX_ANALYTICS_FILTER_VALUES = 100;
|
|
1430
|
+
/** The breakdown reports the panel can ask for, by path segment. */
|
|
1431
|
+
type AnalyticsBreakdownName = 'sources' | 'campaigns' | 'utm/medium' | 'utm/source' | 'utm/campaign' | 'utm/content' | 'utm/term' | 'pages' | 'entry-pages' | 'exit-pages' | 'countries' | 'regions' | 'cities' | 'devices' | 'browsers' | 'operating-systems';
|
|
965
1432
|
|
|
966
1433
|
declare class AifeaturesApiError extends Error {
|
|
967
1434
|
status: number;
|
|
@@ -1002,6 +1469,14 @@ interface AifeaturesApiClient {
|
|
|
1002
1469
|
getOrder(orderId: string): Promise<Order>;
|
|
1003
1470
|
resendOrderReceipt(orderId: string): Promise<void>;
|
|
1004
1471
|
resetOrderDownloads(orderId: string): Promise<Order>;
|
|
1472
|
+
getInvoices(options?: GetInvoicesOptions): Promise<PaginatedInvoices>;
|
|
1473
|
+
getInvoice(invoiceId: string): Promise<Invoice>;
|
|
1474
|
+
/** The invoice email as it was (or would be) sent — from the recorded payload. */
|
|
1475
|
+
getInvoicePreview(invoiceId: string): Promise<InvoicePreview>;
|
|
1476
|
+
getInvoiceSettings(): Promise<InvoiceSettings>;
|
|
1477
|
+
/** Retainers — recurring invoices (read-only here, like invoices). */
|
|
1478
|
+
getRetainers(options?: GetRetainersOptions): Promise<PaginatedRetainers>;
|
|
1479
|
+
getRetainer(retainerId: string): Promise<Retainer>;
|
|
1005
1480
|
/**
|
|
1006
1481
|
* Mark the WHOLE order done (or un-mark it), optionally recording a
|
|
1007
1482
|
* tracking number. Merchant bookkeeping only — never moves money. The API
|
|
@@ -1016,6 +1491,30 @@ interface AifeaturesApiClient {
|
|
|
1016
1491
|
getPeople(options?: GetPeopleOptions): Promise<PeopleListResponse>;
|
|
1017
1492
|
/** Everything known about one person (customer record, orders, submissions). */
|
|
1018
1493
|
getPerson(email: string): Promise<PersonDetail>;
|
|
1494
|
+
/** Whether this site collects at all, its reporting zone, and first_seen. */
|
|
1495
|
+
getAnalyticsStatus(): Promise<AnalyticsStatus>;
|
|
1496
|
+
/**
|
|
1497
|
+
* Top-line metrics with the previous window for deltas.
|
|
1498
|
+
*
|
|
1499
|
+
* `filters` is optional on every report and must be the SAME list for all of
|
|
1500
|
+
* them on one page — see AnalyticsFilter.
|
|
1501
|
+
*/
|
|
1502
|
+
getAnalyticsSummary(period: AnalyticsPeriod, filters?: AnalyticsFilter[]): Promise<AnalyticsSummary>;
|
|
1503
|
+
/** Visitors by local day; days without traffic are omitted. */
|
|
1504
|
+
getAnalyticsTimeseries(period: AnalyticsPeriod, filters?: AnalyticsFilter[]): Promise<AnalyticsTimeseries>;
|
|
1505
|
+
/**
|
|
1506
|
+
* Visitors active in the last 5 minutes, with the instant it was taken.
|
|
1507
|
+
*
|
|
1508
|
+
* DELIBERATELY UNFILTERED. Realtime is a five-minute uniq with no
|
|
1509
|
+
* sessionization behind it, so a visit-scoped filter has nothing to apply
|
|
1510
|
+
* to; the pill says site-wide rather than quietly answering a different
|
|
1511
|
+
* question from the panel around it.
|
|
1512
|
+
*/
|
|
1513
|
+
getAnalyticsRealtime(): Promise<AnalyticsRealtime>;
|
|
1514
|
+
/** First-touch acquisition folded into channels. Visits, not visitors. */
|
|
1515
|
+
getAnalyticsChannels(period: AnalyticsPeriod, filters?: AnalyticsFilter[]): Promise<AnalyticsChannels>;
|
|
1516
|
+
/** One ranked breakdown, named by its path segment. */
|
|
1517
|
+
getAnalyticsBreakdown(name: AnalyticsBreakdownName, period: AnalyticsPeriod, filters?: AnalyticsFilter[]): Promise<AnalyticsBreakdown>;
|
|
1019
1518
|
getEventDestinations(): Promise<EventDestination[]>;
|
|
1020
1519
|
createEventDestination(input: CreateEventDestinationInput): Promise<EventDestination>;
|
|
1021
1520
|
updateEventDestination(destinationId: string, input: UpdateEventDestinationInput): Promise<EventDestination>;
|
|
@@ -1196,7 +1695,7 @@ interface PaymentsDashboardProps {
|
|
|
1196
1695
|
/** Optional className */
|
|
1197
1696
|
className?: string;
|
|
1198
1697
|
/** Which tab to open initially */
|
|
1199
|
-
defaultTab?: "products" | "orders" | "customers" | "setup";
|
|
1698
|
+
defaultTab?: "products" | "orders" | "invoices" | "customers" | "setup";
|
|
1200
1699
|
/**
|
|
1201
1700
|
* Host-app callback that starts (or resumes) Stripe Connect onboarding —
|
|
1202
1701
|
* shown on the Setup tab when the site still needs Stripe.
|
|
@@ -1533,6 +2032,88 @@ interface WebhookDeliveriesProps {
|
|
|
1533
2032
|
*/
|
|
1534
2033
|
declare function WebhookDeliveries({ destinationId, limit, className, }: WebhookDeliveriesProps): react_jsx_runtime.JSX.Element;
|
|
1535
2034
|
|
|
2035
|
+
declare function InvoiceLabelBadge({ invoice, className }: {
|
|
2036
|
+
invoice: Pick<Invoice, "label" | "days_overdue" | "collection_method">;
|
|
2037
|
+
className?: string;
|
|
2038
|
+
}): react_jsx_runtime.JSX.Element;
|
|
2039
|
+
interface InvoicesListProps {
|
|
2040
|
+
className?: string;
|
|
2041
|
+
/** Bump to refetch (view data freshness). */
|
|
2042
|
+
refreshKey?: number;
|
|
2043
|
+
/** Deep-open this invoice's detail on mount. */
|
|
2044
|
+
initialInvoiceId?: string;
|
|
2045
|
+
/** Tells the host when the detail is open (so its own back button steps aside). */
|
|
2046
|
+
onDetailOpenChange?: (open: boolean) => void;
|
|
2047
|
+
/** Host callback for the "Connect Stripe" empty state. */
|
|
2048
|
+
onConnectStripe?: () => void;
|
|
2049
|
+
/** Host callback for the "Upgrade" empty state. */
|
|
2050
|
+
onUpgradePlan?: () => void;
|
|
2051
|
+
/** The plan gate the host knows about; the view only renders the copy. */
|
|
2052
|
+
needsPaidPlan?: boolean;
|
|
2053
|
+
/** Show only one retainer's cycles (Unit 8b); the label names it in the chip. */
|
|
2054
|
+
retainerFilter?: {
|
|
2055
|
+
id: string;
|
|
2056
|
+
label: string;
|
|
2057
|
+
} | null;
|
|
2058
|
+
onClearRetainerFilter?: () => void;
|
|
2059
|
+
}
|
|
2060
|
+
declare function InvoicesList({ className, refreshKey, initialInvoiceId, onDetailOpenChange, onConnectStripe, onUpgradePlan, needsPaidPlan, retainerFilter, onClearRetainerFilter }: InvoicesListProps): react_jsx_runtime.JSX.Element;
|
|
2061
|
+
interface InvoiceDetailProps {
|
|
2062
|
+
invoice: Invoice;
|
|
2063
|
+
onBack: () => void;
|
|
2064
|
+
/** Bump to re-read the invoice (a chat mutation landed while the detail is open). */
|
|
2065
|
+
refreshKey?: number;
|
|
2066
|
+
className?: string;
|
|
2067
|
+
}
|
|
2068
|
+
declare function InvoiceDetail({ invoice: given, onBack, refreshKey, className }: InvoiceDetailProps): react_jsx_runtime.JSX.Element;
|
|
2069
|
+
|
|
2070
|
+
interface InvoicesViewProps {
|
|
2071
|
+
/** Bump to refetch everything on screen (view data freshness). */
|
|
2072
|
+
refreshKey?: number;
|
|
2073
|
+
/** Deep-open this invoice's detail on mount (`show_view` params.invoiceId). */
|
|
2074
|
+
initialInvoiceId?: string;
|
|
2075
|
+
/** Host-app callback that swaps the panel back to the website preview. */
|
|
2076
|
+
onBackToWebsite?: () => void;
|
|
2077
|
+
onConnectStripe?: InvoicesListProps["onConnectStripe"];
|
|
2078
|
+
onUpgradePlan?: InvoicesListProps["onUpgradePlan"];
|
|
2079
|
+
needsPaidPlan?: boolean;
|
|
2080
|
+
className?: string;
|
|
2081
|
+
}
|
|
2082
|
+
/**
|
|
2083
|
+
* InvoicesView — the merchant view the AI swaps in for "show me my invoices"
|
|
2084
|
+
* (agent-invoicing plan, Unit 8a). Three tiles (outstanding, overdue, paid
|
|
2085
|
+
* this month — in the site currency, recorded rows only), then the read-only
|
|
2086
|
+
* list and detail. Ephemeral like OrdersView: top-level list state on every
|
|
2087
|
+
* swap, except the deep-open.
|
|
2088
|
+
*/
|
|
2089
|
+
declare function InvoicesView({ refreshKey, initialInvoiceId, onBackToWebsite, onConnectStripe, onUpgradePlan, needsPaidPlan, className }: InvoicesViewProps): react_jsx_runtime.JSX.Element;
|
|
2090
|
+
|
|
2091
|
+
declare function RetainerStatusBadge({ retainer, className }: {
|
|
2092
|
+
retainer: Pick<Retainer, "status" | "paused_by" | "skip_next_cycle">;
|
|
2093
|
+
className?: string;
|
|
2094
|
+
}): react_jsx_runtime.JSX.Element;
|
|
2095
|
+
interface RetainersPanelProps {
|
|
2096
|
+
retainers: Retainer[];
|
|
2097
|
+
isLoading: boolean;
|
|
2098
|
+
error: Error | null;
|
|
2099
|
+
onRetry: () => void;
|
|
2100
|
+
/** Filter the invoice list below to this retainer's cycles. */
|
|
2101
|
+
onShowCycles: (retainer: Retainer) => void;
|
|
2102
|
+
/** The retainer whose cycles are on screen, if any. */
|
|
2103
|
+
activeRetainerId?: string | null;
|
|
2104
|
+
/** Rows matching the series on screen (the API's total); more than `retainers.length` means another page exists. */
|
|
2105
|
+
total?: number;
|
|
2106
|
+
/** Ended rows known to exist while the live series is empty (the hook's probe). */
|
|
2107
|
+
endedTotal?: number;
|
|
2108
|
+
isLoadingMore?: boolean;
|
|
2109
|
+
onLoadMore?: () => void;
|
|
2110
|
+
/** The series on screen: live only, or the ended ones too. Omit to hide the toggle. */
|
|
2111
|
+
includeEnded?: boolean;
|
|
2112
|
+
onIncludeEndedChange?: (includeEnded: boolean) => void;
|
|
2113
|
+
className?: string;
|
|
2114
|
+
}
|
|
2115
|
+
declare function RetainersPanel({ retainers, isLoading, error, onRetry, onShowCycles, activeRetainerId, total, endedTotal, isLoadingMore, onLoadMore, includeEnded, onIncludeEndedChange, className }: RetainersPanelProps): react_jsx_runtime.JSX.Element | null;
|
|
2116
|
+
|
|
1536
2117
|
interface UseFormsReturn {
|
|
1537
2118
|
forms: Form[];
|
|
1538
2119
|
isLoading: boolean;
|
|
@@ -1786,6 +2367,230 @@ interface UseEventDestinationsReturn {
|
|
|
1786
2367
|
}
|
|
1787
2368
|
declare function useEventDestinations(): UseEventDestinationsReturn;
|
|
1788
2369
|
|
|
2370
|
+
/**
|
|
2371
|
+
* The Invoices view's data (agent-invoicing plan, Unit 8a). Recorded rows
|
|
2372
|
+
* only — the API never calls Stripe for a list — with the derived labels the
|
|
2373
|
+
* API computes per row and the three tiles' aggregates.
|
|
2374
|
+
*/
|
|
2375
|
+
interface UseInvoicesReturn {
|
|
2376
|
+
invoices: Invoice[];
|
|
2377
|
+
total: number;
|
|
2378
|
+
aggregates: InvoiceAggregates | null;
|
|
2379
|
+
isLoading: boolean;
|
|
2380
|
+
error: Error | null;
|
|
2381
|
+
page: number;
|
|
2382
|
+
pageSize: number;
|
|
2383
|
+
hasNextPage: boolean;
|
|
2384
|
+
hasPreviousPage: boolean;
|
|
2385
|
+
setPage: (page: number) => void;
|
|
2386
|
+
setPageSize: (size: number) => void;
|
|
2387
|
+
/** Derived labels to keep (a saved view). Undefined = every invoice. Resets to the first page. */
|
|
2388
|
+
labels: InvoiceLabel[] | undefined;
|
|
2389
|
+
setLabels: (labels: InvoiceLabel[] | undefined) => void;
|
|
2390
|
+
/** Exact-match recipient email filter. Resets to the first page. */
|
|
2391
|
+
customerEmail: string;
|
|
2392
|
+
setCustomerEmail: (email: string) => void;
|
|
2393
|
+
/** Server-side substring search (invoice number, recipient name or email). Resets to the first page. */
|
|
2394
|
+
q: string;
|
|
2395
|
+
setQ: (q: string) => void;
|
|
2396
|
+
from: string;
|
|
2397
|
+
setFrom: (from: string) => void;
|
|
2398
|
+
to: string;
|
|
2399
|
+
setTo: (to: string) => void;
|
|
2400
|
+
/** Only the cycles of one retainer (Unit 8b). Empty = every invoice. Resets to the first page. */
|
|
2401
|
+
retainerId: string;
|
|
2402
|
+
setRetainerId: (retainerId: string) => void;
|
|
2403
|
+
clearFilters: () => void;
|
|
2404
|
+
refetch: () => Promise<void>;
|
|
2405
|
+
}
|
|
2406
|
+
interface UseInvoicesOptions {
|
|
2407
|
+
initialPageSize?: number;
|
|
2408
|
+
/** Bump to refetch with the current filters (view data freshness). */
|
|
2409
|
+
refreshKey?: number;
|
|
2410
|
+
/**
|
|
2411
|
+
* Ask the API for the three tiles' aggregates on every fetch. Off by
|
|
2412
|
+
* default: the list's own requests don't need them, and the view mounts a
|
|
2413
|
+
* separate one-row hook for the tiles (so a filter change never re-sums
|
|
2414
|
+
* the whole site).
|
|
2415
|
+
*/
|
|
2416
|
+
includeAggregates?: boolean;
|
|
2417
|
+
}
|
|
2418
|
+
declare function useInvoices({ initialPageSize, refreshKey, includeAggregates }?: UseInvoicesOptions): UseInvoicesReturn;
|
|
2419
|
+
|
|
2420
|
+
/**
|
|
2421
|
+
* The Invoices view's retainer series (agent-invoicing plan, Unit 8b).
|
|
2422
|
+
* Live retainers by default (creating / active / paused / canceling), paged
|
|
2423
|
+
* from the API and accumulated; `includeEnded` widens the series to the
|
|
2424
|
+
* canceled and failed ones. When the live series is empty the hook probes
|
|
2425
|
+
* once for ended rows so the panel can still offer them.
|
|
2426
|
+
*/
|
|
2427
|
+
interface UseRetainersReturn {
|
|
2428
|
+
retainers: Retainer[];
|
|
2429
|
+
/** Rows matching the current series (live, or every status). */
|
|
2430
|
+
total: number;
|
|
2431
|
+
/** Ended (canceled / failed) rows known to exist while the live series is empty. */
|
|
2432
|
+
endedTotal: number;
|
|
2433
|
+
hasMore: boolean;
|
|
2434
|
+
isLoading: boolean;
|
|
2435
|
+
isLoadingMore: boolean;
|
|
2436
|
+
error: Error | null;
|
|
2437
|
+
includeEnded: boolean;
|
|
2438
|
+
setIncludeEnded: (includeEnded: boolean) => void;
|
|
2439
|
+
loadMore: () => Promise<void>;
|
|
2440
|
+
refetch: () => Promise<void>;
|
|
2441
|
+
}
|
|
2442
|
+
interface UseRetainersOptions {
|
|
2443
|
+
/** Bump to refetch (view data freshness). */
|
|
2444
|
+
refreshKey?: number;
|
|
2445
|
+
/** Initial series: the ended ones too. */
|
|
2446
|
+
includeEnded?: boolean;
|
|
2447
|
+
/** Page size (the API caps at 100). */
|
|
2448
|
+
limit?: number;
|
|
2449
|
+
}
|
|
2450
|
+
declare function useRetainers({ refreshKey, includeEnded: initialIncludeEnded, limit }?: UseRetainersOptions): UseRetainersReturn;
|
|
2451
|
+
|
|
2452
|
+
interface UseAnalyticsOptions {
|
|
2453
|
+
/** Bump to force a refetch, matching the other views' convention. */
|
|
2454
|
+
refreshKey?: number;
|
|
2455
|
+
/** Breakdowns to fetch alongside the core reports. Defaults to none. */
|
|
2456
|
+
breakdowns?: AnalyticsBreakdownName[];
|
|
2457
|
+
/**
|
|
2458
|
+
* Drill-down filters, applied to EVERY report this hook fetches (U13).
|
|
2459
|
+
*
|
|
2460
|
+
* They belong here rather than on individual calls precisely so they cannot
|
|
2461
|
+
* diverge: one filtered card beside one unfiltered tile is the failure mode
|
|
2462
|
+
* the whole feature has to avoid.
|
|
2463
|
+
*/
|
|
2464
|
+
filters?: AnalyticsFilter[];
|
|
2465
|
+
}
|
|
2466
|
+
/**
|
|
2467
|
+
* One report's outcome.
|
|
2468
|
+
*
|
|
2469
|
+
* `error` is for the request failing outright. It is NOT the same as the
|
|
2470
|
+
* payload arriving with `status: 'unreachable'` — that is a successful answer
|
|
2471
|
+
* saying the source could not be reached, and the card renders it differently
|
|
2472
|
+
* from "this request broke".
|
|
2473
|
+
*/
|
|
2474
|
+
interface ReportSlot<T> {
|
|
2475
|
+
data: T | null;
|
|
2476
|
+
error: Error | null;
|
|
2477
|
+
isLoading: boolean;
|
|
2478
|
+
}
|
|
2479
|
+
interface UseAnalyticsReturn {
|
|
2480
|
+
status: ReportSlot<AnalyticsStatus>;
|
|
2481
|
+
summary: ReportSlot<AnalyticsSummary>;
|
|
2482
|
+
timeseries: ReportSlot<AnalyticsTimeseries>;
|
|
2483
|
+
channels: ReportSlot<AnalyticsChannels>;
|
|
2484
|
+
breakdowns: Record<string, ReportSlot<AnalyticsBreakdown>>;
|
|
2485
|
+
/** True until every report has settled, for the initial skeleton only. */
|
|
2486
|
+
isLoading: boolean;
|
|
2487
|
+
refetch: () => Promise<void>;
|
|
2488
|
+
/** Re-read status alone, in place, without disturbing the other reports. */
|
|
2489
|
+
refetchStatus: () => Promise<void>;
|
|
2490
|
+
}
|
|
2491
|
+
/**
|
|
2492
|
+
* Fetch the analytics panel's reports for one period.
|
|
2493
|
+
*
|
|
2494
|
+
* PER-REPORT SLOTS, NOT ONE STATE (R7). Each report resolves into its own
|
|
2495
|
+
* slot, so a failing pages card leaves the summary, chart and every other card
|
|
2496
|
+
* rendered. Collapsing this into a single `error` would blank the whole panel
|
|
2497
|
+
* because one of fourteen calls failed, which is both worse for the merchant
|
|
2498
|
+
* and hides which source is actually broken.
|
|
2499
|
+
*
|
|
2500
|
+
* THE REQUESTS ARE ISSUED TOGETHER and settle independently: they share no
|
|
2501
|
+
* dependency, so serialising them would make the panel as slow as the sum of
|
|
2502
|
+
* its cards rather than its slowest one.
|
|
2503
|
+
*/
|
|
2504
|
+
declare function useAnalytics(period: AnalyticsPeriod, { refreshKey, breakdowns, filters }?: UseAnalyticsOptions): UseAnalyticsReturn;
|
|
2505
|
+
|
|
2506
|
+
/** KTD10. Named rather than inlined so the tests state the same numbers. */
|
|
2507
|
+
declare const REALTIME_POLL_MS = 30000;
|
|
2508
|
+
declare const REALTIME_FAILURES_BEFORE_ERROR = 3;
|
|
2509
|
+
interface UseRealtimeVisitorsReturn {
|
|
2510
|
+
/** Last known count. Survives a transient failure — see `isStale`. */
|
|
2511
|
+
currentVisitors: number | null;
|
|
2512
|
+
/** When the held count was taken, straight from the server. */
|
|
2513
|
+
asOf: string | null;
|
|
2514
|
+
/**
|
|
2515
|
+
* The held value is older than one poll because a fetch failed. The pill
|
|
2516
|
+
* keeps showing the number and says how old it is: blanking a live counter
|
|
2517
|
+
* on one network blip is worse than showing a slightly stale one, as long as
|
|
2518
|
+
* the staleness is visible.
|
|
2519
|
+
*/
|
|
2520
|
+
isStale: boolean;
|
|
2521
|
+
/** Set only after REALTIME_FAILURES_BEFORE_ERROR consecutive failures. */
|
|
2522
|
+
error: Error | null;
|
|
2523
|
+
/** The source answered, but said it could not be reached. */
|
|
2524
|
+
isUnreachable: boolean;
|
|
2525
|
+
/**
|
|
2526
|
+
* A monotonic counter of SETTLED polls, successful or not.
|
|
2527
|
+
*
|
|
2528
|
+
* `asOf` only advances on an OK payload, so anything pacing itself off it
|
|
2529
|
+
* stops the moment realtime starts failing — even when the thing it was
|
|
2530
|
+
* really waiting on is perfectly healthy. This counter is the honest "a
|
|
2531
|
+
* poll completed" signal.
|
|
2532
|
+
*/
|
|
2533
|
+
polls: number;
|
|
2534
|
+
/**
|
|
2535
|
+
* No poll has SETTLED yet.
|
|
2536
|
+
*
|
|
2537
|
+
* Distinct from every failure flag: on mount there is no count because none
|
|
2538
|
+
* has been fetched, which is not the same claim as "we cannot reach it".
|
|
2539
|
+
* Without this the pill announced an outage on every page load and took it
|
|
2540
|
+
* back a moment later.
|
|
2541
|
+
*/
|
|
2542
|
+
isInitialLoad: boolean;
|
|
2543
|
+
}
|
|
2544
|
+
/**
|
|
2545
|
+
* Poll the live visitor count (R6, KTD10).
|
|
2546
|
+
*
|
|
2547
|
+
* PAUSES WHILE THE TAB IS HIDDEN. A background tab polling every 30 seconds
|
|
2548
|
+
* spends the merchant's Tinybird quota to update a number nobody is looking
|
|
2549
|
+
* at, and the panel's own throttle cannot help across browser sessions. It
|
|
2550
|
+
* fetches once immediately on becoming visible again, because the first thing
|
|
2551
|
+
* someone does on returning to the tab is read that number.
|
|
2552
|
+
*
|
|
2553
|
+
* FAILURES DEGRADE IN STAGES rather than flipping straight to an error. One or
|
|
2554
|
+
* two misses hold the last value and mark it stale; only the third consecutive
|
|
2555
|
+
* failure surfaces an error. A live counter that blanks on a single blip
|
|
2556
|
+
* trains people to distrust it.
|
|
2557
|
+
*/
|
|
2558
|
+
declare function useRealtimeVisitors(options?: {
|
|
2559
|
+
/**
|
|
2560
|
+
* Whether the site is known to collect. UNDEFINED means not yet known —
|
|
2561
|
+
* status has not answered, or its answer was cleared by a refetch.
|
|
2562
|
+
*
|
|
2563
|
+
* The caller passes the raw fact and this hook LATCHES it, because the latch
|
|
2564
|
+
* has to be reset when the site changes and that is something only this hook
|
|
2565
|
+
* can see. Latched in the caller instead, it survived a site switch: moving
|
|
2566
|
+
* from a collecting site to one whose status call fails left the latch true
|
|
2567
|
+
* and polled the new site — possibly one with no analytics identity at all —
|
|
2568
|
+
* every 30 seconds, defeating the gate it exists to enforce.
|
|
2569
|
+
*/
|
|
2570
|
+
collecting?: boolean;
|
|
2571
|
+
/**
|
|
2572
|
+
* The collection lookup itself FAILED, so `collecting` is unknowable rather
|
|
2573
|
+
* than merely not-yet-known.
|
|
2574
|
+
*
|
|
2575
|
+
* Passed in rather than inferred because only the caller sees the error —
|
|
2576
|
+
* but interpreted HERE, along with the latch, because both questions turn on
|
|
2577
|
+
* the site lifecycle and this hook is the only place that observes it. The
|
|
2578
|
+
* caller previously tracked "have we ever known?" itself and did not reset
|
|
2579
|
+
* it per site, which left a stale answer applied to a new one.
|
|
2580
|
+
*/
|
|
2581
|
+
statusFailed?: boolean;
|
|
2582
|
+
/**
|
|
2583
|
+
* The site's analytics identity, when known.
|
|
2584
|
+
*
|
|
2585
|
+
* A site can be REPOINTED at a different identity without the provider or
|
|
2586
|
+
* this hook remounting — the org-scoped analytics route exists to do exactly
|
|
2587
|
+
* that, and its own description warns it can repoint a panel at another
|
|
2588
|
+
* tenant's traffic. Keyed only on `api`, the previous identity's count
|
|
2589
|
+
* stayed on screen and an in-flight request for it stayed valid.
|
|
2590
|
+
*/
|
|
2591
|
+
identity?: string | null;
|
|
2592
|
+
}): UseRealtimeVisitorsReturn;
|
|
2593
|
+
|
|
1789
2594
|
declare function isZeroDecimalCurrency(currency: string): boolean;
|
|
1790
2595
|
/**
|
|
1791
2596
|
* Format a minor-unit amount for display ("$29.00", "¥1,500").
|
|
@@ -1828,4 +2633,43 @@ declare function toMinorUnits(major: string | number, currency: string): number
|
|
|
1828
2633
|
*/
|
|
1829
2634
|
declare function toMajorUnits(minor: number, currency: string): number;
|
|
1830
2635
|
|
|
1831
|
-
|
|
2636
|
+
interface AnalyticsViewProps {
|
|
2637
|
+
/**
|
|
2638
|
+
* Filters, when the HOST wants to own them — to put them in its URL, say.
|
|
2639
|
+
*
|
|
2640
|
+
* This package peers only on react and react-dom and has no router, so it
|
|
2641
|
+
* cannot read or write a URL itself. Lifting the state through props is how
|
|
2642
|
+
* a linkable, reloadable filtered view stays possible without dragging a
|
|
2643
|
+
* router dependency into an embeddable panel. Omit both and the panel keeps
|
|
2644
|
+
* the filters internally, which is what Storybook and the tests do.
|
|
2645
|
+
*/
|
|
2646
|
+
filters?: AnalyticsFilter[];
|
|
2647
|
+
onFiltersChange?: (filters: AnalyticsFilter[]) => void;
|
|
2648
|
+
/** Bump to force a refetch, matching the other views. */
|
|
2649
|
+
refreshKey?: number;
|
|
2650
|
+
onBackToWebsite?: () => void;
|
|
2651
|
+
className?: string;
|
|
2652
|
+
/**
|
|
2653
|
+
* Publish state, supplied by the host: aifeatures has none of its own.
|
|
2654
|
+
* Without it the pre-collection state cannot tell "never published" from
|
|
2655
|
+
* "published before we started collecting", which need different nudges.
|
|
2656
|
+
*/
|
|
2657
|
+
published?: boolean;
|
|
2658
|
+
lastPublishedAt?: string | null;
|
|
2659
|
+
}
|
|
2660
|
+
/**
|
|
2661
|
+
* The merchant-facing analytics panel.
|
|
2662
|
+
*
|
|
2663
|
+
* THE NON-DATA STATES ARE THE HARD PART (R7), and they are four different
|
|
2664
|
+
* things that all look like "nothing here":
|
|
2665
|
+
*
|
|
2666
|
+
* not collecting, never published -> publish to start collecting
|
|
2667
|
+
* not collecting, published early -> republish; the tag is not on the site
|
|
2668
|
+
* collecting, nothing yet -> it is working, wait for a visitor
|
|
2669
|
+
* collecting, nothing this period -> pick a wider period
|
|
2670
|
+
*
|
|
2671
|
+
* Rendering any of them as zeros would tell the merchant their site is dead.
|
|
2672
|
+
*/
|
|
2673
|
+
declare function AnalyticsView({ filters: filtersProp, onFiltersChange, refreshKey, onBackToWebsite, className, published, lastPublishedAt, }: AnalyticsViewProps): react_jsx_runtime.JSX.Element;
|
|
2674
|
+
|
|
2675
|
+
export { type AdjustInventoryInput, type AifeaturesApiClient, AifeaturesApiError, type AifeaturesContextValue, AifeaturesProvider, type AifeaturesProviderProps, type AnalyticsBreakdown, type AnalyticsBreakdownName, type AnalyticsBreakdownRow, type AnalyticsChannelRow, type AnalyticsChannels, type AnalyticsFilter, type AnalyticsFilterDimension, type AnalyticsPeriod, type AnalyticsRealtime, type AnalyticsSourced, type AnalyticsStatus, type AnalyticsSummary, type AnalyticsSummaryData, type AnalyticsSummaryMetrics, type AnalyticsTimeseries, type AnalyticsTimeseriesRow, AnalyticsView, type AnalyticsViewProps, type ApiError, type Attachment, type BusinessSummary, type BusinessVisitors, type CreateEventDestinationInput, 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 EmailDelivery, type EmailSideStatus, type EventDeliveriesListResponse, type EventDelivery, type EventDestination, type EventDestinationSecretResponse, type EventDestinationsListResponse, type Form, FormSettings, type FormSettingsProps, FormSubmissions, type FormSubmissionsProps, FormsDashboard, type FormsDashboardProps, FormsList, type FormsListProps, type FormsListResponse, type GetBusinessSummaryOptions, type GetCustomersOptions, type GetInvoicesOptions, type GetOrdersOptions, type GetPeopleOptions, type GetProductsOptions, type GetSubmissionsOptions, type GetSubscriptionsOptions, type Invoice, type InvoiceAggregates, type InvoiceBillTo, type InvoiceDeliveryState, InvoiceDetail, type InvoiceDetailProps, type InvoiceLabel, InvoiceLabelBadge, type InvoiceLineItem, type InvoicePreview, type InvoiceSettings, InvoicesList, type InvoicesListProps, InvoicesView, type InvoicesViewProps, LeadsView, type LeadsViewProps, type LowStockProduct, MAX_ANALYTICS_FILTERS, MAX_ANALYTICS_FILTER_VALUES, type NeedsAttentionItem, type NeedsAttentionType, type Order, OrderDetail, type OrderDetailProps, type OrderStatus, OrderStatusBadge, OrdersList, type OrdersListProps, OrdersView, type OrdersViewProps, type PaginatedInvoices, type PaginatedOrders, type PaginatedSubmissions, type PaginatedSubscriptions, 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, REALTIME_FAILURES_BEFORE_ERROR, REALTIME_POLL_MS, type RefundRequest, type ReportSlot, RetainerStatusBadge, RetainersPanel, type RetainersPanelProps, type RevenueCurrencyTotal, type RevenuePeriod, type SetInventoryInput, type SetOrderFulfillmentInput, type SettledRevenue, type Submission, SubmissionDetail, type SubmissionDetailProps, type SubmissionMetadata, type Subscription, SubscriptionsView, type SubscriptionsViewProps, type UpdateEventDestinationInput, type UpdateFormInput, type UpdateOptionInput, type UpdateProductInput, type UpdateVariantInput, type UseAnalyticsOptions, type UseAnalyticsReturn, type UseBusinessSummaryOptions, type UseBusinessSummaryReturn, type UseCustomersOptions, type UseCustomersReturn, type UseEventDestinationsReturn, type UseFormsReturn, type UseInvoicesOptions, type UseInvoicesReturn, type UseOrdersOptions, type UseOrdersReturn, type UsePaymentsStatusReturn, type UsePeopleOptions, type UsePeopleReturn, type UsePersonOptions, type UsePersonReturn, type UseProductsOptions, type UseProductsReturn, type UseRealtimeVisitorsReturn, type UseSubmissionsOptions, type UseSubmissionsReturn, type UseSubscriptionsOptions, type UseSubscriptionsReturn, type VariantInventory, type VariantOptionValue, VariantsEditor, type VariantsEditorProps, ViewShell, type ViewShellProps, WebhookDeliveries, type WebhookDeliveriesProps, WebhookSettings, type WebhookSettingsProps, chargedTotal, createApiClient, formatPrice, isZeroDecimalCurrency, toMajorUnits, toMinorUnits, useAifeaturesContext as useAifeatures, useAifeaturesContext, useAnalytics, useBusinessSummary, useCustomers, useEventDestinations, useForms, useInvoices, useOrders, usePaymentsStatus, usePeople, usePerson, useProducts, useRealtimeVisitors, useRetainers, useSubmissions, useSubscriptions };
|