@aifeatures/admin-react 0.6.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +4 -4
- package/dist/index.d.cts +431 -3
- package/dist/index.d.ts +431 -3
- package/dist/index.js +4 -4
- package/dist/styles.css +1 -1
- package/package.json +3 -1
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)
|
|
@@ -472,6 +492,7 @@ interface LineItem {
|
|
|
472
492
|
* currency's minor unit.
|
|
473
493
|
*/
|
|
474
494
|
interface Order {
|
|
495
|
+
email_deliveries?: EmailDelivery[];
|
|
475
496
|
id: string;
|
|
476
497
|
/**
|
|
477
498
|
* The merchant-facing order number (`#1042`) — a per-site sequence assigned
|
|
@@ -660,6 +681,7 @@ interface CustomerAddress {
|
|
|
660
681
|
}
|
|
661
682
|
/** Customer detail = the customer plus addresses and their order count. */
|
|
662
683
|
interface CustomerDetail$1 extends Customer {
|
|
684
|
+
email_deliveries?: EmailDelivery[];
|
|
663
685
|
addresses: CustomerAddress[];
|
|
664
686
|
order_count: number;
|
|
665
687
|
}
|
|
@@ -727,9 +749,32 @@ interface LowStockProduct {
|
|
|
727
749
|
/** Units still available on the lowest tracked variant. */
|
|
728
750
|
available: number;
|
|
729
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
|
+
}
|
|
730
775
|
/**
|
|
731
776
|
* Response from GET /api/v1/summary — the merchant's one-look business
|
|
732
|
-
* rollup.
|
|
777
|
+
* rollup.
|
|
733
778
|
*/
|
|
734
779
|
interface BusinessSummary {
|
|
735
780
|
site_id: string;
|
|
@@ -747,7 +792,7 @@ interface BusinessSummary {
|
|
|
747
792
|
count: number;
|
|
748
793
|
low_stock: LowStockProduct[];
|
|
749
794
|
};
|
|
750
|
-
visitors: null;
|
|
795
|
+
visitors: BusinessVisitors | null;
|
|
751
796
|
}
|
|
752
797
|
/** Options for fetching the business summary. */
|
|
753
798
|
interface GetBusinessSummaryOptions {
|
|
@@ -856,6 +901,7 @@ interface PersonDetail {
|
|
|
856
901
|
* dashboard's site token cannot call them.
|
|
857
902
|
*/
|
|
858
903
|
interface Subscription {
|
|
904
|
+
email_deliveries?: EmailDelivery[];
|
|
859
905
|
id: string;
|
|
860
906
|
/**
|
|
861
907
|
* Mirrored Stripe status, stored VERBATIM — a full-Dashboard merchant can
|
|
@@ -1206,6 +1252,183 @@ interface GetRetainersOptions {
|
|
|
1206
1252
|
limit?: number;
|
|
1207
1253
|
offset?: number;
|
|
1208
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';
|
|
1209
1432
|
|
|
1210
1433
|
declare class AifeaturesApiError extends Error {
|
|
1211
1434
|
status: number;
|
|
@@ -1268,6 +1491,30 @@ interface AifeaturesApiClient {
|
|
|
1268
1491
|
getPeople(options?: GetPeopleOptions): Promise<PeopleListResponse>;
|
|
1269
1492
|
/** Everything known about one person (customer record, orders, submissions). */
|
|
1270
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>;
|
|
1271
1518
|
getEventDestinations(): Promise<EventDestination[]>;
|
|
1272
1519
|
createEventDestination(input: CreateEventDestinationInput): Promise<EventDestination>;
|
|
1273
1520
|
updateEventDestination(destinationId: string, input: UpdateEventDestinationInput): Promise<EventDestination>;
|
|
@@ -2202,6 +2449,148 @@ interface UseRetainersOptions {
|
|
|
2202
2449
|
}
|
|
2203
2450
|
declare function useRetainers({ refreshKey, includeEnded: initialIncludeEnded, limit }?: UseRetainersOptions): UseRetainersReturn;
|
|
2204
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
|
+
|
|
2205
2594
|
declare function isZeroDecimalCurrency(currency: string): boolean;
|
|
2206
2595
|
/**
|
|
2207
2596
|
* Format a minor-unit amount for display ("$29.00", "¥1,500").
|
|
@@ -2244,4 +2633,43 @@ declare function toMinorUnits(major: string | number, currency: string): number
|
|
|
2244
2633
|
*/
|
|
2245
2634
|
declare function toMajorUnits(minor: number, currency: string): number;
|
|
2246
2635
|
|
|
2247
|
-
|
|
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 };
|