@nymbalhq/platform 1.4.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.
Files changed (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +6 -0
  3. package/dist/{chunk-GMV3B3SC.js → chunk-KH3BABMV.js} +10570 -7364
  4. package/dist/chunk-KH3BABMV.js.map +1 -0
  5. package/dist/{chunk-SNNK2OX3.js → chunk-TVKV5GBY.js} +172 -9
  6. package/dist/chunk-TVKV5GBY.js.map +1 -0
  7. package/dist/db/schema/index.d.ts +6537 -3506
  8. package/dist/db/schema/index.js +1 -1
  9. package/dist/index.d.ts +893 -129
  10. package/dist/index.js +4321 -1905
  11. package/dist/index.js.map +1 -1
  12. package/dist/register-XP5XVAXM.js +8 -0
  13. package/migrations/postgres/0016_email_suppressions.sql +7 -0
  14. package/migrations/postgres/0017_order_shipments.sql +14 -0
  15. package/migrations/postgres/0018_order_key_expiry.sql +8 -0
  16. package/migrations/postgres/0019_carts_customer_idx.sql +1 -0
  17. package/migrations/postgres/0020_alert_confirmation_sent.sql +1 -0
  18. package/migrations/postgres/0021_proposals.sql +27 -0
  19. package/migrations/postgres/0022_order_source.sql +3 -0
  20. package/migrations/postgres/meta/0016_snapshot.json +2233 -0
  21. package/migrations/postgres/meta/0017_snapshot.json +2300 -0
  22. package/migrations/postgres/meta/0018_snapshot.json +2306 -0
  23. package/migrations/postgres/meta/0019_snapshot.json +2322 -0
  24. package/migrations/postgres/meta/0020_snapshot.json +2328 -0
  25. package/migrations/postgres/meta/0021_snapshot.json +2543 -0
  26. package/migrations/postgres/meta/0022_snapshot.json +2578 -0
  27. package/migrations/postgres/meta/_journal.json +49 -0
  28. package/migrations/sqlite/0016_email_suppressions.sql +7 -0
  29. package/migrations/sqlite/0017_order_shipments.sql +9 -0
  30. package/migrations/sqlite/0018_order_key_expiry.sql +25 -0
  31. package/migrations/sqlite/0019_carts_customer_idx.sql +1 -0
  32. package/migrations/sqlite/0020_alert_confirmation_sent.sql +1 -0
  33. package/migrations/sqlite/0021_proposals.sql +27 -0
  34. package/migrations/sqlite/0022_order_source.sql +3 -0
  35. package/migrations/sqlite/meta/0016_snapshot.json +1981 -0
  36. package/migrations/sqlite/meta/0017_snapshot.json +2041 -0
  37. package/migrations/sqlite/meta/0018_snapshot.json +2048 -0
  38. package/migrations/sqlite/meta/0019_snapshot.json +2056 -0
  39. package/migrations/sqlite/meta/0020_snapshot.json +2063 -0
  40. package/migrations/sqlite/meta/0021_snapshot.json +2246 -0
  41. package/migrations/sqlite/meta/0022_snapshot.json +2270 -0
  42. package/migrations/sqlite/meta/_journal.json +49 -0
  43. package/package.json +25 -52
  44. package/dist/chunk-GMV3B3SC.js.map +0 -1
  45. package/dist/chunk-SNNK2OX3.js.map +0 -1
  46. package/dist/register-N2XGSFUF.js +0 -8
  47. /package/dist/{register-N2XGSFUF.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
- import { Logger, DocumentStoreAdapter, EventBusAdapter, MediaStorage, Product, ProductStatus, ProductType, ProductMedia, Variant, VariantDimensions, VariantOption, VariantStatus, Category, Customer, Role, CustomerAddress, Order, OrderStatus, Address, OrderLineItem, CaptureMethod, OrderHistoryEntry, OrderRefundStatus, OrderRefund, InventoryReservation, StockAdjustmentReason, StockAdjustment, Review, ReviewModerationStatus, NymbalEvent, Cart, AuditSubject, AuditActor, AuditOutcome, AuditEntry, AlertKind, AlertStatus, HealthReport, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, RequestAuth, AdapterSetting, CommerceSlotAdapters, SecurityAdapter, AiAdapter, PaymentsAdapter, EmailAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, SearchAdapter, OrderPayment, Refund, RecentViewer, CommerceSlot, HttpAdapter, Slot, ProviderPackageModule, RateLimitAction, ReviewsAdapter, AnalyticsAdapter, ShippingAdapter, TaxAdapter, HealthStatus } from '@nymbalhq/types';
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';
@@ -104,7 +105,9 @@ declare const REDIS_DEFAULTS: {
104
105
  };
105
106
  /**
106
107
  * The document store, event bus and media storage the config names. A primitive that lives in its own package is
107
- * imported only when named; a missing package fails `adapter.package_missing` with the install line.
108
+ * imported only when named, from its block's `package` or `@nymbalhq/<slot>-<provider>`; a missing package fails
109
+ * `adapter.package_missing` with the install line. A provider whose connection the kernel does not build gets its
110
+ * block's `config`.
108
111
  */
109
112
  declare function resolvePrimitives(config: NymbalConfig, options?: ResolvePrimitivesOptions): Promise<Primitives>;
110
113
  declare function createPlatform(config: NymbalConfig, options: CreatePlatformOptions): Platform;
@@ -113,6 +116,17 @@ interface MigrateOptions {
113
116
  migrationsRoot?: string;
114
117
  }
115
118
  declare function runMigrations(store: CommandStore, options?: MigrateOptions): Promise<void>;
119
+ interface MigrationState {
120
+ /** Rows in the store's migrations table. */
121
+ applied: number;
122
+ /** Journal entries `runMigrations` would apply. */
123
+ pending: number;
124
+ }
125
+ /**
126
+ * What `runMigrations` would do to `store`, read without writing. Drizzle applies every journal entry created after the
127
+ * newest one its table records, so that is what counts as pending; a store with no table has every entry pending.
128
+ */
129
+ declare function migrationState(store: CommandStore, options?: MigrateOptions): Promise<MigrationState>;
116
130
 
117
131
  interface ProductInsert$1 {
118
132
  id: string;
@@ -254,6 +268,9 @@ interface VariantRepository extends StoreRepository {
254
268
  findById(tx: ReadTx, id: string): Promise<Variant | null>;
255
269
  findBySku(tx: ReadTx, sku: string): Promise<Variant | null>;
256
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[]>;
257
274
  insert(tx: Tx, v: VariantInsert): Promise<void>;
258
275
  update(tx: Tx, id: string, patch: VariantUpdate): Promise<void>;
259
276
  /** One conditional UPDATE: the new stock, or null when the variant is missing or holds fewer than `qty`. */
@@ -365,13 +382,46 @@ interface RefreshTokenRow {
365
382
  interface RefreshTokenRepository extends StoreRepository {
366
383
  insert(tx: Tx, t: RefreshTokenInsert): Promise<void>;
367
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
+ */
368
389
  rotate(tx: Tx, oldJti: string, next: RefreshTokenInsert): Promise<void>;
369
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. */
370
392
  revokeAllForCustomer(tx: Tx, customerId: string): Promise<void>;
371
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>;
372
400
  }
373
401
  declare function createRefreshTokenRepository(store: CommandStore): RefreshTokenRepository;
374
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
+ }
375
425
  interface OrderInsert {
376
426
  id: string;
377
427
  orderNumber: string;
@@ -397,6 +447,8 @@ interface OrderInsert {
397
447
  capture?: OrderCapture & {
398
448
  refundedMinor: number;
399
449
  };
450
+ /** Who brought the order; `storefront` when not given. */
451
+ source?: OrderSource;
400
452
  createdAt: Date;
401
453
  updatedAt: Date;
402
454
  }
@@ -417,6 +469,15 @@ interface OrderRepository extends StoreRepository {
417
469
  /** The newest order the cart became: neither pending nor cancelled. */
418
470
  findLastConvertedByCartToken(tx: ReadTx, cartToken: string): Promise<Order | null>;
419
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>;
420
481
  list(tx: ReadTx, opts?: {
421
482
  status?: OrderStatus;
422
483
  limit?: number;
@@ -433,6 +494,10 @@ interface OrderRepository extends StoreRepository {
433
494
  recordCapture(tx: Tx, id: string, capture: OrderCapture): Promise<void>;
434
495
  setRefunded(tx: Tx, id: string, refundedMinor: number, updatedAt: Date): Promise<void>;
435
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[]>;
436
501
  }
437
502
  declare function createOrderRepository(store: CommandStore): OrderRepository;
438
503
 
@@ -448,6 +513,9 @@ interface OrderHistoryInsert {
448
513
  interface OrderHistoryRepository extends StoreRepository {
449
514
  append(tx: Tx, entry: OrderHistoryInsert): Promise<void>;
450
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[]>;
451
519
  }
452
520
  declare function createOrderHistoryRepository(store: CommandStore): OrderHistoryRepository;
453
521
 
@@ -477,6 +545,9 @@ interface OrderRefundRepository extends StoreRepository {
477
545
  listByOrder(tx: ReadTx, orderId: string): Promise<OrderRefund[]>;
478
546
  /** The refunds of each order, oldest first; an order without refunds is absent. */
479
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[]>;
480
551
  }
481
552
  declare function createOrderRefundRepository(store: CommandStore): OrderRefundRepository;
482
553
 
@@ -487,6 +558,8 @@ declare function createOrderSequenceRepository(store: CommandStore): OrderSequen
487
558
 
488
559
  /** Who minted the key: a checkout answer, or the order-placed email. */
489
560
  type OrderAccessKeyPurpose = 'checkout' | 'email';
561
+ /** What a key does for an order: opens it, has expired, or is not one of its keys. */
562
+ type OrderKeyState = 'open' | 'expired' | 'none';
490
563
  interface OrderAccessKeyInsert {
491
564
  id: string;
492
565
  orderId: string;
@@ -494,11 +567,17 @@ interface OrderAccessKeyInsert {
494
567
  keyHash: string;
495
568
  purpose: OrderAccessKeyPurpose;
496
569
  createdAt: Date;
570
+ expiresAt: Date;
497
571
  }
498
572
  interface OrderAccessKeyRepository extends StoreRepository {
499
573
  insert(tx: Tx, k: OrderAccessKeyInsert): Promise<void>;
500
- /** Whether a key with this hash opens this order: another order's key opens nothing here. */
501
- opens(tx: ReadTx, orderId: string, keyHash: string): Promise<boolean>;
574
+ /** What a key with this hash does for this order at `now`: another order's key is `none` here. */
575
+ opens(tx: ReadTx, orderId: string, keyHash: string, now: Date): Promise<OrderKeyState>;
576
+ /** Deletes the order's oldest keys of `purpose`, by `(created_at, id)`, until at most `keep` remain. */
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[]>;
502
581
  }
503
582
  declare function createOrderAccessKeyRepository(store: CommandStore): OrderAccessKeyRepository;
504
583
 
@@ -557,10 +636,20 @@ interface ReviewKey {
557
636
  }
558
637
  interface ReviewRepository extends StoreRepository {
559
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>;
560
646
  /** Newest first, ties by id descending; `after` is the last review of the previous page. */
561
647
  listByProduct(tx: ReadTx, productId: string, status?: ReviewModerationStatus, limit?: number, after?: ReviewKey): Promise<Review[]>;
562
648
  listByStatus(tx: ReadTx, status: ReviewModerationStatus, limit?: number): Promise<Review[]>;
563
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[]>;
564
653
  setModerationStatus(tx: Tx, id: string, status: ReviewModerationStatus, moderatedBy: string, moderatedAt: Date): Promise<void>;
565
654
  aggregateByProduct(tx: ReadTx, productId: string): Promise<{
566
655
  average: number;
@@ -623,12 +712,17 @@ interface EventLogRepository extends StoreRepository {
623
712
  * given, is the earliest the next attempt may be made.
624
713
  */
625
714
  recordFailure(tx: Tx, id: string, at: Date, maxAttempts: number, retryAt?: Date): Promise<void>;
715
+ /** A delivery that failed during an adapter outage: only the earliest next attempt moves, nothing is counted. */
716
+ recordOutage(tx: Tx, id: string, retryAt: Date): Promise<void>;
626
717
  countDead(tx: ReadTx): Promise<number>;
627
718
  /** Dead events, oldest first. */
628
719
  listDead(tx: ReadTx, limit: number): Promise<LoggedEvent[]>;
629
720
  /** Neither delivered nor dead, with at least one failed attempt. */
630
721
  countRetrying(tx: ReadTx): Promise<number>;
631
- /** Deletes delivered events delivered before `at`; returns how many. Undelivered and dead events are never deleted. */
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
+ */
632
726
  deleteDeliveredBefore(tx: Tx, at: Date): Promise<number>;
633
727
  listAll(tx: ReadTx): Promise<LoggedEvent[]>;
634
728
  /** One correlation id's events, by `seq`. */
@@ -677,6 +771,8 @@ interface CartRepository extends StoreRepository {
677
771
  /** `findByToken`, holding the row for the rest of the transaction so concurrent commands on the cart queue behind
678
772
  * this one (Postgres `FOR UPDATE`; SQLite's `BEGIN IMMEDIATE` already holds the database). */
679
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>;
680
776
  /** Inserts the cart, or replaces an expired row on its token. A live row on the token is left as it is and
681
777
  * returned with `created: false`. */
682
778
  create(tx: Tx, cart: Cart): Promise<{
@@ -804,6 +900,8 @@ interface AlertSubscription {
804
900
  createdAt: Date;
805
901
  updatedAt: Date;
806
902
  confirmedAt: Date | null;
903
+ /** When its last confirmation was sent; null on a new or reissued row. */
904
+ confirmationSentAt: Date | null;
807
905
  }
808
906
  /** A subscribe request: a new row's values, of which a row already there takes only what its status allows. */
809
907
  interface AlertSubscriptionRequest {
@@ -830,9 +928,11 @@ interface AlertSubscriptionRepository extends StoreRepository {
830
928
  /**
831
929
  * One write on the unique (email, variant, kind): a new row is `pending`; a `pending` row takes the request's origin;
832
930
  * an `unsubscribed` or `fired` row returns to `pending` with the request's origin, confirm token and baseline (its
833
- * unsubscribe token is kept); an `active` row only has `updated_at` touched. Answers the row after the write.
931
+ * unsubscribe token is kept) and no confirmation sent; an `active` row only has `updated_at` touched. Answers the
932
+ * row after the write.
834
933
  */
835
934
  upsertPending(tx: Tx, request: AlertSubscriptionRequest): Promise<AlertSubscription>;
935
+ markConfirmationSent(tx: Tx, id: string, at: Date): Promise<void>;
836
936
  findById(tx: ReadTx, id: string): Promise<AlertSubscription | null>;
837
937
  findByConfirmToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
838
938
  findByUnsubscribeToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
@@ -842,6 +942,111 @@ interface AlertSubscriptionRepository extends StoreRepository {
842
942
  }
843
943
  declare function createAlertSubscriptionRepository(store: CommandStore): AlertSubscriptionRepository;
844
944
 
945
+ type EmailSuppressionReason = 'hard_bounce' | 'complaint';
946
+ interface EmailSuppressionInput {
947
+ email: string;
948
+ reason: EmailSuppressionReason;
949
+ /** The feedback event that suppresses the address. */
950
+ eventId: string;
951
+ at: Date;
952
+ }
953
+ /** Addresses that hard-bounced or complained. Each method normalises the address it is given. */
954
+ interface EmailSuppressionRepository extends StoreRepository {
955
+ /** True when this call suppressed the address; false when it already was, whose first reason stays. */
956
+ suppress(tx: Tx, input: EmailSuppressionInput): Promise<boolean>;
957
+ isSuppressed(tx: ReadTx, email: string): Promise<boolean>;
958
+ }
959
+ declare function createEmailSuppressionRepository(store: CommandStore): EmailSuppressionRepository;
960
+
961
+ interface OrderShipmentInput {
962
+ orderId: string;
963
+ carrier: string;
964
+ trackingNumber: string;
965
+ at: Date;
966
+ }
967
+ /** The parcel each shipped order went out in. Each method normalises the tracking number it is given. */
968
+ interface OrderShipmentRepository extends StoreRepository {
969
+ record(tx: Tx, input: OrderShipmentInput): Promise<void>;
970
+ /** The ids of every order shipped under the number, in no particular order. */
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[]>;
975
+ }
976
+ declare function createOrderShipmentRepository(store: CommandStore): OrderShipmentRepository;
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
+
845
1050
  interface Repositories {
846
1051
  product: ProductRepository;
847
1052
  variant: VariantRepository;
@@ -863,6 +1068,9 @@ interface Repositories {
863
1068
  settings: SettingsRepository;
864
1069
  auditEntry: AuditEntryRepository;
865
1070
  alertSubscription: AlertSubscriptionRepository;
1071
+ emailSuppression: EmailSuppressionRepository;
1072
+ orderShipment: OrderShipmentRepository;
1073
+ proposal: ProposalRepository;
866
1074
  }
867
1075
  declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
868
1076
 
@@ -917,6 +1125,15 @@ interface MakeEventOptions {
917
1125
  }
918
1126
  declare function createEventBuilder(ctx: EventBuilderContext): <T>(type: string, payload: T, options?: MakeEventOptions) => NymbalEvent<T>;
919
1127
 
1128
+ interface OutageReport {
1129
+ /** True when any checked subject is down, threw or did not answer in time. */
1130
+ outage: boolean;
1131
+ down: readonly {
1132
+ name: string;
1133
+ detail: string;
1134
+ }[];
1135
+ }
1136
+
920
1137
  /** Hands committed events from the log to the bus. */
921
1138
  interface Relay {
922
1139
  /** Delivers every undelivered, non-dead event in `seq` order. Never rejects. */
@@ -945,6 +1162,13 @@ interface CreateRelayOptions {
945
1162
  retryDelayMs?: number;
946
1163
  /** The clock failures and retry waits are read from. */
947
1164
  now?: () => Date;
1165
+ /**
1166
+ * Asked once a pass, at its first failed delivery: a failure during an outage is not counted toward `maxAttempts`.
1167
+ * Absent, no failure is an outage.
1168
+ */
1169
+ outage?: () => Promise<OutageReport>;
1170
+ /** How long the relay waits on `outage` before taking the pass as an outage (default the health check bound + 1 s). */
1171
+ outageTimeoutMs?: number;
948
1172
  }
949
1173
  declare function createRelay(opts: CreateRelayOptions): Relay;
950
1174
 
@@ -1050,6 +1274,10 @@ interface BuildAdaptersDeps {
1050
1274
  }
1051
1275
  declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
1052
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;
1053
1281
  interface AlertSubscribeInput {
1054
1282
  email: string;
1055
1283
  variantId: string;
@@ -1068,7 +1296,8 @@ interface AlertConfirmed {
1068
1296
  interface AlertService {
1069
1297
  /**
1070
1298
  * Answers `pending` whatever the address's account or subscription, so the answer reveals neither; every accepted
1071
- * request writes the row once. Only a row that is not `active` is (re)sent its confirmation.
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.
1072
1301
  */
1073
1302
  subscribe(input: AlertSubscribeInput): Promise<{
1074
1303
  status: 'pending';
@@ -1079,9 +1308,12 @@ interface AlertService {
1079
1308
  }>;
1080
1309
  /**
1081
1310
  * In the transaction that marks an alert's send: a back-in-stock row is `fired`, a price-drop row stays `active` with
1082
- * 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.
1083
1313
  */
1084
- recordSent(tx: Tx, subscription: AlertSubscription, trigger: NymbalEvent<unknown>): Promise<void>;
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>;
1085
1317
  }
1086
1318
  interface CreateAlertServiceDeps {
1087
1319
  store: CommandStore;
@@ -1094,6 +1326,73 @@ interface CreateAlertServiceDeps {
1094
1326
  }
1095
1327
  declare function createAlertService(deps: CreateAlertServiceDeps): AlertService;
1096
1328
 
1329
+ interface OrderCreateDraftInput {
1330
+ orderId: string;
1331
+ customerId: string | null;
1332
+ email: string;
1333
+ billingAddress: Address;
1334
+ shippingAddress: Address;
1335
+ lineItems: OrderLineItem[];
1336
+ subtotalMinor: number;
1337
+ taxTotalMinor: number;
1338
+ shippingTotalMinor: number;
1339
+ discountTotalMinor: number;
1340
+ totalMinor: number;
1341
+ currency: string;
1342
+ notes?: string;
1343
+ metadata?: Record<string, unknown>;
1344
+ paymentIntentId?: string | null;
1345
+ cartToken?: string | null;
1346
+ /** The source of the cart the order is placed from; `storefront` when not given. */
1347
+ source?: CartSource;
1348
+ }
1349
+ /** An imported order's source is always `import`. */
1350
+ interface OrderImportInput extends Omit<OrderCreateDraftInput, 'source'> {
1351
+ orderNumber: string;
1352
+ status: OrderStatus;
1353
+ createdAt: Date;
1354
+ /** What the imported order was paid, taken as captured when it was placed; nothing when absent. */
1355
+ capturedMinor?: number;
1356
+ refundedMinor?: number;
1357
+ captureMethod?: CaptureMethod | null;
1358
+ }
1359
+ interface OrderService {
1360
+ createFromCheckout(input: OrderCreateDraftInput): Promise<Order>;
1361
+ importOrder(input: OrderImportInput): Promise<Order>;
1362
+ getById(id: string): Promise<Order>;
1363
+ getByOrderNumber(orderNumber: string): Promise<Order>;
1364
+ listByCustomer(customerId: string): Promise<Order[]>;
1365
+ /** Whether `key` opens the order now: one of its own keys, well formed and unexpired. */
1366
+ keyOpens(orderId: string, key: string): Promise<boolean>;
1367
+ /** What `key` does for the order at `now`: another order's key, or a malformed one, is `none`. */
1368
+ keyState(orderId: string, key: string, now?: Date): Promise<OrderKeyState>;
1369
+ /**
1370
+ * "Send me my order link": when the number and email name an order a confirmation is due for (confirmed or later),
1371
+ * its order-placed email is sent again, with a fresh link for a guest's order. Anything else does nothing, and the
1372
+ * caller is told nothing either way.
1373
+ */
1374
+ requestLink(orderNumber: string, email: string): Promise<void>;
1375
+ updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
1376
+ markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
1377
+ markDelivered(id: string, actor: string): Promise<Order>;
1378
+ /** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
1379
+ cancel(id: string, reason: string, actor: string): Promise<Order>;
1380
+ /**
1381
+ * Asks for the order's confirmation email again; the email handler sends it. Refuses with `order.unpaid` for an
1382
+ * order no confirmation is due for (pending, or cancelled and so never paid). Changes nothing on the order.
1383
+ */
1384
+ resendConfirmation(id: string): Promise<Order>;
1385
+ }
1386
+ interface CreateOrderServiceDeps {
1387
+ store: CommandStore;
1388
+ repos: Repositories;
1389
+ publisher: EventPublisher;
1390
+ logger: Logger;
1391
+ orderNumberPrefix: string;
1392
+ orderNumberStart: number;
1393
+ }
1394
+ declare function createOrderService(deps: CreateOrderServiceDeps): OrderService;
1395
+
1097
1396
  interface RegisterHandlersDeps {
1098
1397
  config: NymbalConfig;
1099
1398
  eventBus: EventBusAdapter;
@@ -1102,6 +1401,8 @@ interface RegisterHandlersDeps {
1102
1401
  adapters: AdapterRegistry;
1103
1402
  /** Records each alert's send: the row fired and `alert.sent.v1` published. */
1104
1403
  alerts: AlertService;
1404
+ /** Moves an order a tracking update reports delivered. */
1405
+ orders: OrderService;
1105
1406
  logger: Logger;
1106
1407
  }
1107
1408
  declare function registerHandlers(deps: RegisterHandlersDeps): Promise<void>;
@@ -1110,7 +1411,7 @@ interface RegisterAlertHandlerDeps {
1110
1411
  eventBus: EventBusAdapter;
1111
1412
  email: EmailAdapter;
1112
1413
  logger: Logger;
1113
- repos: Pick<Repositories, 'alertSubscription' | 'processedEvent' | 'product'>;
1414
+ repos: Pick<Repositories, 'alertSubscription' | 'emailSuppression' | 'processedEvent' | 'product'>;
1114
1415
  alerts: AlertService;
1115
1416
  storeName: string;
1116
1417
  }
@@ -1195,7 +1496,8 @@ declare function createCategoryService(deps: {
1195
1496
  }): CategoryService;
1196
1497
 
1197
1498
  interface CartService {
1198
- getOrCreate(token?: string, customerId?: string | null): Promise<Cart>;
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>;
1199
1501
  get(token: string): Promise<Cart | null>;
1200
1502
  addItem(token: string, item: Omit<CartItem, 'qty'> & {
1201
1503
  qty?: number;
@@ -1205,13 +1507,29 @@ interface CartService {
1205
1507
  clear(token: string): Promise<Cart>;
1206
1508
  merge(guestToken: string, customerToken: string): Promise<Cart>;
1207
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>>;
1208
1518
  }
1519
+ declare function createCartCatalogue(repos: {
1520
+ variant: VariantRepository;
1521
+ product: ProductRepository;
1522
+ }): CartCatalogue;
1209
1523
  interface CreateCartServiceDeps {
1210
1524
  store: CommandStore;
1211
1525
  carts: CartRepository;
1212
1526
  publisher: EventPublisher;
1213
1527
  logger: Logger;
1214
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'>;
1215
1533
  ttlSeconds?: number;
1216
1534
  now?: () => Date;
1217
1535
  }
@@ -1222,12 +1540,20 @@ interface ProfileUpdate {
1222
1540
  lastName?: string;
1223
1541
  phone?: string;
1224
1542
  }
1543
+ /** An admin's note on a customer, kept in its metadata. */
1544
+ interface CustomerNote {
1545
+ body: string;
1546
+ actor: string;
1547
+ at: string;
1548
+ }
1225
1549
  interface CustomerService {
1226
1550
  getProfile(customerId: string): Promise<Customer>;
1227
1551
  updateProfile(customerId: string, patch: ProfileUpdate): Promise<Customer>;
1228
1552
  listAddresses(customerId: string): Promise<CustomerAddress[]>;
1229
1553
  addAddress(customerId: string, addr: Omit<CustomerAddress, 'id'>): Promise<CustomerAddress>;
1230
1554
  deleteAddress(customerId: string, addressId: string): Promise<void>;
1555
+ /** Appends `note` to the customer's admin notes. */
1556
+ addNote(customerId: string, note: CustomerNote): Promise<void>;
1231
1557
  }
1232
1558
  declare function createCustomerService(deps: {
1233
1559
  repos: Repositories;
@@ -1286,64 +1612,13 @@ interface CreateAuthServiceDeps {
1286
1612
  issuer?: string;
1287
1613
  }
1288
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;
1289
1620
  declare function createAuthService(deps: CreateAuthServiceDeps): AuthService;
1290
1621
 
1291
- interface OrderCreateDraftInput {
1292
- orderId: string;
1293
- customerId: string | null;
1294
- email: string;
1295
- billingAddress: Address;
1296
- shippingAddress: Address;
1297
- lineItems: OrderLineItem[];
1298
- subtotalMinor: number;
1299
- taxTotalMinor: number;
1300
- shippingTotalMinor: number;
1301
- discountTotalMinor: number;
1302
- totalMinor: number;
1303
- currency: string;
1304
- notes?: string;
1305
- metadata?: Record<string, unknown>;
1306
- paymentIntentId?: string | null;
1307
- cartToken?: string | null;
1308
- }
1309
- interface OrderImportInput extends OrderCreateDraftInput {
1310
- orderNumber: string;
1311
- status: OrderStatus;
1312
- createdAt: Date;
1313
- /** What the imported order was paid, taken as captured when it was placed; nothing when absent. */
1314
- capturedMinor?: number;
1315
- refundedMinor?: number;
1316
- captureMethod?: CaptureMethod | null;
1317
- }
1318
- interface OrderService {
1319
- createFromCheckout(input: OrderCreateDraftInput): Promise<Order>;
1320
- importOrder(input: OrderImportInput): Promise<Order>;
1321
- getById(id: string): Promise<Order>;
1322
- getByOrderNumber(orderNumber: string): Promise<Order>;
1323
- listByCustomer(customerId: string): Promise<Order[]>;
1324
- /** Whether `key` opens the order: one of its own keys, well formed. Another order's key opens nothing. */
1325
- keyOpens(orderId: string, key: string): Promise<boolean>;
1326
- updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
1327
- markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
1328
- markDelivered(id: string, actor: string): Promise<Order>;
1329
- /** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
1330
- cancel(id: string, reason: string, actor: string): Promise<Order>;
1331
- /**
1332
- * Asks for the order's confirmation email again; the email handler sends it. Refuses with `order.unpaid` for an
1333
- * order no confirmation is due for (pending, or cancelled and so never paid). Changes nothing on the order.
1334
- */
1335
- resendConfirmation(id: string): Promise<Order>;
1336
- }
1337
- interface CreateOrderServiceDeps {
1338
- store: CommandStore;
1339
- repos: Repositories;
1340
- publisher: EventPublisher;
1341
- logger: Logger;
1342
- orderNumberPrefix: string;
1343
- orderNumberStart: number;
1344
- }
1345
- declare function createOrderService(deps: CreateOrderServiceDeps): OrderService;
1346
-
1347
1622
  interface ReserveStockResult {
1348
1623
  reservationId: string;
1349
1624
  expiresAt: string;
@@ -1379,6 +1654,13 @@ interface BeginCheckoutInput {
1379
1654
  billingAddress: Address;
1380
1655
  shippingAddress: Address;
1381
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
+ };
1382
1664
  }
1383
1665
  interface BeginCheckoutResult {
1384
1666
  orderId: string;
@@ -1389,8 +1671,11 @@ interface BeginCheckoutResult {
1389
1671
  /** The order's status as the checkout answers. */
1390
1672
  orderStatus: OrderStatus;
1391
1673
  payment: CheckoutPayment;
1392
- /** A fresh key that reads the order with no session (`ORDER_KEY_HEADER`). Only its hash is stored. */
1393
- orderKey: string;
1674
+ /**
1675
+ * A guest order's fresh key, which reads it with no session (`ORDER_KEY_HEADER`) until it expires. Only its hash is
1676
+ * stored. A signed-in customer's order has none: their account is its home.
1677
+ */
1678
+ orderKey?: string;
1394
1679
  }
1395
1680
  /** What the payment provider captured. */
1396
1681
  interface CapturedPayment {
@@ -1413,7 +1698,11 @@ interface CheckoutService {
1413
1698
  * there is an order, a history note) and leaves the order as it was. Joins the caller's transaction.
1414
1699
  */
1415
1700
  finalize(paymentIntentId: string, paid: CapturedPayment): Promise<FinalizeResult>;
1416
- cancel(orderId: string, reason: string): Promise<void>;
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>;
1417
1706
  }
1418
1707
  /** The admin's side of a checkout: a payment taken outside the store. */
1419
1708
  interface ManualPayments {
@@ -1434,6 +1723,8 @@ interface CreateCheckoutServiceDeps {
1434
1723
  inventory: InventoryService;
1435
1724
  payments: PaymentsAdapter;
1436
1725
  currency: string;
1726
+ /** How long a checkout's order key opens the order on its own; 48 hours when not given. */
1727
+ keyLifetimeMs?: number;
1437
1728
  }
1438
1729
  declare function createCheckoutService(deps: CreateCheckoutServiceDeps): CheckoutService & ManualPayments;
1439
1730
 
@@ -1486,7 +1777,10 @@ interface Settlement {
1486
1777
  }
1487
1778
  /** The provider's answer settles a refund row as succeeded only when it is for the row's amount and currency. */
1488
1779
  declare function settlementOf(answer: Refund, row: Pick<OrderRefund, 'amountMinor' | 'currency'>): Settlement;
1489
- /** Writes `refunded_minor` as Σ of the order's succeeded refunds. */
1780
+ /**
1781
+ * Writes `refunded_minor` as Σ of the order's succeeded refunds, when that moves it: a refund that moved no money (failed
1782
+ * or still pending) leaves the order row as it was, so it needs no order event. The caller holds the order's lock.
1783
+ */
1490
1784
  declare function refreshRefunded(repos: Repositories, tx: Tx, orderId: string, at: Date): Promise<{
1491
1785
  refunds: OrderRefund[];
1492
1786
  refundedMinor: number;
@@ -1509,9 +1803,129 @@ interface RecentlyViewedService {
1509
1803
  }
1510
1804
  declare function createRecentlyViewedService(deps: RecentlyViewedServiceDeps): RecentlyViewedService;
1511
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
+
1512
1919
  /** A confirm or unsubscribe link's bearer credential: 32 random bytes, base64url (43 characters). */
1513
1920
  declare function newAlertToken(): string;
1514
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
+
1515
1929
  /** A `native` email adapter only logs; any other (`smtp`, a project's own) is taken to reach a mailbox. */
1516
1930
  declare function emailDelivers(email: EmailAdapter): boolean;
1517
1931
  interface ServiceRegistry {
@@ -1527,6 +1941,9 @@ interface ServiceRegistry {
1527
1941
  search: SearchService;
1528
1942
  recentlyViewed: RecentlyViewedService;
1529
1943
  alert: AlertService;
1944
+ review: ReviewService;
1945
+ proposals: ProposalService;
1946
+ importRemoval: ImportRemovalService;
1530
1947
  }
1531
1948
  interface BuildServicesDeps {
1532
1949
  config: NymbalConfig;
@@ -1537,6 +1954,11 @@ interface BuildServicesDeps {
1537
1954
  payments: PaymentsAdapter;
1538
1955
  searchAdapter: SearchAdapter;
1539
1956
  email: EmailAdapter;
1957
+ reviews: ReviewsAdapter;
1958
+ /** The effective JWT secret (`resolveAuthSecret`), not the config's field. */
1959
+ jwtSecret: string;
1960
+ /** Runs a stored proposal through its route: the tool surface `attachHttp` builds. */
1961
+ executeProposal: ProposalServiceDeps['execute'];
1540
1962
  }
1541
1963
  declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
1542
1964
 
@@ -1546,7 +1968,10 @@ interface DeclaredSlot {
1546
1968
  provider: string;
1547
1969
  declared: readonly AdapterSetting[];
1548
1970
  }
1549
- /** A store from before migration 0008 has no `settings` relation: it holds no settings. */
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
+ */
1550
1975
  declare function isMissingSettingsTable(error: unknown): boolean;
1551
1976
 
1552
1977
  interface RegisterAllRoutesDeps {
@@ -1560,8 +1985,12 @@ interface RegisterAllRoutesDeps {
1560
1985
  publisher: EventPublisher;
1561
1986
  /** The slots whose provider packages declare settings, as the store booted with them. */
1562
1987
  settingsSlots: readonly DeclaredSlot[];
1988
+ /** The effective JWT secret (`resolveAuthSecret`), which signs the event-stream ticket as it signs tokens. */
1989
+ jwtSecret: string;
1563
1990
  /** The admin's dist directory, or null for a 404 that says how to build it; undefined serves no admin. */
1564
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;
1565
1994
  }
1566
1995
  declare function registerAllRoutes(deps: RegisterAllRoutesDeps): void;
1567
1996
 
@@ -1591,9 +2020,133 @@ interface RouteSchema {
1591
2020
  * the service commits its own steps around the provider call, so what it holds is committed before money moves.
1592
2021
  */
1593
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[];
1594
2038
  }
2039
+ /** A customer field a route's answer can carry. */
2040
+ type PersonalField = 'email' | 'phone' | 'address';
1595
2041
  declare const routeSchemas: Record<string, RouteSchema>;
1596
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
+
1597
2150
  interface NymbalApp {
1598
2151
  platform: Platform;
1599
2152
  repos: Repositories;
@@ -1602,11 +2155,22 @@ interface NymbalApp {
1602
2155
  publisher: EventPublisher;
1603
2156
  /** Delivers the event log to the bus; started by createApp, stopped by stop(). */
1604
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;
1605
2163
  /**
1606
2164
  * Registers the API on the adapter. The admin is served at /admin/ when `adminRoot` is passed (its dist directory,
1607
2165
  * or null for a 404 that says how to build it) or `NYMBAL_ADMIN_DIST` is set.
1608
2166
  */
1609
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;
1610
2174
  /** Each slot's provider and its adapter's own `capabilities()`; an ai slot of `none` offers nothing. */
1611
2175
  capabilities(): CapabilitiesReport;
1612
2176
  stop(): Promise<void>;
@@ -1626,9 +2190,203 @@ interface CreateAppOptions extends ResolvePrimitivesOptions {
1626
2190
  adapters?: InjectedAdapters;
1627
2191
  /** How the event relay retries a failed delivery (`createRelay`). */
1628
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
+ };
1629
2197
  }
1630
2198
  declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
1631
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
+
2373
+ interface AuthSecret {
2374
+ secret: string;
2375
+ source: 'config' | 'env' | 'default';
2376
+ }
2377
+ /**
2378
+ * The secret every token is signed with: the config's own, else NYMBAL_JWT_SECRET, else the schema default. Code that
2379
+ * names a secret wins, as it does over the environment for adapter settings. A set variable is checked first, so a
2380
+ * malformed one fails the boot even when the config's secret would win.
2381
+ */
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;
2389
+
1632
2390
  /**
1633
2391
  * Serves the admin's built files at /admin/ beside /api, one origin, so its relative API URLs and the refresh cookie
1634
2392
  * work without a proxy. `root` is the admin's dist directory, or null when none is installed: then /admin/ answers 404
@@ -1687,38 +2445,69 @@ interface EventRetentionSweeperDeps {
1687
2445
  */
1688
2446
  declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
1689
2447
 
1690
- interface ProviderPackage {
1691
- /** The adapter package, which exports `createAdapter(ctx: AdapterContext)`. */
1692
- package: string;
1693
- /** The provider SDK the package peers, which the project installs beside it; none when it talks HTTP itself. */
1694
- sdk?: string;
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
+
2460
+ /** What the config names for a slot: its provider, and the package the adapter comes from when it says. */
2461
+ interface Choice {
2462
+ provider: string;
2463
+ package?: string | undefined;
1695
2464
  }
1696
- type Packages<P extends ProviderPackage> = Readonly<Record<string, P>>;
1697
2465
  /**
1698
- * The providers that live in their own package, by slot then provider. The kernel imports a package only when the
1699
- * config names its provider; `native`, `none`, `custom` and the kernel's own primitives (`in-memory`, `in-process`,
1700
- * `local-fs`) have no entry. Every package peers its provider's SDK but the security ones, which call an HTTP API.
2466
+ * Where a slot's adapter comes from: the one passed to `createApp` (`custom`), the kernel's own (`built-in`), or a
2467
+ * package, named by the config's `package` or by the convention, `@nymbalhq/<slot>-<provider>`.
1701
2468
  */
1702
- declare const PROVIDER_PACKAGES: Readonly<Partial<Record<Exclude<Slot, 'security'>, Packages<Required<ProviderPackage>>>>> & {
1703
- readonly security: Packages<ProviderPackage>;
2469
+ type Resolution = {
2470
+ kind: 'custom';
2471
+ } | {
2472
+ kind: 'built-in';
2473
+ } | {
2474
+ kind: 'package';
2475
+ package: string;
2476
+ sdk?: string;
2477
+ named: 'package' | 'convention';
1704
2478
  };
2479
+ /** The rule every caller shares: `custom`, then a built-in, then `package`, then the convention name. */
2480
+ declare function resolveChoice(slot: Slot, choice: Choice): Resolution;
1705
2481
  /** The command that installs `packages` with the project's package manager, as `packageManager` picks it. */
1706
2482
  declare function installLine(packages: readonly string[], env: NodeJS.ProcessEnv, cwd: string): string;
1707
- type ProviderModule = ProviderPackageModule;
1708
2483
  /**
1709
- * The module of a provider that lives in its own package, imported from the kernel as `loadProviderAdapter` imports
1710
- * it, or `undefined` when the provider is built in. A missing package or SDK is a `ConfigError`
1711
- * (`adapter.package_missing`) carrying the install line, a module with no `createAdapter` is `adapter.package_invalid`,
1712
- * and any other load error is rethrown as it is.
2484
+ * The package Node could not find, when `error` is a missing package and not some other failure. A path (an installed
2485
+ * package's own missing file) is not a package to install, so it is `null` and the error stays as Node threw it.
2486
+ */
2487
+ declare function missingPackage(error: unknown): string | null;
2488
+ /**
2489
+ * `mod` as the adapter module of `slot` and `provider`, from `pkg`: it must export `createAdapter`, `slot` equal to the
2490
+ * slot and, for any provider but `custom`, `provider` equal to it. A module for another slot is `adapter.wrong_slot`,
2491
+ * anything else wrong `adapter.package_invalid`, each naming the package, the export, the expected and actual value.
1713
2492
  */
1714
- declare function importProviderPackage(slot: Slot, provider: string, env: NodeJS.ProcessEnv): Promise<ProviderModule | undefined>;
2493
+ declare function checkAdapterModule(mod: unknown, slot: Slot, provider: string, pkg: string): ProviderPackageModule;
2494
+ /**
2495
+ * The adapter module the slot's choice resolves to, imported and checked, or `undefined` for `custom` and a built-in.
2496
+ * The specifier is imported from the project root, `process.cwd()`. A package that is not installed is
2497
+ * `adapter.package_missing` with its install line, or `adapter.provider_unknown` (with a suggestion when one is near)
2498
+ * for a convention name no first-party package has; an adapter that resolves another copy of @nymbalhq/types than the
2499
+ * kernel's is `adapter.types_duplicate`; any other load error is rethrown as it is.
2500
+ */
2501
+ declare function importAdapterModule(slot: Slot, choice: Choice, env: NodeJS.ProcessEnv, importer?: (specifier: string) => Promise<unknown>): Promise<ProviderPackageModule | undefined>;
2502
+ /** The fields a provider package lets Settings fill: its `settings` export, or none. */
2503
+ declare function declaredSettings(mod: ProviderPackageModule | undefined): readonly AdapterSetting[];
1715
2504
 
1716
2505
  /**
1717
2506
  * v0.1 security adapter.
1718
2507
  *
1719
- * Rate limiting, CSRF verification and CSRF cookie minting need the request before
1720
- * any middleware and the response after the handler, so the HTTP adapter runs them
1721
- * itself on every route (`FastifyHttpAdapter`'s guard). This adapter only asserts
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
1722
2511
  * static security headers via `HttpAdapter.setDefaultHeaders(...)`. A future
1723
2512
  * WAF-native adapter will replace both layers.
1724
2513
  */
@@ -1754,7 +2543,7 @@ declare function createNativeStubPaymentsAdapter(deps: {
1754
2543
  logger: Logger;
1755
2544
  }): PaymentsAdapter;
1756
2545
 
1757
- /** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/adapter-smtp). */
2546
+ /** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/email-smtp). */
1758
2547
  interface NativeEmailAdapterConfig {
1759
2548
  transport?: 'console';
1760
2549
  from?: string;
@@ -1783,7 +2572,8 @@ declare function createNativeReviewsAdapter(deps: {
1783
2572
 
1784
2573
  declare function createNativeAnalyticsAdapter(logger: Logger): AnalyticsAdapter;
1785
2574
 
1786
- declare function createNativeShippingAdapter(logger: Logger): ShippingAdapter;
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;
1787
2577
 
1788
2578
  declare function createNativeTaxAdapter(logger: Logger, defaultRate?: number): TaxAdapter;
1789
2579
 
@@ -1796,37 +2586,6 @@ interface CreateLoggerOptions {
1796
2586
  }
1797
2587
  declare function createLogger(options?: CreateLoggerOptions): Logger;
1798
2588
 
1799
- /** `ok` is a check with no health semantics (config, a package, migrations); the rest are a health report's. */
1800
- type DiagnosisStatus = HealthStatus | 'ok';
1801
- interface DiagnosisCheck {
1802
- name: string;
1803
- status: DiagnosisStatus;
1804
- detail: string;
1805
- }
1806
- interface DiagnosisReport {
1807
- checks: DiagnosisCheck[];
1808
- }
1809
- interface DiagnoseOptions {
1810
- /** The project's adapters, one per slot whose provider is `custom`, as `createApp` takes them. */
1811
- adapters?: InjectedAdapters;
1812
- logger?: Logger;
1813
- /** Each check's bound; `HEALTH_CHECK_TIMEOUT_MS` when not given. */
1814
- timeoutMs?: number;
1815
- env?: NodeJS.ProcessEnv;
1816
- sqlitePath?: string;
1817
- postgresUrl?: string;
1818
- mediaRoot?: string;
1819
- /** Where the migrations journal is read; the platform's own migrations when not given. */
1820
- migrationsRoot?: string;
1821
- }
1822
- /**
1823
- * Checks a project without changing it: its config, the packages its providers live in, the command store and its
1824
- * migrations, and the health of every commerce slot, the security slot and every primitive. It builds what `createApp`
1825
- * builds, through the same registry and constructors, and nothing more: no warm-up, no relay, no sweeper, no migrator,
1826
- * 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.
1827
- */
1828
- declare function diagnose(input: NymbalConfig, options?: DiagnoseOptions): Promise<DiagnosisReport>;
1829
-
1830
2589
  interface SeedDeps {
1831
2590
  config: NymbalConfig;
1832
2591
  commandStore: CommandStore;
@@ -1927,6 +2686,8 @@ interface RebuildDeps {
1927
2686
  table: string;
1928
2687
  page: number;
1929
2688
  }) => void | Promise<void>;
2689
+ /** Awaited once every model is collected, before a model is caught up and swapped, and after its swap. */
2690
+ onPhase?: (phase: 'collected' | 'swapped', model: ReadModelName) => void | Promise<void>;
1930
2691
  }
1931
2692
  /** What a rebuilder reads with: the command store in pages, each page a read of its own. */
1932
2693
  interface RebuildContext {
@@ -1977,6 +2738,8 @@ interface RebuildReportEntry {
1977
2738
  name: string;
1978
2739
  documents: number;
1979
2740
  }>;
2741
+ /** Logged events applied to the collected contents before the swap. */
2742
+ caughtUpBeforeSwap: number;
1980
2743
  /** Logged events re-applied after the swap. */
1981
2744
  caughtUpEvents: number;
1982
2745
  /** Catch-up events a handler failed on: the model is swapped all the same. */
@@ -1992,8 +2755,9 @@ declare class RebuildError extends Error {
1992
2755
  constructor(model: ReadModelName, cause: unknown);
1993
2756
  }
1994
2757
  /**
1995
- * Rebuilds `names` from the command store's tables: every model is read first, then each is swapped in (atomically
1996
- * per collection) and caught up with the events delivered since its read began. A rebuilder that throws rejects with
2758
+ * Rebuilds `names` from the command store's tables: every model is read first, then each is caught up in memory with
2759
+ * the events delivered since its read began, swapped in (atomically per collection) and caught up again, for the
2760
+ * events delivered while it was swapped. A rebuilder that throws rejects with
1997
2761
  * a `RebuildError` before anything is swapped. Catch-up failures are in the report.
1998
2762
  */
1999
2763
  declare function rebuild(names: readonly ReadModelName[], deps: RebuildDeps): Promise<RebuildReport>;
@@ -2053,5 +2817,5 @@ interface LocalFsMediaStorageOptions {
2053
2817
  declare const LOCAL_FS_MEDIA_CAPABILITIES: readonly string[];
2054
2818
  declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
2055
2819
 
2056
- export { CATCH_UP_MARGIN_MS, CSRF_COOKIE, CSRF_HEADER, InMemoryDocumentStore, InProcessEventBus, LOCAL_FS_MEDIA_CAPABILITIES, PROVIDER_PACKAGES, 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, createAlertService, createAlertSubscriptionRepository, createApp, createAuditEntryRepository, createAuthService, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, 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, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRecentlyViewedService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createSettingsRepository, createStockAdjustmentRepository, createVariantRepository, currentActor, currentCorrelationId, decrypt, diagnose, diffReadModel, emailDelivers, encodeSearchCursor, encrypt, fillFromSettings, findAppliedByKey, importProviderPackage, installLine, isMissingSettingsTable, keyId, keyProblem, listAuditEntries, newAlertToken, newCorrelationId, openReadModels, orderPayment, parseDurationToMs, rawClients, readSecretsKey, rebuild, refreshRefunded, registerAdminStaticRoute, registerAlertHandler, registerAlertRoutes, registerAllRoutes, registerHandlers, resolvePrimitives, routeSchemas, runAsActor, runMigrations, runSeed, runWithCorrelation, scrub, seedCategories, seedProducts, settingAad, settlementOf, sqliteFile, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, withIdempotency };
2057
- export type { AbandonedCart, AbandonedWindow, Actor, AdapterRegistry, AlertConfirmed, AlertService, AlertSubscribeInput, AlertSubscription, AlertSubscriptionPatch, AlertSubscriptionRepository, AlertSubscriptionRequest, AppliedEntry, AttachHttpOptions, AuditCursor, AuditEntryInsert, AuditEntryRepository, AuditFilter, AuditQuery, AuthService, AuthTokens, BeginCheckoutInput, BeginCheckoutResult, BuildAdaptersDeps, BuildServicesDeps, CapabilitiesReport, CapabilitySlot, CapturedPayment, CartRepository, CartService, CatchUpFailure, CategoryCreateInput, CategoryInsert, CategoryRepository, CategoryService, CategoryUpdate, CategoryUpdateInput, CheckoutService, CollectionDiff, CommandStore, CommandStoreOptions, CommerceAdapters, CreateAlertServiceDeps, CreateAppOptions, CreateAuthServiceDeps, CreateCartServiceDeps, CreateCheckoutServiceDeps, CreateInventoryServiceDeps, CreateLoggerOptions, CreateOrderServiceDeps, CreatePlatformOptions, CreateProductServiceDeps, CreatePublisherOptions, CreateRefundServiceDeps, CreateRelayOptions, CustomerInsert, CustomerJwtPayload, CustomerRepository, CustomerService, CustomerUpdate, CustomerWithHash, DiagnoseOptions, DiagnosisCheck, DiagnosisReport, DiagnosisStatus, 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, NativeEmailAdapterConfig, NymbalApp, OpenReadModelsOptions, OrderAccessKeyInsert, OrderAccessKeyPurpose, OrderAccessKeyRepository, OrderCapture, OrderCreateDraftInput, OrderHistoryInsert, OrderHistoryRepository, OrderImportInput, OrderInsert, OrderRefundInsert, OrderRefundRepository, OrderRepository, OrderSequenceRepository, OrderService, Platform, PlatformConnectionOptions, PostgresClient, Primitives, ProcessedEventRepository, ProductCategoryRepository, ProductCreateInput, ProductInsert, ProductRepository, ProductService, ProductUpdate, ProductUpdateInput, ProfileUpdate, ProviderPackage, 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, 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 };