@nymbalhq/platform 1.5.0 → 1.6.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/LICENSE +21 -0
- package/README.md +6 -0
- package/dist/{chunk-TRLERRUI.js → chunk-KH3BABMV.js} +10467 -7548
- package/dist/chunk-KH3BABMV.js.map +1 -0
- package/dist/{chunk-NNDIAIT6.js → chunk-TVKV5GBY.js} +102 -7
- package/dist/chunk-TVKV5GBY.js.map +1 -0
- package/dist/db/schema/index.d.ts +5745 -3404
- package/dist/db/schema/index.js +1 -1
- package/dist/index.d.ts +678 -47
- package/dist/index.js +4055 -2098
- package/dist/index.js.map +1 -1
- package/dist/register-XP5XVAXM.js +8 -0
- package/migrations/postgres/0019_carts_customer_idx.sql +1 -0
- package/migrations/postgres/0020_alert_confirmation_sent.sql +1 -0
- package/migrations/postgres/0021_proposals.sql +27 -0
- package/migrations/postgres/0022_order_source.sql +3 -0
- package/migrations/postgres/meta/0019_snapshot.json +2322 -0
- package/migrations/postgres/meta/0020_snapshot.json +2328 -0
- package/migrations/postgres/meta/0021_snapshot.json +2543 -0
- package/migrations/postgres/meta/0022_snapshot.json +2578 -0
- package/migrations/postgres/meta/_journal.json +28 -0
- package/migrations/sqlite/0019_carts_customer_idx.sql +1 -0
- package/migrations/sqlite/0020_alert_confirmation_sent.sql +1 -0
- package/migrations/sqlite/0021_proposals.sql +27 -0
- package/migrations/sqlite/0022_order_source.sql +3 -0
- package/migrations/sqlite/meta/0019_snapshot.json +2056 -0
- package/migrations/sqlite/meta/0020_snapshot.json +2063 -0
- package/migrations/sqlite/meta/0021_snapshot.json +2246 -0
- package/migrations/sqlite/meta/0022_snapshot.json +2270 -0
- package/migrations/sqlite/meta/_journal.json +28 -0
- package/package.json +24 -21
- package/dist/chunk-NNDIAIT6.js.map +0 -1
- package/dist/chunk-TRLERRUI.js.map +0 -1
- package/dist/register-SBGUI2L5.js +0 -8
- /package/dist/{register-SBGUI2L5.js.map → register-XP5XVAXM.js.map} +0 -0
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { NymbalConfig } from '@nymbalhq/config';
|
|
2
|
-
|
|
2
|
+
export { secureCookies } from '@nymbalhq/config';
|
|
3
|
+
import { Logger, DocumentStoreAdapter, EventBusAdapter, MediaStorage, Product, ProductStatus, ProductType, ProductMedia, Variant, VariantDimensions, VariantOption, VariantStatus, Category, Customer, Role, CustomerAddress, Order, OrderStatus, Address, OrderLineItem, CaptureMethod, OrderSource, OrderHistoryEntry, OrderRefundStatus, OrderRefund, InventoryReservation, StockAdjustmentReason, StockAdjustment, Review, ReviewModerationStatus, NymbalEvent, Cart, AuditSubject, AuditActor, AuditOutcome, AuditEntry, AlertKind, AlertStatus, ProposalStatus, ProposalDecider, ProposalView, HealthReport, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, RequestAuth, AdapterSetting, CommerceSlotAdapters, SecurityAdapter, AiAdapter, PaymentsAdapter, CartSource, EmailAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, SearchAdapter, OrderPayment, Refund, RecentViewer, ReviewsAdapter, Caller, ToolResult, ProposalPage, CommerceSlot, HttpAdapter, ToolSurface, RequestContext, ResponseEnvelope, RouteHandler, ToolDefinition, JsonSchemaObject, AssistantFrame, ResolvedNetwork, AgentSurfaces, AgentSurfaceUrls, AgentSurfaceAdapter, HealthStatus, SecurityNetwork, OriginLockRule, Slot, ProviderPackageModule, RateLimitAction, AnalyticsAdapter, ShippingAdapter, TaxAdapter } from '@nymbalhq/types';
|
|
3
4
|
export { MediaStorage, buildSecurityHeaders, isValidCorrelationId } from '@nymbalhq/types';
|
|
4
5
|
import BetterSqlite3 from 'better-sqlite3';
|
|
5
6
|
import pg from 'pg';
|
|
@@ -267,6 +268,9 @@ interface VariantRepository extends StoreRepository {
|
|
|
267
268
|
findById(tx: ReadTx, id: string): Promise<Variant | null>;
|
|
268
269
|
findBySku(tx: ReadTx, sku: string): Promise<Variant | null>;
|
|
269
270
|
findByProduct(tx: ReadTx, productId: string): Promise<Variant[]>;
|
|
271
|
+
/** `findByProduct`, holding the rows for the rest of the transaction so concurrent commands on them queue behind
|
|
272
|
+
* this one (Postgres `FOR UPDATE`; SQLite's `BEGIN IMMEDIATE` already holds the database). */
|
|
273
|
+
lockByProduct(tx: Tx, productId: string): Promise<Variant[]>;
|
|
270
274
|
insert(tx: Tx, v: VariantInsert): Promise<void>;
|
|
271
275
|
update(tx: Tx, id: string, patch: VariantUpdate): Promise<void>;
|
|
272
276
|
/** One conditional UPDATE: the new stock, or null when the variant is missing or holds fewer than `qty`. */
|
|
@@ -378,13 +382,46 @@ interface RefreshTokenRow {
|
|
|
378
382
|
interface RefreshTokenRepository extends StoreRepository {
|
|
379
383
|
insert(tx: Tx, t: RefreshTokenInsert): Promise<void>;
|
|
380
384
|
findById(tx: ReadTx, id: string): Promise<RefreshTokenRow | null>;
|
|
385
|
+
/**
|
|
386
|
+
* Inserts `next` as the successor of `oldJti`. The old row's `revokedAt` is set only if it has none: re-rotating a
|
|
387
|
+
* token inside the reuse window keeps the instant of its first rotation, so the window never slides.
|
|
388
|
+
*/
|
|
381
389
|
rotate(tx: Tx, oldJti: string, next: RefreshTokenInsert): Promise<void>;
|
|
382
390
|
revoke(tx: Tx, id: string): Promise<void>;
|
|
391
|
+
/** Revokes every row of the customer not revoked already, leaving earlier `revokedAt` instants as they were. */
|
|
383
392
|
revokeAllForCustomer(tx: Tx, customerId: string): Promise<void>;
|
|
384
393
|
purgeExpired(tx: Tx, now: Date): Promise<number>;
|
|
394
|
+
/**
|
|
395
|
+
* Deletes rotated rows (a successor is recorded) revoked before `revokedBefore`. Rows revoked with no successor
|
|
396
|
+
* (logout, sign-out of every session) stay until they expire, so presenting one stays a plain refusal.
|
|
397
|
+
*/
|
|
398
|
+
purgeRotated(tx: Tx, revokedBefore: Date): Promise<number>;
|
|
399
|
+
deleteByCustomer(tx: Tx, customerId: string): Promise<void>;
|
|
385
400
|
}
|
|
386
401
|
declare function createRefreshTokenRepository(store: CommandStore): RefreshTokenRepository;
|
|
387
402
|
|
|
403
|
+
interface CustomerOrderTotals {
|
|
404
|
+
orderCount: number;
|
|
405
|
+
/** Σ (captured − refunded): the money the store kept. */
|
|
406
|
+
keptMinor: number;
|
|
407
|
+
/** Orders that captured any money. */
|
|
408
|
+
capturedCount: number;
|
|
409
|
+
firstAt: string | null;
|
|
410
|
+
lastAt: string | null;
|
|
411
|
+
}
|
|
412
|
+
/** One agent's orders in a window: how many, and Σ (captured − refunded). */
|
|
413
|
+
interface AgentSourceTotals {
|
|
414
|
+
source: `agent:${string}`;
|
|
415
|
+
count: number;
|
|
416
|
+
revenueMinor: number;
|
|
417
|
+
}
|
|
418
|
+
/** Every agent order in a window, and the agents that brought the most money. */
|
|
419
|
+
interface AgentTotals {
|
|
420
|
+
count: number;
|
|
421
|
+
revenueMinor: number;
|
|
422
|
+
/** At most `top` sources: revenue descending, then count descending, then source ascending. */
|
|
423
|
+
bySource: AgentSourceTotals[];
|
|
424
|
+
}
|
|
388
425
|
interface OrderInsert {
|
|
389
426
|
id: string;
|
|
390
427
|
orderNumber: string;
|
|
@@ -410,6 +447,8 @@ interface OrderInsert {
|
|
|
410
447
|
capture?: OrderCapture & {
|
|
411
448
|
refundedMinor: number;
|
|
412
449
|
};
|
|
450
|
+
/** Who brought the order; `storefront` when not given. */
|
|
451
|
+
source?: OrderSource;
|
|
413
452
|
createdAt: Date;
|
|
414
453
|
updatedAt: Date;
|
|
415
454
|
}
|
|
@@ -430,6 +469,15 @@ interface OrderRepository extends StoreRepository {
|
|
|
430
469
|
/** The newest order the cart became: neither pending nor cancelled. */
|
|
431
470
|
findLastConvertedByCartToken(tx: ReadTx, cartToken: string): Promise<Order | null>;
|
|
432
471
|
listByCustomer(tx: ReadTx, customerId: string, limit?: number): Promise<Order[]>;
|
|
472
|
+
/**
|
|
473
|
+
* The customer's newest order (by `createdAt`, then id) in one of `statuses` whose line items hold the product, or
|
|
474
|
+
* null: their orders are read newest first a page at a time until one does.
|
|
475
|
+
*/
|
|
476
|
+
newestHolding(tx: ReadTx, customerId: string, productId: string, statuses: readonly OrderStatus[]): Promise<Order | null>;
|
|
477
|
+
/** Totals over every order the customer has, however many. */
|
|
478
|
+
totalsByCustomer(tx: ReadTx, customerId: string): Promise<CustomerOrderTotals>;
|
|
479
|
+
/** The `agent:` orders created at or after `since`, any status, and the `top` agents among them. */
|
|
480
|
+
agentTotals(tx: ReadTx, since: Date, top: number): Promise<AgentTotals>;
|
|
433
481
|
list(tx: ReadTx, opts?: {
|
|
434
482
|
status?: OrderStatus;
|
|
435
483
|
limit?: number;
|
|
@@ -446,6 +494,10 @@ interface OrderRepository extends StoreRepository {
|
|
|
446
494
|
recordCapture(tx: Tx, id: string, capture: OrderCapture): Promise<void>;
|
|
447
495
|
setRefunded(tx: Tx, id: string, refundedMinor: number, updatedAt: Date): Promise<void>;
|
|
448
496
|
setNotes(tx: Tx, id: string, notes: string, updatedAt: Date): Promise<void>;
|
|
497
|
+
/** Deletes the order's row alone: the rows that reference it go first. */
|
|
498
|
+
delete(tx: Tx, id: string): Promise<void>;
|
|
499
|
+
/** Ids of the orders created at or after `since`. */
|
|
500
|
+
idsCreatedSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
449
501
|
}
|
|
450
502
|
declare function createOrderRepository(store: CommandStore): OrderRepository;
|
|
451
503
|
|
|
@@ -461,6 +513,9 @@ interface OrderHistoryInsert {
|
|
|
461
513
|
interface OrderHistoryRepository extends StoreRepository {
|
|
462
514
|
append(tx: Tx, entry: OrderHistoryInsert): Promise<void>;
|
|
463
515
|
listByOrder(tx: ReadTx, orderId: string): Promise<OrderHistoryEntry[]>;
|
|
516
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
517
|
+
/** The order of each entry written at or after `since`, once per entry. */
|
|
518
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
464
519
|
}
|
|
465
520
|
declare function createOrderHistoryRepository(store: CommandStore): OrderHistoryRepository;
|
|
466
521
|
|
|
@@ -490,6 +545,9 @@ interface OrderRefundRepository extends StoreRepository {
|
|
|
490
545
|
listByOrder(tx: ReadTx, orderId: string): Promise<OrderRefund[]>;
|
|
491
546
|
/** The refunds of each order, oldest first; an order without refunds is absent. */
|
|
492
547
|
listByOrders(tx: ReadTx, orderIds: string[]): Promise<Map<string, OrderRefund[]>>;
|
|
548
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
549
|
+
/** The order of each refund made at or after `since`, once per refund. */
|
|
550
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
493
551
|
}
|
|
494
552
|
declare function createOrderRefundRepository(store: CommandStore): OrderRefundRepository;
|
|
495
553
|
|
|
@@ -517,6 +575,9 @@ interface OrderAccessKeyRepository extends StoreRepository {
|
|
|
517
575
|
opens(tx: ReadTx, orderId: string, keyHash: string, now: Date): Promise<OrderKeyState>;
|
|
518
576
|
/** Deletes the order's oldest keys of `purpose`, by `(created_at, id)`, until at most `keep` remain. */
|
|
519
577
|
keepNewest(tx: Tx, orderId: string, purpose: OrderAccessKeyPurpose, keep: number): Promise<void>;
|
|
578
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
579
|
+
/** The order of each key minted at or after `since`, once per key. */
|
|
580
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
520
581
|
}
|
|
521
582
|
declare function createOrderAccessKeyRepository(store: CommandStore): OrderAccessKeyRepository;
|
|
522
583
|
|
|
@@ -575,10 +636,20 @@ interface ReviewKey {
|
|
|
575
636
|
}
|
|
576
637
|
interface ReviewRepository extends StoreRepository {
|
|
577
638
|
findById(tx: ReadTx, id: string): Promise<Review | null>;
|
|
639
|
+
/** The customer's review of the product, whatever its moderation status. */
|
|
640
|
+
findByProductAndCustomer(tx: ReadTx, productId: string, customerId: string): Promise<Review | null>;
|
|
641
|
+
/**
|
|
642
|
+
* Holds the (product, customer) pair until the transaction ends, so a find then insert for it runs one at a time:
|
|
643
|
+
* a Postgres advisory lock; on SQLite the open `BEGIN IMMEDIATE` transaction already holds every write.
|
|
644
|
+
*/
|
|
645
|
+
lockPair(tx: Tx, productId: string, customerId: string): Promise<void>;
|
|
578
646
|
/** Newest first, ties by id descending; `after` is the last review of the previous page. */
|
|
579
647
|
listByProduct(tx: ReadTx, productId: string, status?: ReviewModerationStatus, limit?: number, after?: ReviewKey): Promise<Review[]>;
|
|
580
648
|
listByStatus(tx: ReadTx, status: ReviewModerationStatus, limit?: number): Promise<Review[]>;
|
|
581
649
|
insert(tx: Tx, r: ReviewInsert): Promise<void>;
|
|
650
|
+
delete(tx: Tx, id: string): Promise<void>;
|
|
651
|
+
/** Ids of the reviews submitted at or after `since`. */
|
|
652
|
+
idsSubmittedSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
582
653
|
setModerationStatus(tx: Tx, id: string, status: ReviewModerationStatus, moderatedBy: string, moderatedAt: Date): Promise<void>;
|
|
583
654
|
aggregateByProduct(tx: ReadTx, productId: string): Promise<{
|
|
584
655
|
average: number;
|
|
@@ -648,7 +719,10 @@ interface EventLogRepository extends StoreRepository {
|
|
|
648
719
|
listDead(tx: ReadTx, limit: number): Promise<LoggedEvent[]>;
|
|
649
720
|
/** Neither delivered nor dead, with at least one failed attempt. */
|
|
650
721
|
countRetrying(tx: ReadTx): Promise<number>;
|
|
651
|
-
/**
|
|
722
|
+
/**
|
|
723
|
+
* Deletes delivered events delivered before `at`; returns how many. Undelivered and dead events, a dead one also
|
|
724
|
+
* marked delivered included, are never deleted.
|
|
725
|
+
*/
|
|
652
726
|
deleteDeliveredBefore(tx: Tx, at: Date): Promise<number>;
|
|
653
727
|
listAll(tx: ReadTx): Promise<LoggedEvent[]>;
|
|
654
728
|
/** One correlation id's events, by `seq`. */
|
|
@@ -697,6 +771,8 @@ interface CartRepository extends StoreRepository {
|
|
|
697
771
|
/** `findByToken`, holding the row for the rest of the transaction so concurrent commands on the cart queue behind
|
|
698
772
|
* this one (Postgres `FOR UPDATE`; SQLite's `BEGIN IMMEDIATE` already holds the database). */
|
|
699
773
|
lock(tx: Tx, token: string): Promise<Cart | null>;
|
|
774
|
+
/** The customer's most recently written cart that is still live at `at`; holds nothing. */
|
|
775
|
+
findLiveByCustomer(tx: ReadTx, customerId: string, at: Date): Promise<Cart | null>;
|
|
700
776
|
/** Inserts the cart, or replaces an expired row on its token. A live row on the token is left as it is and
|
|
701
777
|
* returned with `created: false`. */
|
|
702
778
|
create(tx: Tx, cart: Cart): Promise<{
|
|
@@ -824,6 +900,8 @@ interface AlertSubscription {
|
|
|
824
900
|
createdAt: Date;
|
|
825
901
|
updatedAt: Date;
|
|
826
902
|
confirmedAt: Date | null;
|
|
903
|
+
/** When its last confirmation was sent; null on a new or reissued row. */
|
|
904
|
+
confirmationSentAt: Date | null;
|
|
827
905
|
}
|
|
828
906
|
/** A subscribe request: a new row's values, of which a row already there takes only what its status allows. */
|
|
829
907
|
interface AlertSubscriptionRequest {
|
|
@@ -850,9 +928,11 @@ interface AlertSubscriptionRepository extends StoreRepository {
|
|
|
850
928
|
/**
|
|
851
929
|
* One write on the unique (email, variant, kind): a new row is `pending`; a `pending` row takes the request's origin;
|
|
852
930
|
* an `unsubscribed` or `fired` row returns to `pending` with the request's origin, confirm token and baseline (its
|
|
853
|
-
* unsubscribe token is kept); an `active` row only has `updated_at` touched. Answers the
|
|
931
|
+
* unsubscribe token is kept) and no confirmation sent; an `active` row only has `updated_at` touched. Answers the
|
|
932
|
+
* row after the write.
|
|
854
933
|
*/
|
|
855
934
|
upsertPending(tx: Tx, request: AlertSubscriptionRequest): Promise<AlertSubscription>;
|
|
935
|
+
markConfirmationSent(tx: Tx, id: string, at: Date): Promise<void>;
|
|
856
936
|
findById(tx: ReadTx, id: string): Promise<AlertSubscription | null>;
|
|
857
937
|
findByConfirmToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
|
|
858
938
|
findByUnsubscribeToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
|
|
@@ -889,9 +969,84 @@ interface OrderShipmentRepository extends StoreRepository {
|
|
|
889
969
|
record(tx: Tx, input: OrderShipmentInput): Promise<void>;
|
|
890
970
|
/** The ids of every order shipped under the number, in no particular order. */
|
|
891
971
|
ordersByTrackingNumber(tx: ReadTx, trackingNumber: string): Promise<string[]>;
|
|
972
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
973
|
+
/** The orders shipped at or after `since`. */
|
|
974
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
892
975
|
}
|
|
893
976
|
declare function createOrderShipmentRepository(store: CommandStore): OrderShipmentRepository;
|
|
894
977
|
|
|
978
|
+
/** One `proposals` row. */
|
|
979
|
+
interface ProposalRecord {
|
|
980
|
+
id: string;
|
|
981
|
+
tool: string;
|
|
982
|
+
command: string;
|
|
983
|
+
args: Record<string, unknown>;
|
|
984
|
+
/** Argument name to value: the credentials (a cart id) the call carried as handles. */
|
|
985
|
+
handles: Record<string, string> | null;
|
|
986
|
+
idempotencyKey: string | null;
|
|
987
|
+
proposerId: string | null;
|
|
988
|
+
agentName: string;
|
|
989
|
+
agentVersion: string | null;
|
|
990
|
+
correlationId: string;
|
|
991
|
+
status: ProposalStatus;
|
|
992
|
+
decidedByKind: 'admin' | 'policy' | null;
|
|
993
|
+
decidedBy: string | null;
|
|
994
|
+
decidedAt: string | null;
|
|
995
|
+
reason: string | null;
|
|
996
|
+
outcomeStatus: number | null;
|
|
997
|
+
outcomeCode: string | null;
|
|
998
|
+
outcomeMessage: string | null;
|
|
999
|
+
createdAt: string;
|
|
1000
|
+
settledAt: string | null;
|
|
1001
|
+
}
|
|
1002
|
+
type ProposalInsert = Pick<ProposalRecord, 'id' | 'tool' | 'command' | 'args' | 'handles' | 'idempotencyKey' | 'proposerId' | 'agentName' | 'agentVersion' | 'correlationId'> & {
|
|
1003
|
+
createdAt: Date;
|
|
1004
|
+
};
|
|
1005
|
+
interface ProposalDecision {
|
|
1006
|
+
status: 'approved' | 'rejected';
|
|
1007
|
+
by: ProposalDecider;
|
|
1008
|
+
at: Date;
|
|
1009
|
+
reason?: string | undefined;
|
|
1010
|
+
}
|
|
1011
|
+
interface ProposalSettlement {
|
|
1012
|
+
status: 'applied' | 'failed';
|
|
1013
|
+
outcome: {
|
|
1014
|
+
status: number;
|
|
1015
|
+
code?: string;
|
|
1016
|
+
message?: string;
|
|
1017
|
+
};
|
|
1018
|
+
at: Date;
|
|
1019
|
+
}
|
|
1020
|
+
/** A position in the (created_at, id) order proposals are listed in, newest first. */
|
|
1021
|
+
interface ProposalCursor {
|
|
1022
|
+
at: string;
|
|
1023
|
+
id: string;
|
|
1024
|
+
}
|
|
1025
|
+
interface ProposalQuery {
|
|
1026
|
+
status: 'pending' | 'decided' | 'all';
|
|
1027
|
+
cursor?: ProposalCursor;
|
|
1028
|
+
limit: number;
|
|
1029
|
+
}
|
|
1030
|
+
interface ProposalRepository extends StoreRepository {
|
|
1031
|
+
/** False when the proposer already has a row for the tool under the key: that row stands. */
|
|
1032
|
+
insert(tx: Tx, row: ProposalInsert): Promise<boolean>;
|
|
1033
|
+
findById(tx: ReadTx, id: string): Promise<ProposalRecord | null>;
|
|
1034
|
+
findByKey(tx: ReadTx, proposerId: string, tool: string, key: string): Promise<ProposalRecord | null>;
|
|
1035
|
+
/** Decides a pending row; false when it was not pending (or does not exist). */
|
|
1036
|
+
decide(tx: Tx, id: string, decision: ProposalDecision): Promise<boolean>;
|
|
1037
|
+
/** Settles an approved row with what its command answered; false when it was not approved. */
|
|
1038
|
+
settle(tx: Tx, id: string, settlement: ProposalSettlement): Promise<boolean>;
|
|
1039
|
+
/** Newest first, the rows before `cursor`, at most `limit`. */
|
|
1040
|
+
list(tx: ReadTx, q: ProposalQuery): Promise<ProposalRecord[]>;
|
|
1041
|
+
countPending(tx: ReadTx): Promise<number>;
|
|
1042
|
+
}
|
|
1043
|
+
declare function encodeProposalCursor(row: Pick<ProposalRecord, 'createdAt' | 'id'>): string;
|
|
1044
|
+
/** A cursor `encodeProposalCursor` made, or undefined for anything else. */
|
|
1045
|
+
declare function decodeProposalCursor(value: string): ProposalCursor | undefined;
|
|
1046
|
+
/** The row as the admin reads it: a handle by its argument's name only. */
|
|
1047
|
+
declare function proposalView(row: ProposalRecord): ProposalView;
|
|
1048
|
+
declare function createProposalRepository(store: CommandStore): ProposalRepository;
|
|
1049
|
+
|
|
895
1050
|
interface Repositories {
|
|
896
1051
|
product: ProductRepository;
|
|
897
1052
|
variant: VariantRepository;
|
|
@@ -915,6 +1070,7 @@ interface Repositories {
|
|
|
915
1070
|
alertSubscription: AlertSubscriptionRepository;
|
|
916
1071
|
emailSuppression: EmailSuppressionRepository;
|
|
917
1072
|
orderShipment: OrderShipmentRepository;
|
|
1073
|
+
proposal: ProposalRepository;
|
|
918
1074
|
}
|
|
919
1075
|
declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
|
|
920
1076
|
|
|
@@ -1118,6 +1274,10 @@ interface BuildAdaptersDeps {
|
|
|
1118
1274
|
}
|
|
1119
1275
|
declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
|
|
1120
1276
|
|
|
1277
|
+
/** A pending row is sent its confirmation again only once this long has passed since the last one. */
|
|
1278
|
+
declare const ALERT_CONFIRMATION_INTERVAL_MS = 600000;
|
|
1279
|
+
/** Whether a row's last confirmation, if any, was sent at least the interval before `now`. */
|
|
1280
|
+
declare function confirmationDue(row: AlertSubscription, now: Date): boolean;
|
|
1121
1281
|
interface AlertSubscribeInput {
|
|
1122
1282
|
email: string;
|
|
1123
1283
|
variantId: string;
|
|
@@ -1136,7 +1296,8 @@ interface AlertConfirmed {
|
|
|
1136
1296
|
interface AlertService {
|
|
1137
1297
|
/**
|
|
1138
1298
|
* Answers `pending` whatever the address's account or subscription, so the answer reveals neither; every accepted
|
|
1139
|
-
* request writes the row once.
|
|
1299
|
+
* request writes the row once. A new or reissued row is sent its confirmation; a row already pending only once the
|
|
1300
|
+
* interval has passed since its last one.
|
|
1140
1301
|
*/
|
|
1141
1302
|
subscribe(input: AlertSubscribeInput): Promise<{
|
|
1142
1303
|
status: 'pending';
|
|
@@ -1147,9 +1308,12 @@ interface AlertService {
|
|
|
1147
1308
|
}>;
|
|
1148
1309
|
/**
|
|
1149
1310
|
* In the transaction that marks an alert's send: a back-in-stock row is `fired`, a price-drop row stays `active` with
|
|
1150
|
-
* the trigger's price as its baseline; `alert.sent.v1` names the trigger.
|
|
1311
|
+
* the trigger's price as its baseline; `alert.sent.v1` names the trigger. A row no longer `active` is left as it is,
|
|
1312
|
+
* with no event: answers whether the row moved.
|
|
1151
1313
|
*/
|
|
1152
|
-
recordSent(tx: Tx, subscription: AlertSubscription, trigger: NymbalEvent<unknown>): Promise<
|
|
1314
|
+
recordSent(tx: Tx, subscription: AlertSubscription, trigger: NymbalEvent<unknown>): Promise<boolean>;
|
|
1315
|
+
/** In the transaction that marks a confirmation's send: the row's interval starts at `at`. */
|
|
1316
|
+
recordConfirmationSent(tx: Tx, subscription: AlertSubscription, request: NymbalEvent<unknown>, at: Date): Promise<void>;
|
|
1153
1317
|
}
|
|
1154
1318
|
interface CreateAlertServiceDeps {
|
|
1155
1319
|
store: CommandStore;
|
|
@@ -1179,8 +1343,11 @@ interface OrderCreateDraftInput {
|
|
|
1179
1343
|
metadata?: Record<string, unknown>;
|
|
1180
1344
|
paymentIntentId?: string | null;
|
|
1181
1345
|
cartToken?: string | null;
|
|
1346
|
+
/** The source of the cart the order is placed from; `storefront` when not given. */
|
|
1347
|
+
source?: CartSource;
|
|
1182
1348
|
}
|
|
1183
|
-
|
|
1349
|
+
/** An imported order's source is always `import`. */
|
|
1350
|
+
interface OrderImportInput extends Omit<OrderCreateDraftInput, 'source'> {
|
|
1184
1351
|
orderNumber: string;
|
|
1185
1352
|
status: OrderStatus;
|
|
1186
1353
|
createdAt: Date;
|
|
@@ -1329,7 +1496,8 @@ declare function createCategoryService(deps: {
|
|
|
1329
1496
|
}): CategoryService;
|
|
1330
1497
|
|
|
1331
1498
|
interface CartService {
|
|
1332
|
-
|
|
1499
|
+
/** The live cart on `token`, or a new one opened with `source`; an existing cart keeps its own source. */
|
|
1500
|
+
getOrCreate(token?: string, customerId?: string | null, source?: CartSource): Promise<Cart>;
|
|
1333
1501
|
get(token: string): Promise<Cart | null>;
|
|
1334
1502
|
addItem(token: string, item: Omit<CartItem, 'qty'> & {
|
|
1335
1503
|
qty?: number;
|
|
@@ -1339,13 +1507,29 @@ interface CartService {
|
|
|
1339
1507
|
clear(token: string): Promise<Cart>;
|
|
1340
1508
|
merge(guestToken: string, customerToken: string): Promise<Cart>;
|
|
1341
1509
|
attachCustomer(token: string, customerId: string): Promise<Cart>;
|
|
1510
|
+
/** The customer's cart once the guest cart at `guestToken` is folded into it; null when there is neither. */
|
|
1511
|
+
signIn(guestToken: string | undefined, customerId: string): Promise<Cart | null>;
|
|
1512
|
+
}
|
|
1513
|
+
/** A variant can go on a cart while it and its product are both active. */
|
|
1514
|
+
declare function isSellable(variant: Pick<Variant, 'status'>, product: Pick<Product, 'status'>): boolean;
|
|
1515
|
+
/** Which variants can be on a cart: the variant and its product both exist and are sellable. */
|
|
1516
|
+
interface CartCatalogue {
|
|
1517
|
+
sellable(tx: ReadTx, variantIds: readonly string[]): Promise<ReadonlySet<string>>;
|
|
1342
1518
|
}
|
|
1519
|
+
declare function createCartCatalogue(repos: {
|
|
1520
|
+
variant: VariantRepository;
|
|
1521
|
+
product: ProductRepository;
|
|
1522
|
+
}): CartCatalogue;
|
|
1343
1523
|
interface CreateCartServiceDeps {
|
|
1344
1524
|
store: CommandStore;
|
|
1345
1525
|
carts: CartRepository;
|
|
1346
1526
|
publisher: EventPublisher;
|
|
1347
1527
|
logger: Logger;
|
|
1348
1528
|
currency: string;
|
|
1529
|
+
/** Which variants a cart may keep at a sign-in; the store's variants and products by default. */
|
|
1530
|
+
catalogue?: CartCatalogue;
|
|
1531
|
+
/** Finds a guest cart's checkout in progress, which keeps that cart at a sign-in; the store's orders by default. */
|
|
1532
|
+
pendingOrders?: Pick<OrderRepository, 'findPendingByCartToken'>;
|
|
1349
1533
|
ttlSeconds?: number;
|
|
1350
1534
|
now?: () => Date;
|
|
1351
1535
|
}
|
|
@@ -1428,6 +1612,11 @@ interface CreateAuthServiceDeps {
|
|
|
1428
1612
|
issuer?: string;
|
|
1429
1613
|
}
|
|
1430
1614
|
declare function parseDurationToMs(s: string): number;
|
|
1615
|
+
/**
|
|
1616
|
+
* How long after its first rotation a refresh token may be rotated again: two tabs restored together present one cookie
|
|
1617
|
+
* at once. The window is anchored at that first rotation and never slides.
|
|
1618
|
+
*/
|
|
1619
|
+
declare const REFRESH_REUSE_WINDOW_MS = 30000;
|
|
1431
1620
|
declare function createAuthService(deps: CreateAuthServiceDeps): AuthService;
|
|
1432
1621
|
|
|
1433
1622
|
interface ReserveStockResult {
|
|
@@ -1465,6 +1654,13 @@ interface BeginCheckoutInput {
|
|
|
1465
1654
|
billingAddress: Address;
|
|
1466
1655
|
shippingAddress: Address;
|
|
1467
1656
|
notes?: string;
|
|
1657
|
+
/**
|
|
1658
|
+
* A payment credential an agent holds for the buyer (an ACP Shared Payment Token), charged at once. No one is there
|
|
1659
|
+
* to complete a challenge, so an intent that neither succeeds nor fails is cancelled.
|
|
1660
|
+
*/
|
|
1661
|
+
delegatedPayment?: {
|
|
1662
|
+
token: string;
|
|
1663
|
+
};
|
|
1468
1664
|
}
|
|
1469
1665
|
interface BeginCheckoutResult {
|
|
1470
1666
|
orderId: string;
|
|
@@ -1502,7 +1698,11 @@ interface CheckoutService {
|
|
|
1502
1698
|
* there is an order, a history note) and leaves the order as it was. Joins the caller's transaction.
|
|
1503
1699
|
*/
|
|
1504
1700
|
finalize(paymentIntentId: string, paid: CapturedPayment): Promise<FinalizeResult>;
|
|
1505
|
-
|
|
1701
|
+
/**
|
|
1702
|
+
* Cancels an order and gives back the stock it still holds, in one transaction under the order's row lock. `actor`
|
|
1703
|
+
* names who cancelled in the order's history.
|
|
1704
|
+
*/
|
|
1705
|
+
cancel(orderId: string, reason: string, actor?: string): Promise<Order>;
|
|
1506
1706
|
}
|
|
1507
1707
|
/** The admin's side of a checkout: a payment taken outside the store. */
|
|
1508
1708
|
interface ManualPayments {
|
|
@@ -1603,9 +1803,129 @@ interface RecentlyViewedService {
|
|
|
1603
1803
|
}
|
|
1604
1804
|
declare function createRecentlyViewedService(deps: RecentlyViewedServiceDeps): RecentlyViewedService;
|
|
1605
1805
|
|
|
1806
|
+
/** The order statuses that make a review verified: the order was paid and not wholly refunded or cancelled. */
|
|
1807
|
+
declare const REVIEW_VERIFYING_STATUSES: readonly OrderStatus[];
|
|
1808
|
+
interface ReviewSubmitInput {
|
|
1809
|
+
customerId: string;
|
|
1810
|
+
productId: string;
|
|
1811
|
+
rating: number;
|
|
1812
|
+
title: string;
|
|
1813
|
+
body: string;
|
|
1814
|
+
}
|
|
1815
|
+
interface ReviewService {
|
|
1816
|
+
/**
|
|
1817
|
+
* Files the signed-in customer's review of an active product through the reviews adapter, as theirs and verified
|
|
1818
|
+
* by their newest paid order holding the product, and publishes `review.submitted.v1` for what the adapter stored.
|
|
1819
|
+
*/
|
|
1820
|
+
submit(input: ReviewSubmitInput): Promise<Review>;
|
|
1821
|
+
}
|
|
1822
|
+
interface ReviewServiceDeps {
|
|
1823
|
+
store: CommandStore;
|
|
1824
|
+
repos: Pick<Repositories, 'product' | 'customer' | 'order'>;
|
|
1825
|
+
publisher: EventPublisher;
|
|
1826
|
+
reviews: ReviewsAdapter;
|
|
1827
|
+
logger: Logger;
|
|
1828
|
+
}
|
|
1829
|
+
declare function createReviewService(deps: ReviewServiceDeps): ReviewService;
|
|
1830
|
+
|
|
1831
|
+
/** A command tool's call, admitted by its route's gate and schema, as the proposal it is kept as. */
|
|
1832
|
+
interface Proposal {
|
|
1833
|
+
tool: string;
|
|
1834
|
+
command: string;
|
|
1835
|
+
/** The arguments as sent, less the idempotency key and the handles. */
|
|
1836
|
+
args: Record<string, unknown>;
|
|
1837
|
+
/** Argument name to value, for the handles the call carried (a cart). */
|
|
1838
|
+
handles?: Record<string, string>;
|
|
1839
|
+
idempotencyKey?: string;
|
|
1840
|
+
caller: Caller;
|
|
1841
|
+
correlationId: string;
|
|
1842
|
+
at: string;
|
|
1843
|
+
}
|
|
1844
|
+
/** What a proposal's route answered when it ran: the tool's result, and the status and error it was answered with. */
|
|
1845
|
+
interface Executed {
|
|
1846
|
+
result: ToolResult;
|
|
1847
|
+
outcome: {
|
|
1848
|
+
status: number;
|
|
1849
|
+
code?: string;
|
|
1850
|
+
message?: string;
|
|
1851
|
+
};
|
|
1852
|
+
}
|
|
1853
|
+
/** Who approves a command at the call, or null when an admin must. */
|
|
1854
|
+
type Policy = (command: string) => ProposalDecider | null;
|
|
1855
|
+
/**
|
|
1856
|
+
* The policy `agents` sets. `writes: 'apply'` approves every command; `autoApprove` the commands it names, each of
|
|
1857
|
+
* which must be a route's command that moves no money (`provider`), or createApp stops.
|
|
1858
|
+
*/
|
|
1859
|
+
declare function policyOf(agents: NymbalConfig['agents']): Policy;
|
|
1860
|
+
|
|
1861
|
+
interface ProposalServiceDeps {
|
|
1862
|
+
store: CommandStore;
|
|
1863
|
+
proposals: ProposalRepository;
|
|
1864
|
+
publisher: EventPublisher;
|
|
1865
|
+
/** Runs a stored proposal's request through its route as `auth`. */
|
|
1866
|
+
execute(row: ProposalRecord, auth: RequestAuth | undefined): Promise<Executed>;
|
|
1867
|
+
}
|
|
1868
|
+
interface ProposalService {
|
|
1869
|
+
/** Keeps a proposal pending; a proposer's repeat under one idempotency key answers the row it already has. */
|
|
1870
|
+
propose(p: Proposal): Promise<ProposalView>;
|
|
1871
|
+
/** Approves a pending proposal and runs it as the approving admin; answers the settled row. */
|
|
1872
|
+
approve(id: string, by: RequestAuth): Promise<ProposalView>;
|
|
1873
|
+
reject(id: string, by: RequestAuth, reason?: string): Promise<ProposalView>;
|
|
1874
|
+
/** Approves a pending proposal by a policy and runs it as `executor`, answering what its route answered. */
|
|
1875
|
+
run(id: string, by: ProposalDecider, executor: RequestAuth | undefined): Promise<Executed>;
|
|
1876
|
+
get(id: string): Promise<ProposalView | null>;
|
|
1877
|
+
list(q: ProposalQuery): Promise<ProposalPage>;
|
|
1878
|
+
}
|
|
1879
|
+
/**
|
|
1880
|
+
* Proposals as rows a person or a policy decides. A decision is one conditional update, so of two deciders one wins
|
|
1881
|
+
* and the other is told the status it lost to. The command runs between the decision and the settlement, in no
|
|
1882
|
+
* transaction of this service's: a provider command commits its own steps around the money it moves.
|
|
1883
|
+
*/
|
|
1884
|
+
declare function createProposalService(deps: ProposalServiceDeps): ProposalService;
|
|
1885
|
+
|
|
1886
|
+
/** A record already gone is `absent`, not an error, so a removal stopped half way can run again. */
|
|
1887
|
+
type RemovalOutcome = 'removed' | 'absent';
|
|
1888
|
+
/** What the store did on its own since an import began: orders and reviews no import created. */
|
|
1889
|
+
interface StoreActivity {
|
|
1890
|
+
/** Orders not held, created since; and held orders that have been shipped, refunded or given a key since. */
|
|
1891
|
+
orders: number;
|
|
1892
|
+
/** Reviews not held, submitted since. */
|
|
1893
|
+
reviews: number;
|
|
1894
|
+
}
|
|
1895
|
+
/**
|
|
1896
|
+
* Takes records an import created back out of the store. Each removal is one transaction under its own audit entry.
|
|
1897
|
+
* Products and categories go through their own services' `delete`.
|
|
1898
|
+
*/
|
|
1899
|
+
interface ImportRemovalService {
|
|
1900
|
+
/** Deletes the order with its history, refunds, access keys and shipment, and publishes `order.deleted.v1`. */
|
|
1901
|
+
removeOrder(id: string): Promise<RemovalOutcome>;
|
|
1902
|
+
/** Deletes the customer and its refresh tokens, and publishes `customer.deleted.v1`. */
|
|
1903
|
+
removeCustomer(id: string): Promise<RemovalOutcome>;
|
|
1904
|
+
/** Deletes the review row; as a submission publishes nothing, neither does this. */
|
|
1905
|
+
removeReview(id: string): Promise<RemovalOutcome>;
|
|
1906
|
+
activitySince(since: string, held: {
|
|
1907
|
+
orders: string[];
|
|
1908
|
+
reviews: string[];
|
|
1909
|
+
}): Promise<StoreActivity>;
|
|
1910
|
+
}
|
|
1911
|
+
interface ImportRemovalServiceDeps {
|
|
1912
|
+
store: CommandStore;
|
|
1913
|
+
repos: Repositories;
|
|
1914
|
+
publisher: EventPublisher;
|
|
1915
|
+
logger: Logger;
|
|
1916
|
+
}
|
|
1917
|
+
declare function createImportRemovalService(deps: ImportRemovalServiceDeps): ImportRemovalService;
|
|
1918
|
+
|
|
1606
1919
|
/** A confirm or unsubscribe link's bearer credential: 32 random bytes, base64url (43 characters). */
|
|
1607
1920
|
declare function newAlertToken(): string;
|
|
1608
1921
|
|
|
1922
|
+
/**
|
|
1923
|
+
* A product description as the store keeps it: an HTML fragment of the allowlisted tags, links only to http(s) and
|
|
1924
|
+
* mailto with `rel="nofollow noopener noreferrer"`, no other attribute, and text `<` and `&` written as entities.
|
|
1925
|
+
* Sanitising its own output changes nothing.
|
|
1926
|
+
*/
|
|
1927
|
+
declare function sanitizeDescription(html: string): string;
|
|
1928
|
+
|
|
1609
1929
|
/** A `native` email adapter only logs; any other (`smtp`, a project's own) is taken to reach a mailbox. */
|
|
1610
1930
|
declare function emailDelivers(email: EmailAdapter): boolean;
|
|
1611
1931
|
interface ServiceRegistry {
|
|
@@ -1621,6 +1941,9 @@ interface ServiceRegistry {
|
|
|
1621
1941
|
search: SearchService;
|
|
1622
1942
|
recentlyViewed: RecentlyViewedService;
|
|
1623
1943
|
alert: AlertService;
|
|
1944
|
+
review: ReviewService;
|
|
1945
|
+
proposals: ProposalService;
|
|
1946
|
+
importRemoval: ImportRemovalService;
|
|
1624
1947
|
}
|
|
1625
1948
|
interface BuildServicesDeps {
|
|
1626
1949
|
config: NymbalConfig;
|
|
@@ -1631,8 +1954,11 @@ interface BuildServicesDeps {
|
|
|
1631
1954
|
payments: PaymentsAdapter;
|
|
1632
1955
|
searchAdapter: SearchAdapter;
|
|
1633
1956
|
email: EmailAdapter;
|
|
1957
|
+
reviews: ReviewsAdapter;
|
|
1634
1958
|
/** The effective JWT secret (`resolveAuthSecret`), not the config's field. */
|
|
1635
1959
|
jwtSecret: string;
|
|
1960
|
+
/** Runs a stored proposal through its route: the tool surface `attachHttp` builds. */
|
|
1961
|
+
executeProposal: ProposalServiceDeps['execute'];
|
|
1636
1962
|
}
|
|
1637
1963
|
declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
|
|
1638
1964
|
|
|
@@ -1642,7 +1968,10 @@ interface DeclaredSlot {
|
|
|
1642
1968
|
provider: string;
|
|
1643
1969
|
declared: readonly AdapterSetting[];
|
|
1644
1970
|
}
|
|
1645
|
-
/**
|
|
1971
|
+
/**
|
|
1972
|
+
* A store from before migration 0008 has no `settings` relation: it holds no settings. drizzle wraps a node-postgres
|
|
1973
|
+
* error in its own, the driver's as `cause`; better-sqlite3's arrive unwrapped.
|
|
1974
|
+
*/
|
|
1646
1975
|
declare function isMissingSettingsTable(error: unknown): boolean;
|
|
1647
1976
|
|
|
1648
1977
|
interface RegisterAllRoutesDeps {
|
|
@@ -1660,6 +1989,8 @@ interface RegisterAllRoutesDeps {
|
|
|
1660
1989
|
jwtSecret: string;
|
|
1661
1990
|
/** The admin's dist directory, or null for a 404 that says how to build it; undefined serves no admin. */
|
|
1662
1991
|
adminRoot?: string | null | undefined;
|
|
1992
|
+
/** The tools the admin's assistant runs, built over these routes once they are registered. */
|
|
1993
|
+
assistantTools: () => ToolSurface | undefined;
|
|
1663
1994
|
}
|
|
1664
1995
|
declare function registerAllRoutes(deps: RegisterAllRoutesDeps): void;
|
|
1665
1996
|
|
|
@@ -1689,9 +2020,133 @@ interface RouteSchema {
|
|
|
1689
2020
|
* the service commits its own steps around the provider call, so what it holds is committed before money moves.
|
|
1690
2021
|
*/
|
|
1691
2022
|
provider?: true;
|
|
2023
|
+
/**
|
|
2024
|
+
* Kept from agents: the route mints or clears credentials, streams, takes provider-signed bytes, serves files,
|
|
2025
|
+
* records a browser's views or spends the store's AI key.
|
|
2026
|
+
*/
|
|
2027
|
+
tool?: false;
|
|
2028
|
+
/**
|
|
2029
|
+
* The cookies a route reads its caller's state from, as the tool arguments that carry it instead: argument name to
|
|
2030
|
+
* cookie name. An agent holds no cookie jar, so the cart travels as a `cart` handle.
|
|
2031
|
+
*/
|
|
2032
|
+
handles?: Record<string, string>;
|
|
2033
|
+
/**
|
|
2034
|
+
* The customer fields a read's answer can carry. The assistant sends a tool's result to the AI provider as it is, so
|
|
2035
|
+
* `agents.assistant.customerData: false` leaves every marked route off the assistant, and the docs list them.
|
|
2036
|
+
*/
|
|
2037
|
+
personal?: readonly PersonalField[];
|
|
1692
2038
|
}
|
|
2039
|
+
/** A customer field a route's answer can carry. */
|
|
2040
|
+
type PersonalField = 'email' | 'phone' | 'address';
|
|
1693
2041
|
declare const routeSchemas: Record<string, RouteSchema>;
|
|
1694
2042
|
|
|
2043
|
+
/**
|
|
2044
|
+
* The refusal for a caller who fails a route's gate, or null when the caller passes it. `scope` is the least caller
|
|
2045
|
+
* it admits: `customer` for any signed-in user, a role's name for that role.
|
|
2046
|
+
*/
|
|
2047
|
+
type Gate = ((ctx: RequestContext) => ResponseEnvelope | null) & {
|
|
2048
|
+
readonly scope?: 'customer' | Role;
|
|
2049
|
+
};
|
|
2050
|
+
|
|
2051
|
+
type Scope = ToolDefinition['scope'];
|
|
2052
|
+
interface RecordedRoute {
|
|
2053
|
+
/** The handler as the HTTP adapter runs it: gate, schema, correlation, audit and idempotency composed. */
|
|
2054
|
+
handler: RouteHandler;
|
|
2055
|
+
gate: Gate | undefined;
|
|
2056
|
+
scope: Scope;
|
|
2057
|
+
}
|
|
2058
|
+
/** Every route `registerAllRoutes` registered, by `"<METHOD> <path>"`; stream routes are not tools and not kept. */
|
|
2059
|
+
declare class RouteTable {
|
|
2060
|
+
#private;
|
|
2061
|
+
record(key: string, handler: RouteHandler): void;
|
|
2062
|
+
get(key: string): RecordedRoute | undefined;
|
|
2063
|
+
keys(): string[];
|
|
2064
|
+
}
|
|
2065
|
+
/** The innermost adapter of the route chain: it keeps each composed handler in `table`, then registers it. */
|
|
2066
|
+
declare function recordingAdapter(table: RouteTable, adapter: HttpAdapter): HttpAdapter;
|
|
2067
|
+
|
|
2068
|
+
/** `admin.products.create` → `admin_products_create`: not every model API that lists MCP tools accepts a dot. */
|
|
2069
|
+
declare function toolName(dotted: string): string;
|
|
2070
|
+
/**
|
|
2071
|
+
* One JSON Schema object for a route's input: the keys of its params, query and body side by side, each as the route
|
|
2072
|
+
* parses it. A key two parts share would make the call ambiguous, so it is refused.
|
|
2073
|
+
*/
|
|
2074
|
+
declare function jsonSchemaOf(entry: RouteSchema): JsonSchemaObject;
|
|
2075
|
+
/**
|
|
2076
|
+
* The agent tools of the routes in `table`: one per route the registry does not keep from agents (`tool: false`).
|
|
2077
|
+
* Stream routes are never in the table.
|
|
2078
|
+
*/
|
|
2079
|
+
declare function toolsOf(table: RouteTable): ToolDefinition[];
|
|
2080
|
+
|
|
2081
|
+
interface InvokerDeps {
|
|
2082
|
+
table: RouteTable;
|
|
2083
|
+
tools: ToolDefinition[];
|
|
2084
|
+
proposals: Pick<ProposalService, 'propose' | 'run'>;
|
|
2085
|
+
policy: Policy;
|
|
2086
|
+
logger: Logger;
|
|
2087
|
+
}
|
|
2088
|
+
/** The tool surface, and how a stored proposal is run through its route (for the proposal service, not for agents). */
|
|
2089
|
+
interface Invoker extends ToolSurface {
|
|
2090
|
+
execute(row: ProposalRecord, auth: RequestAuth | undefined): Promise<Executed>;
|
|
2091
|
+
}
|
|
2092
|
+
/**
|
|
2093
|
+
* Runs agent tools as the routes they are: each call is a request built from the arguments and handed to the
|
|
2094
|
+
* composed handler the HTTP adapter runs, so the gate, the schema, correlation, audit and idempotency hold for it as
|
|
2095
|
+
* for a request over HTTP. A command tool stops after the gate and the schema and becomes a proposal: an admin's is
|
|
2096
|
+
* kept for an admin to decide, a shopper's only when a policy approves it, and one a policy approves runs at once.
|
|
2097
|
+
*/
|
|
2098
|
+
declare function createInvoker(deps: InvokerDeps): Invoker;
|
|
2099
|
+
|
|
2100
|
+
/** The agent name every tool call, proposal and audit entry of the assistant carries. */
|
|
2101
|
+
declare const ASSISTANT_AGENT = "nymbal-assistant";
|
|
2102
|
+
interface AssistantDeps {
|
|
2103
|
+
ai: AiAdapter;
|
|
2104
|
+
/** The tools as the assistant runs them: writes become proposals unless `agents.autoApprove` lists them. */
|
|
2105
|
+
tools: ToolSurface;
|
|
2106
|
+
proposals: Pick<ProposalService, 'get'>;
|
|
2107
|
+
logger: Logger;
|
|
2108
|
+
/** The store's name and currency, for the model's instructions. */
|
|
2109
|
+
store?: {
|
|
2110
|
+
name: string;
|
|
2111
|
+
currency: string;
|
|
2112
|
+
};
|
|
2113
|
+
limits?: {
|
|
2114
|
+
maxSteps?: number;
|
|
2115
|
+
turnMs?: number;
|
|
2116
|
+
resultChars?: number;
|
|
2117
|
+
};
|
|
2118
|
+
/** `agents.assistant.customerData`: false leaves out every tool whose answer carries a customer's details. */
|
|
2119
|
+
customerData?: boolean;
|
|
2120
|
+
}
|
|
2121
|
+
interface AssistantTurn {
|
|
2122
|
+
/** The turn's id, the prefix of each call's correlation id; one is minted when absent. */
|
|
2123
|
+
turnId?: string;
|
|
2124
|
+
/** The signed-in admin, as agent `nymbal-assistant`. */
|
|
2125
|
+
caller: Caller;
|
|
2126
|
+
/** The conversation so far as the admin's browser holds it; the last turn is the question. */
|
|
2127
|
+
messages: Array<{
|
|
2128
|
+
role: 'user' | 'assistant';
|
|
2129
|
+
content: string;
|
|
2130
|
+
}>;
|
|
2131
|
+
/** The admin route the panel was opened on, e.g. `/products/ceramic-mug`. */
|
|
2132
|
+
page?: string;
|
|
2133
|
+
}
|
|
2134
|
+
type Stream = NonNullable<AiAdapter['chatStream']>;
|
|
2135
|
+
/**
|
|
2136
|
+
* The adapter's own `chatStream`, or for an adapter with only `chat` its answer as one text event, its calls and
|
|
2137
|
+
* `done`, so an ai adapter that cannot stream still runs the assistant. A result without `toolCalls` (an adapter of the
|
|
2138
|
+
* older contract) is read as one with none.
|
|
2139
|
+
*/
|
|
2140
|
+
declare function streamOf(ai: AiAdapter): Stream;
|
|
2141
|
+
/**
|
|
2142
|
+
* One assistant turn: the model is called with the store's tools, each tool it asks for runs through the tool surface
|
|
2143
|
+
* as the admin, and its result goes back to it, until it answers without calls. `emit` receives every frame; the turn
|
|
2144
|
+
* ends with one `done` or one `error` frame, or with none when `signal` aborts (the merchant has gone). It is bounded by
|
|
2145
|
+
* `maxSteps` model requests, `turnMs`, ten calls per reply, ten writes and 64 000 characters of results. Each call
|
|
2146
|
+
* carries its own correlation id, `<turnId>.<n>`, and logs one line without its arguments or result.
|
|
2147
|
+
*/
|
|
2148
|
+
declare function runAssistantTurn(deps: AssistantDeps, turn: AssistantTurn, emit: (frame: AssistantFrame) => void, signal?: AbortSignal): Promise<void>;
|
|
2149
|
+
|
|
1695
2150
|
interface NymbalApp {
|
|
1696
2151
|
platform: Platform;
|
|
1697
2152
|
repos: Repositories;
|
|
@@ -1700,11 +2155,22 @@ interface NymbalApp {
|
|
|
1700
2155
|
publisher: EventPublisher;
|
|
1701
2156
|
/** Delivers the event log to the bus; started by createApp, stopped by stop(). */
|
|
1702
2157
|
relay: Relay;
|
|
2158
|
+
/**
|
|
2159
|
+
* The trusted proxies, client-address header and origin lock, resolved once from the environment, the config and the
|
|
2160
|
+
* security adapter's contribution: the block every HTTP server for this app is built with.
|
|
2161
|
+
*/
|
|
2162
|
+
network: ResolvedNetwork;
|
|
1703
2163
|
/**
|
|
1704
2164
|
* Registers the API on the adapter. The admin is served at /admin/ when `adminRoot` is passed (its dist directory,
|
|
1705
2165
|
* or null for a 404 that says how to build it) or `NYMBAL_ADMIN_DIST` is set.
|
|
1706
2166
|
*/
|
|
1707
2167
|
attachHttp(adapter: HttpAdapter, options?: AttachHttpOptions): Promise<void>;
|
|
2168
|
+
/** The API's routes as agent tools, run in process through the handlers `attachHttp` registered; set by it. */
|
|
2169
|
+
readonly mcp: ToolSurface | undefined;
|
|
2170
|
+
/** The routes as the admin's assistant runs them: as `mcp`, but only `agents.autoApprove` applies a write. */
|
|
2171
|
+
readonly assistantTools: ToolSurface | undefined;
|
|
2172
|
+
/** The agent surfaces (UCP) and crawl files, over `mcp`; set by `attachHttp` once `mcp` is. */
|
|
2173
|
+
readonly agents: AgentSurfaces | undefined;
|
|
1708
2174
|
/** Each slot's provider and its adapter's own `capabilities()`; an ai slot of `none` offers nothing. */
|
|
1709
2175
|
capabilities(): CapabilitiesReport;
|
|
1710
2176
|
stop(): Promise<void>;
|
|
@@ -1724,9 +2190,186 @@ interface CreateAppOptions extends ResolvePrimitivesOptions {
|
|
|
1724
2190
|
adapters?: InjectedAdapters;
|
|
1725
2191
|
/** How the event relay retries a failed delivery (`createRelay`). */
|
|
1726
2192
|
relay?: Pick<CreateRelayOptions, 'maxAttempts' | 'retryDelayMs' | 'intervalMs' | 'now'>;
|
|
2193
|
+
/** How often expired and used refresh tokens are deleted; tests shorten it. */
|
|
2194
|
+
refreshTokenSweep?: {
|
|
2195
|
+
intervalMs?: number;
|
|
2196
|
+
};
|
|
1727
2197
|
}
|
|
1728
2198
|
declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
|
|
1729
2199
|
|
|
2200
|
+
type GoldenKind = 'read' | 'write' | 'none';
|
|
2201
|
+
/** A fact the answer must hold: a text, or any one of several (an amount in the store's format, or as digits). */
|
|
2202
|
+
type GoldenFact = string | readonly string[];
|
|
2203
|
+
/** The orders the golden store places, by the part each plays in a question. */
|
|
2204
|
+
type GoldenOrderPart = 'placed' | 'unpaid' | 'waiting' | 'refunded' | 'paid';
|
|
2205
|
+
interface GoldenOrder {
|
|
2206
|
+
id: string;
|
|
2207
|
+
orderNumber: string;
|
|
2208
|
+
email: string;
|
|
2209
|
+
capturedMinor: number;
|
|
2210
|
+
refundedMinor: number;
|
|
2211
|
+
}
|
|
2212
|
+
/** The golden store as a question reads it, at the moment the question is asked. */
|
|
2213
|
+
interface GoldenStoreView {
|
|
2214
|
+
currency: string;
|
|
2215
|
+
/** A read tool's result, run as the admin. */
|
|
2216
|
+
read(tool: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
2217
|
+
order(part: GoldenOrderPart): Promise<GoldenOrder>;
|
|
2218
|
+
/** A seeded product's id and its first variant's id, by slug. */
|
|
2219
|
+
product(slug: string): Promise<{
|
|
2220
|
+
id: string;
|
|
2221
|
+
variantId: string;
|
|
2222
|
+
}>;
|
|
2223
|
+
money(minor: number): GoldenFact;
|
|
2224
|
+
}
|
|
2225
|
+
interface GoldenProposal {
|
|
2226
|
+
tool: string;
|
|
2227
|
+
argsMatch(args: Record<string, unknown>, store: GoldenStoreView): boolean | Promise<boolean>;
|
|
2228
|
+
}
|
|
2229
|
+
interface GoldenQuestion {
|
|
2230
|
+
id: string;
|
|
2231
|
+
/** What the merchant asks; `{order:<part>}` is the number of the golden store's order for that part. */
|
|
2232
|
+
ask: string;
|
|
2233
|
+
/** The admin page the panel is opened on. */
|
|
2234
|
+
page?: string;
|
|
2235
|
+
kind: GoldenKind;
|
|
2236
|
+
/** Tools the answer must call; `a|b` is either. */
|
|
2237
|
+
calls?: string[];
|
|
2238
|
+
/** Tools it must never call. */
|
|
2239
|
+
never?: string[];
|
|
2240
|
+
/** For a write: exactly these proposals, left pending. */
|
|
2241
|
+
proposals?: GoldenProposal[];
|
|
2242
|
+
/** The facts the answer must hold, read from the store when the question is asked. */
|
|
2243
|
+
answer?: (store: GoldenStoreView) => Promise<GoldenFact[]>;
|
|
2244
|
+
/** The answer reads text a shopper or an import wrote that asks for a write the merchant did not. */
|
|
2245
|
+
injection?: boolean;
|
|
2246
|
+
}
|
|
2247
|
+
declare const GOLDEN_QUESTIONS: readonly GoldenQuestion[];
|
|
2248
|
+
/**
|
|
2249
|
+
* Fills an empty store with what the golden questions ask about, through its services: the demo seed, five orders
|
|
2250
|
+
* (two unpaid, three paid by the native payments stub, one of those partly refunded) and one pending proposal, and the
|
|
2251
|
+
* injected text: a pending review of the Stoneware Mug, checkout notes on the placed order and Shape Up's description.
|
|
2252
|
+
*/
|
|
2253
|
+
declare function goldenStore(app: NymbalApp): Promise<void>;
|
|
2254
|
+
|
|
2255
|
+
interface GoldenResult {
|
|
2256
|
+
id: string;
|
|
2257
|
+
/** The question as asked, its order numbers filled in. */
|
|
2258
|
+
ask: string;
|
|
2259
|
+
ok: boolean;
|
|
2260
|
+
/** Why it failed, one line per check; empty when it passed. */
|
|
2261
|
+
reasons: string[];
|
|
2262
|
+
/** The tools the assistant called, in order. */
|
|
2263
|
+
calls: string[];
|
|
2264
|
+
/** The ids of the proposals the turn made. */
|
|
2265
|
+
proposals: string[];
|
|
2266
|
+
answer: string;
|
|
2267
|
+
}
|
|
2268
|
+
interface GoldenReport {
|
|
2269
|
+
passed: number;
|
|
2270
|
+
total: number;
|
|
2271
|
+
results: GoldenResult[];
|
|
2272
|
+
}
|
|
2273
|
+
interface RunGoldenOptions {
|
|
2274
|
+
/** Question ids to run; all of them when omitted. */
|
|
2275
|
+
only?: string[];
|
|
2276
|
+
onResult?: (result: GoldenResult) => void;
|
|
2277
|
+
}
|
|
2278
|
+
/**
|
|
2279
|
+
* Asks each golden question of the store's assistant, one conversation each, as the seeded admin on the golden store
|
|
2280
|
+
* (`goldenStore`), and checks what it called, what it proposed, what it changed and what it answered.
|
|
2281
|
+
*/
|
|
2282
|
+
declare function runGolden(app: NymbalApp, opts?: RunGoldenOptions): Promise<GoldenReport>;
|
|
2283
|
+
|
|
2284
|
+
/** The Universal Commerce Protocol release this store speaks. */
|
|
2285
|
+
declare const UCP_VERSION = "2026-08-25";
|
|
2286
|
+
/**
|
|
2287
|
+
* The business profile served at `/.well-known/ucp`: one shopping service over MCP and the catalogue and checkout
|
|
2288
|
+
* capabilities. Payment happens on the store's own checkout page, so it names no payment handler. Every URL is built
|
|
2289
|
+
* from the configured origins, so no request header can change a cached copy.
|
|
2290
|
+
*/
|
|
2291
|
+
declare function ucpProfile(urls: AgentSurfaceUrls): Record<string, unknown>;
|
|
2292
|
+
|
|
2293
|
+
/**
|
|
2294
|
+
* The name a UCP call travels under: the host of the platform profile its `meta` names, else the MCP client's name,
|
|
2295
|
+
* else `mcp-client`. Both arguments come from the agent, so anything malformed falls through rather than throws.
|
|
2296
|
+
*/
|
|
2297
|
+
declare function agentNameOf(meta: unknown, clientInfo: unknown): string;
|
|
2298
|
+
|
|
2299
|
+
interface UcpLink {
|
|
2300
|
+
type: string;
|
|
2301
|
+
url: string;
|
|
2302
|
+
title?: string | undefined;
|
|
2303
|
+
}
|
|
2304
|
+
|
|
2305
|
+
interface UcpSurfaceDeps {
|
|
2306
|
+
/** The app's route tools, which every UCP call runs through. */
|
|
2307
|
+
mcp: Pick<ToolSurface, 'call'>;
|
|
2308
|
+
/** The slug of the product a variant id belongs to, or null. */
|
|
2309
|
+
variants: (variantId: string) => Promise<string | null>;
|
|
2310
|
+
/** The live guest cart a token names, or null for an unknown, expired or customer-claimed one. */
|
|
2311
|
+
cart: (token: string) => Promise<Cart | null>;
|
|
2312
|
+
urls: () => AgentSurfaceUrls;
|
|
2313
|
+
links: readonly UcpLink[];
|
|
2314
|
+
}
|
|
2315
|
+
/**
|
|
2316
|
+
* The UCP shopping service over MCP: catalogue search and lookup, and a checkout the buyer completes on the store's
|
|
2317
|
+
* own page. Each call runs the store's routes through `mcp` as the calling agent, so their gates and schemas hold;
|
|
2318
|
+
* none runs a command tool, so nothing here places an order or moves stock.
|
|
2319
|
+
*/
|
|
2320
|
+
declare function createUcpSurface(deps: UcpSurfaceDeps): AgentSurfaceAdapter;
|
|
2321
|
+
|
|
2322
|
+
/** `ok` is a check with no health semantics (config, a package, migrations); the rest are a health report's. */
|
|
2323
|
+
type DiagnosisStatus = HealthStatus | 'ok';
|
|
2324
|
+
interface DiagnosisCheck {
|
|
2325
|
+
name: string;
|
|
2326
|
+
status: DiagnosisStatus;
|
|
2327
|
+
detail: string;
|
|
2328
|
+
}
|
|
2329
|
+
interface DiagnosisReport {
|
|
2330
|
+
checks: DiagnosisCheck[];
|
|
2331
|
+
/**
|
|
2332
|
+
* What the security adapter offers the HTTP layer (`network()`), read from the adapter built for `slot security`:
|
|
2333
|
+
* `unknown` when it failed to build or `network()` threw. Absent when the config did not parse.
|
|
2334
|
+
*/
|
|
2335
|
+
network?: {
|
|
2336
|
+
adapter: string;
|
|
2337
|
+
contribution: SecurityNetwork;
|
|
2338
|
+
} | 'unknown';
|
|
2339
|
+
/**
|
|
2340
|
+
* Whether the CDN sends the origin secret, present only when `NYMBAL_ORIGIN_SECRET` resolves: the security adapter's
|
|
2341
|
+
* answer, `unmanaged` when it cannot tell (no `originLockRule`), `unknown` when it failed to build, threw or timed out.
|
|
2342
|
+
*/
|
|
2343
|
+
originLock?: OriginLockRule | 'unknown' | 'unmanaged';
|
|
2344
|
+
}
|
|
2345
|
+
interface DiagnoseOptions {
|
|
2346
|
+
/** The project's adapters, one per slot whose provider is `custom`, as `createApp` takes them. */
|
|
2347
|
+
adapters?: InjectedAdapters;
|
|
2348
|
+
logger?: Logger;
|
|
2349
|
+
/** Each check's bound; `HEALTH_CHECK_TIMEOUT_MS` when not given. */
|
|
2350
|
+
timeoutMs?: number;
|
|
2351
|
+
env?: NodeJS.ProcessEnv;
|
|
2352
|
+
sqlitePath?: string;
|
|
2353
|
+
postgresUrl?: string;
|
|
2354
|
+
mediaRoot?: string;
|
|
2355
|
+
/** Where the migrations journal is read; the platform's own migrations when not given. */
|
|
2356
|
+
migrationsRoot?: string;
|
|
2357
|
+
}
|
|
2358
|
+
/**
|
|
2359
|
+
* Checks a project without changing it: its config, the packages its providers live in, the command store and its
|
|
2360
|
+
* migrations, and the health of every commerce slot, the security slot and every primitive. It builds what `createApp`
|
|
2361
|
+
* builds, through the same registry and constructors, and nothing more: no warm-up, no relay, no sweeper, no migrator,
|
|
2362
|
+
* no seed, and no primitive's `initialize()` (the security adapter's makes no request). The command store is opened read-only. Every connection is closed before it returns.
|
|
2363
|
+
*/
|
|
2364
|
+
declare function diagnose(input: NymbalConfig, options?: DiagnoseOptions): Promise<DiagnosisReport>;
|
|
2365
|
+
|
|
2366
|
+
/**
|
|
2367
|
+
* How ready the agent surfaces are, from the config and the environment alone. UCP checkout advertised without a
|
|
2368
|
+
* privacy and a terms link, or on a public plain-HTTP origin, is a warning; it is never `down`, because the surface
|
|
2369
|
+
* still serves and doctor's exit code belongs to the checks that stop a store.
|
|
2370
|
+
*/
|
|
2371
|
+
declare function agentReadiness(config: NymbalConfig, env: NodeJS.ProcessEnv): DiagnosisCheck;
|
|
2372
|
+
|
|
1730
2373
|
interface AuthSecret {
|
|
1731
2374
|
secret: string;
|
|
1732
2375
|
source: 'config' | 'env' | 'default';
|
|
@@ -1737,6 +2380,12 @@ interface AuthSecret {
|
|
|
1737
2380
|
* malformed one fails the boot even when the config's secret would win.
|
|
1738
2381
|
*/
|
|
1739
2382
|
declare function resolveAuthSecret(config: NymbalConfig, env: NodeJS.ProcessEnv): AuthSecret;
|
|
2383
|
+
/**
|
|
2384
|
+
* Whether a listen host is reachable from this machine only: 127.0.0.0/8, ::1 or localhost. The wildcards `0.0.0.0`
|
|
2385
|
+
* and `::` listen on every interface, so they are not. Any other spelling of a loopback address is treated as
|
|
2386
|
+
* reachable, which refuses more, never less.
|
|
2387
|
+
*/
|
|
2388
|
+
declare function isLoopbackHost(host: string): boolean;
|
|
1740
2389
|
|
|
1741
2390
|
/**
|
|
1742
2391
|
* Serves the admin's built files at /admin/ beside /api, one origin, so its relative API URLs and the refresh cookie
|
|
@@ -1796,6 +2445,18 @@ interface EventRetentionSweeperDeps {
|
|
|
1796
2445
|
*/
|
|
1797
2446
|
declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
|
|
1798
2447
|
|
|
2448
|
+
interface RefreshTokenSweeperDeps {
|
|
2449
|
+
store: CommandStore;
|
|
2450
|
+
refreshTokens: RefreshTokenRepository;
|
|
2451
|
+
logger: Logger;
|
|
2452
|
+
intervalMs?: number;
|
|
2453
|
+
}
|
|
2454
|
+
/**
|
|
2455
|
+
* Deletes expired refresh tokens and rotated ones whose reuse window has ended, so the table holds about one row per
|
|
2456
|
+
* session. A purged rotated token still reads as a replay: `refresh` treats a signed token with no row as one.
|
|
2457
|
+
*/
|
|
2458
|
+
declare function startRefreshTokenSweeper(deps: RefreshTokenSweeperDeps): SweeperHandle;
|
|
2459
|
+
|
|
1799
2460
|
/** What the config names for a slot: its provider, and the package the adapter comes from when it says. */
|
|
1800
2461
|
interface Choice {
|
|
1801
2462
|
provider: string;
|
|
@@ -1844,9 +2505,9 @@ declare function declaredSettings(mod: ProviderPackageModule | undefined): reado
|
|
|
1844
2505
|
/**
|
|
1845
2506
|
* v0.1 security adapter.
|
|
1846
2507
|
*
|
|
1847
|
-
* Rate limiting
|
|
1848
|
-
*
|
|
1849
|
-
*
|
|
2508
|
+
* Rate limiting and CSRF verification need the request before any middleware, so the
|
|
2509
|
+
* HTTP adapter runs them itself on every route (`FastifyHttpAdapter`'s guard); only
|
|
2510
|
+
* `GET /api/csrf` mints the CSRF cookie. This adapter only asserts
|
|
1850
2511
|
* static security headers via `HttpAdapter.setDefaultHeaders(...)`. A future
|
|
1851
2512
|
* WAF-native adapter will replace both layers.
|
|
1852
2513
|
*/
|
|
@@ -1911,7 +2572,8 @@ declare function createNativeReviewsAdapter(deps: {
|
|
|
1911
2572
|
|
|
1912
2573
|
declare function createNativeAnalyticsAdapter(logger: Logger): AnalyticsAdapter;
|
|
1913
2574
|
|
|
1914
|
-
|
|
2575
|
+
/** The store ships by hand: no rates, labels or tracking registration, so no word and none of their methods. */
|
|
2576
|
+
declare function createNativeShippingAdapter(_logger: Logger): ShippingAdapter;
|
|
1915
2577
|
|
|
1916
2578
|
declare function createNativeTaxAdapter(logger: Logger, defaultRate?: number): TaxAdapter;
|
|
1917
2579
|
|
|
@@ -1924,37 +2586,6 @@ interface CreateLoggerOptions {
|
|
|
1924
2586
|
}
|
|
1925
2587
|
declare function createLogger(options?: CreateLoggerOptions): Logger;
|
|
1926
2588
|
|
|
1927
|
-
/** `ok` is a check with no health semantics (config, a package, migrations); the rest are a health report's. */
|
|
1928
|
-
type DiagnosisStatus = HealthStatus | 'ok';
|
|
1929
|
-
interface DiagnosisCheck {
|
|
1930
|
-
name: string;
|
|
1931
|
-
status: DiagnosisStatus;
|
|
1932
|
-
detail: string;
|
|
1933
|
-
}
|
|
1934
|
-
interface DiagnosisReport {
|
|
1935
|
-
checks: DiagnosisCheck[];
|
|
1936
|
-
}
|
|
1937
|
-
interface DiagnoseOptions {
|
|
1938
|
-
/** The project's adapters, one per slot whose provider is `custom`, as `createApp` takes them. */
|
|
1939
|
-
adapters?: InjectedAdapters;
|
|
1940
|
-
logger?: Logger;
|
|
1941
|
-
/** Each check's bound; `HEALTH_CHECK_TIMEOUT_MS` when not given. */
|
|
1942
|
-
timeoutMs?: number;
|
|
1943
|
-
env?: NodeJS.ProcessEnv;
|
|
1944
|
-
sqlitePath?: string;
|
|
1945
|
-
postgresUrl?: string;
|
|
1946
|
-
mediaRoot?: string;
|
|
1947
|
-
/** Where the migrations journal is read; the platform's own migrations when not given. */
|
|
1948
|
-
migrationsRoot?: string;
|
|
1949
|
-
}
|
|
1950
|
-
/**
|
|
1951
|
-
* Checks a project without changing it: its config, the packages its providers live in, the command store and its
|
|
1952
|
-
* migrations, and the health of every commerce slot, the security slot and every primitive. It builds what `createApp`
|
|
1953
|
-
* builds, through the same registry and constructors, and nothing more: no warm-up, no relay, no sweeper, no migrator,
|
|
1954
|
-
* no seed, and no primitive's `initialize()` (the security adapter's makes no request). The command store is opened read-only. Every connection is closed before it returns.
|
|
1955
|
-
*/
|
|
1956
|
-
declare function diagnose(input: NymbalConfig, options?: DiagnoseOptions): Promise<DiagnosisReport>;
|
|
1957
|
-
|
|
1958
2589
|
interface SeedDeps {
|
|
1959
2590
|
config: NymbalConfig;
|
|
1960
2591
|
commandStore: CommandStore;
|
|
@@ -2186,5 +2817,5 @@ interface LocalFsMediaStorageOptions {
|
|
|
2186
2817
|
declare const LOCAL_FS_MEDIA_CAPABILITIES: readonly string[];
|
|
2187
2818
|
declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
|
|
2188
2819
|
|
|
2189
|
-
export { CATCH_UP_MARGIN_MS, CSRF_COOKIE, CSRF_HEADER, InMemoryDocumentStore, InProcessEventBus, LOCAL_FS_MEDIA_CAPABILITIES, PROVIDER_REFUND_REASON, READ_MODELS, READ_MODEL_NAMES, REDIS_DEFAULTS, RateLimiter, RebuildError, SECRETS_KEY_ENV, SECRETS_KEY_OLD_ENV, actorOf, appendAuditEntry, audit, auditEntriesInOrder, auditedCommand, buildAdapters, buildRepositories, buildServices, checkAdapterModule, createAlertService, createAlertSubscriptionRepository, createApp, createAuditEntryRepository, createAuthService, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createEmailSuppressionRepository, createEventBuilder, createEventLogRepository, createEventPublisher, createInventoryReservationRepository, createInventoryService, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderAccessKeyRepository, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createOrderShipmentRepository, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRecentlyViewedService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createSettingsRepository, createStockAdjustmentRepository, createVariantRepository, currentActor, currentCorrelationId, declaredSettings, decrypt, diagnose, diffReadModel, emailDelivers, encodeSearchCursor, encrypt, fillFromSettings, findAppliedByKey, importAdapterModule, installLine, isMissingSettingsTable, keyId, keyProblem, listAuditEntries, migrationState, missingPackage, newAlertToken, newCorrelationId, openReadModels, orderPayment, parseDurationToMs, rawClients, readSecretsKey, rebuild, refreshRefunded, registerAdminStaticRoute, registerAlertHandler, registerAlertRoutes, registerAllRoutes, registerHandlers, resolveAuthSecret, resolveChoice, resolvePrimitives, routeSchemas, runAsActor, runMigrations, runSeed, runWithCorrelation, scrub, seedCategories, seedProducts, settingAad, settlementOf, sqliteFile, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, withIdempotency };
|
|
2190
|
-
export type { AbandonedCart, AbandonedWindow, Actor, AdapterRegistry, AlertConfirmed, AlertService, AlertSubscribeInput, AlertSubscription, AlertSubscriptionPatch, AlertSubscriptionRepository, AlertSubscriptionRequest, AppliedEntry, AttachHttpOptions, AuditCursor, AuditEntryInsert, AuditEntryRepository, AuditFilter, AuditQuery, AuthSecret, AuthService, AuthTokens, BeginCheckoutInput, BeginCheckoutResult, BuildAdaptersDeps, BuildServicesDeps, CapabilitiesReport, CapabilitySlot, CapturedPayment, CartRepository, CartService, CatchUpFailure, CategoryCreateInput, CategoryInsert, CategoryRepository, CategoryService, CategoryUpdate, CategoryUpdateInput, CheckoutService, Choice, CollectionDiff, CommandStore, CommandStoreOptions, CommerceAdapters, CreateAlertServiceDeps, CreateAppOptions, CreateAuthServiceDeps, CreateCartServiceDeps, CreateCheckoutServiceDeps, CreateInventoryServiceDeps, CreateLoggerOptions, CreateOrderServiceDeps, CreatePlatformOptions, CreateProductServiceDeps, CreatePublisherOptions, CreateRefundServiceDeps, CreateRelayOptions, CustomerInsert, CustomerJwtPayload, CustomerNote, CustomerRepository, CustomerService, CustomerUpdate, CustomerWithHash, DiagnoseOptions, DiagnosisCheck, DiagnosisReport, DiagnosisStatus, EmailSuppressionInput, EmailSuppressionReason, EmailSuppressionRepository, EncryptedValue, EventArchiveWriter, EventBuilderContext, EventLogFilter, EventLogRepository, EventPublisher, EventRetentionSweeperDeps, FinalizeResult, IdempotencyOptions, ImportCustomerInput, InMemoryDocumentStoreOptions, InProcessEventBusOptions, InjectedAdapters, InventoryReservationRepository, InventoryService, KeysetPage, CategoryInsert$1 as LegacyCategoryInsert, CategoryRow as LegacyCategoryRow, ProductInsert$1 as LegacyProductInsert, ProductRow as LegacyProductRow, LocalFsMediaStorageOptions, LoggedEvent, MakeEventOptions, ManualPayments, MigrateOptions, MigrationState, NativeEmailAdapterConfig, NymbalApp, OpenReadModelsOptions, OrderAccessKeyInsert, OrderAccessKeyPurpose, OrderAccessKeyRepository, OrderCapture, OrderCreateDraftInput, OrderHistoryInsert, OrderHistoryRepository, OrderImportInput, OrderInsert, OrderKeyState, OrderRefundInsert, OrderRefundRepository, OrderRepository, OrderSequenceRepository, OrderService, OrderShipmentInput, OrderShipmentRepository, Platform, PlatformConnectionOptions, PostgresClient, Primitives, ProcessedEventRepository, ProductCategoryRepository, ProductCreateInput, ProductInsert, ProductRepository, ProductService, ProductUpdate, ProductUpdateInput, ProfileUpdate, PublishOptions, RawClients, ReadModel, ReadModelDiff, ReadModelName, ReadTx, RebuildDeps, RebuildReport, RebuildReportEntry, RecentlyViewedService, RecentlyViewedServiceDeps, RefreshTokenInsert, RefreshTokenRepository, RefreshTokenRow, RefundInput, RefundResult, RefundService, RegisterAlertHandlerDeps, RegisterAlertRoutesDeps, RegisterAllRoutesDeps, RegisterHandlersDeps, RegisterInput, Relay, Repositories, ReservationInsert, ReserveStockResult, Resolution, ResolvePrimitivesOptions, ReviewInsert, ReviewKey, ReviewRepository, RouteSchema, SearchService, SecretsKey, SeedCategory, SeedDeps, SeedProduct, SeedResult, ServiceRegistry, SettingRow, SettingSource, SettingValue, SettingsRepository, Settlement, SlotCapabilities, SqliteClient, StockAdjustmentInsert, StockAdjustmentRepository, StoreRepository, StoredCipher, SweeperHandle, Tx, VariantInsert, VariantPriceInput, VariantRepository, VariantUpdate };
|
|
2820
|
+
export { ALERT_CONFIRMATION_INTERVAL_MS, ASSISTANT_AGENT, CATCH_UP_MARGIN_MS, CSRF_COOKIE, CSRF_HEADER, GOLDEN_QUESTIONS, InMemoryDocumentStore, InProcessEventBus, LOCAL_FS_MEDIA_CAPABILITIES, PROVIDER_REFUND_REASON, READ_MODELS, READ_MODEL_NAMES, REDIS_DEFAULTS, REFRESH_REUSE_WINDOW_MS, REVIEW_VERIFYING_STATUSES, RateLimiter, RebuildError, RouteTable, SECRETS_KEY_ENV, SECRETS_KEY_OLD_ENV, UCP_VERSION, actorOf, agentNameOf, agentReadiness, appendAuditEntry, audit, auditEntriesInOrder, auditedCommand, buildAdapters, buildRepositories, buildServices, checkAdapterModule, confirmationDue, createAlertService, createAlertSubscriptionRepository, createApp, createAuditEntryRepository, createAuthService, createCartCatalogue, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createEmailSuppressionRepository, createEventBuilder, createEventLogRepository, createEventPublisher, createImportRemovalService, createInventoryReservationRepository, createInventoryService, createInvoker, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderAccessKeyRepository, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createOrderShipmentRepository, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createProposalRepository, createProposalService, createRecentlyViewedService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createReviewService, createSearchService, createSettingsRepository, createStockAdjustmentRepository, createUcpSurface, createVariantRepository, currentActor, currentCorrelationId, declaredSettings, decodeProposalCursor, decrypt, diagnose, diffReadModel, emailDelivers, encodeProposalCursor, encodeSearchCursor, encrypt, fillFromSettings, findAppliedByKey, goldenStore, importAdapterModule, installLine, isLoopbackHost, isMissingSettingsTable, isSellable, jsonSchemaOf, keyId, keyProblem, listAuditEntries, migrationState, missingPackage, newAlertToken, newCorrelationId, openReadModels, orderPayment, parseDurationToMs, policyOf, proposalView, rawClients, readSecretsKey, rebuild, recordingAdapter, refreshRefunded, registerAdminStaticRoute, registerAlertHandler, registerAlertRoutes, registerAllRoutes, registerHandlers, resolveAuthSecret, resolveChoice, resolvePrimitives, routeSchemas, runAsActor, runAssistantTurn, runGolden, runMigrations, runSeed, runWithCorrelation, sanitizeDescription, scrub, seedCategories, seedProducts, settingAad, settlementOf, sqliteFile, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, startRefreshTokenSweeper, streamOf, toolName, toolsOf, ucpProfile, withIdempotency };
|
|
2821
|
+
export type { AbandonedCart, AbandonedWindow, Actor, AdapterRegistry, AgentSourceTotals, AgentTotals, AlertConfirmed, AlertService, AlertSubscribeInput, AlertSubscription, AlertSubscriptionPatch, AlertSubscriptionRepository, AlertSubscriptionRequest, AppliedEntry, AssistantDeps, AssistantTurn, AttachHttpOptions, AuditCursor, AuditEntryInsert, AuditEntryRepository, AuditFilter, AuditQuery, AuthSecret, AuthService, AuthTokens, BeginCheckoutInput, BeginCheckoutResult, BuildAdaptersDeps, BuildServicesDeps, CapabilitiesReport, CapabilitySlot, CapturedPayment, CartCatalogue, CartRepository, CartService, CatchUpFailure, CategoryCreateInput, CategoryInsert, CategoryRepository, CategoryService, CategoryUpdate, CategoryUpdateInput, CheckoutService, Choice, CollectionDiff, CommandStore, CommandStoreOptions, CommerceAdapters, CreateAlertServiceDeps, CreateAppOptions, CreateAuthServiceDeps, CreateCartServiceDeps, CreateCheckoutServiceDeps, CreateInventoryServiceDeps, CreateLoggerOptions, CreateOrderServiceDeps, CreatePlatformOptions, CreateProductServiceDeps, CreatePublisherOptions, CreateRefundServiceDeps, CreateRelayOptions, CustomerInsert, CustomerJwtPayload, CustomerNote, CustomerOrderTotals, CustomerRepository, CustomerService, CustomerUpdate, CustomerWithHash, DiagnoseOptions, DiagnosisCheck, DiagnosisReport, DiagnosisStatus, EmailSuppressionInput, EmailSuppressionReason, EmailSuppressionRepository, EncryptedValue, EventArchiveWriter, EventBuilderContext, EventLogFilter, EventLogRepository, EventPublisher, EventRetentionSweeperDeps, Executed, FinalizeResult, GoldenFact, GoldenKind, GoldenQuestion, GoldenReport, GoldenResult, IdempotencyOptions, ImportCustomerInput, ImportRemovalService, ImportRemovalServiceDeps, InMemoryDocumentStoreOptions, InProcessEventBusOptions, InjectedAdapters, InventoryReservationRepository, InventoryService, Invoker, InvokerDeps, KeysetPage, CategoryInsert$1 as LegacyCategoryInsert, CategoryRow as LegacyCategoryRow, ProductInsert$1 as LegacyProductInsert, ProductRow as LegacyProductRow, LocalFsMediaStorageOptions, LoggedEvent, MakeEventOptions, ManualPayments, MigrateOptions, MigrationState, NativeEmailAdapterConfig, NymbalApp, OpenReadModelsOptions, OrderAccessKeyInsert, OrderAccessKeyPurpose, OrderAccessKeyRepository, OrderCapture, OrderCreateDraftInput, OrderHistoryInsert, OrderHistoryRepository, OrderImportInput, OrderInsert, OrderKeyState, OrderRefundInsert, OrderRefundRepository, OrderRepository, OrderSequenceRepository, OrderService, OrderShipmentInput, OrderShipmentRepository, Platform, PlatformConnectionOptions, Policy, PostgresClient, Primitives, ProcessedEventRepository, ProductCategoryRepository, ProductCreateInput, ProductInsert, ProductRepository, ProductService, ProductUpdate, ProductUpdateInput, ProfileUpdate, Proposal, ProposalCursor, ProposalDecision, ProposalInsert, ProposalQuery, ProposalRecord, ProposalRepository, ProposalService, ProposalServiceDeps, ProposalSettlement, PublishOptions, RawClients, ReadModel, ReadModelDiff, ReadModelName, ReadTx, RebuildDeps, RebuildReport, RebuildReportEntry, RecentlyViewedService, RecentlyViewedServiceDeps, RefreshTokenInsert, RefreshTokenRepository, RefreshTokenRow, RefreshTokenSweeperDeps, RefundInput, RefundResult, RefundService, RegisterAlertHandlerDeps, RegisterAlertRoutesDeps, RegisterAllRoutesDeps, RegisterHandlersDeps, RegisterInput, Relay, RemovalOutcome, Repositories, ReservationInsert, ReserveStockResult, Resolution, ResolvePrimitivesOptions, ReviewInsert, ReviewKey, ReviewRepository, ReviewService, ReviewServiceDeps, ReviewSubmitInput, RouteSchema, RunGoldenOptions, SearchService, SecretsKey, SeedCategory, SeedDeps, SeedProduct, SeedResult, ServiceRegistry, SettingRow, SettingSource, SettingValue, SettingsRepository, Settlement, SlotCapabilities, SqliteClient, StockAdjustmentInsert, StockAdjustmentRepository, StoreActivity, StoreRepository, StoredCipher, SweeperHandle, Tx, UcpSurfaceDeps, VariantInsert, VariantPriceInput, VariantRepository, VariantUpdate };
|