@nymbalhq/platform 1.2.0 → 1.4.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 (33) hide show
  1. package/dist/{chunk-UBEGSSFI.js → chunk-GMV3B3SC.js} +3681 -389
  2. package/dist/chunk-GMV3B3SC.js.map +1 -0
  3. package/dist/{chunk-XVUH34US.js → chunk-SNNK2OX3.js} +129 -7
  4. package/dist/chunk-SNNK2OX3.js.map +1 -0
  5. package/dist/db/schema/index.d.ts +1821 -323
  6. package/dist/db/schema/index.js +1 -1
  7. package/dist/index.d.ts +239 -10
  8. package/dist/index.js +734 -2169
  9. package/dist/index.js.map +1 -1
  10. package/dist/register-N2XGSFUF.js +8 -0
  11. package/migrations/postgres/0012_event_subject.sql +27 -0
  12. package/migrations/postgres/0013_order_access_keys.sql +11 -0
  13. package/migrations/postgres/0014_alert_subscriptions.sql +22 -0
  14. package/migrations/postgres/0015_events_retry_at.sql +1 -0
  15. package/migrations/postgres/meta/0012_snapshot.json +1926 -0
  16. package/migrations/postgres/meta/0013_snapshot.json +2000 -0
  17. package/migrations/postgres/meta/0014_snapshot.json +2185 -0
  18. package/migrations/postgres/meta/0015_snapshot.json +2191 -0
  19. package/migrations/postgres/meta/_journal.json +28 -0
  20. package/migrations/sqlite/0012_event_subject.sql +27 -0
  21. package/migrations/sqlite/0013_order_access_keys.sql +11 -0
  22. package/migrations/sqlite/0014_alert_subscriptions.sql +22 -0
  23. package/migrations/sqlite/0015_events_retry_at.sql +1 -0
  24. package/migrations/sqlite/meta/0012_snapshot.json +1728 -0
  25. package/migrations/sqlite/meta/0013_snapshot.json +1788 -0
  26. package/migrations/sqlite/meta/0014_snapshot.json +1931 -0
  27. package/migrations/sqlite/meta/0015_snapshot.json +1938 -0
  28. package/migrations/sqlite/meta/_journal.json +28 -0
  29. package/package.json +19 -19
  30. package/dist/chunk-UBEGSSFI.js.map +0 -1
  31. package/dist/chunk-XVUH34US.js.map +0 -1
  32. package/dist/register-NHG3TIRQ.js +0 -8
  33. /package/dist/{register-NHG3TIRQ.js.map → register-N2XGSFUF.js.map} +0 -0
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  postgres_exports,
3
3
  sqlite_exports
4
- } from "../../chunk-XVUH34US.js";
4
+ } from "../../chunk-SNNK2OX3.js";
5
5
  export {
6
6
  postgres_exports as postgresSchema,
7
7
  sqlite_exports as sqliteSchema
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
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, HealthReport, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, RequestAuth, AdapterSetting, CommerceSlotAdapters, SecurityAdapter, AiAdapter, PaymentsAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, SearchAdapter, OrderPayment, Refund, CommerceSlot, HttpAdapter, Slot, ProviderPackageModule, RateLimitAction, EmailAdapter, ReviewsAdapter, AnalyticsAdapter, ShippingAdapter, TaxAdapter, HealthStatus } from '@nymbalhq/types';
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';
3
3
  export { MediaStorage, buildSecurityHeaders, isValidCorrelationId } from '@nymbalhq/types';
4
4
  import BetterSqlite3 from 'better-sqlite3';
5
5
  import pg from 'pg';
@@ -485,6 +485,23 @@ interface OrderSequenceRepository extends StoreRepository {
485
485
  }
486
486
  declare function createOrderSequenceRepository(store: CommandStore): OrderSequenceRepository;
487
487
 
488
+ /** Who minted the key: a checkout answer, or the order-placed email. */
489
+ type OrderAccessKeyPurpose = 'checkout' | 'email';
490
+ interface OrderAccessKeyInsert {
491
+ id: string;
492
+ orderId: string;
493
+ /** sha256 hex of the key; the key itself is never stored. */
494
+ keyHash: string;
495
+ purpose: OrderAccessKeyPurpose;
496
+ createdAt: Date;
497
+ }
498
+ interface OrderAccessKeyRepository extends StoreRepository {
499
+ 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>;
502
+ }
503
+ declare function createOrderAccessKeyRepository(store: CommandStore): OrderAccessKeyRepository;
504
+
488
505
  interface ReservationInsert {
489
506
  reservationId: string;
490
507
  variantId: string;
@@ -558,11 +575,22 @@ interface ProcessedEventRepository extends StoreRepository {
558
575
  seen(tx: ReadTx, handlerName: string, eventId: string): Promise<boolean>;
559
576
  /** Idempotent on (handlerName, eventId): a second call keeps the first record. */
560
577
  markProcessed(tx: Tx, handlerName: string, eventId: string, at: Date): Promise<void>;
578
+ /**
579
+ * Records (handlerName, eventId) before its work runs: true when this call inserted it, false when it was there.
580
+ * On Postgres a concurrent claim of the same key waits for this transaction, so only one of them does the work.
581
+ */
582
+ claim(tx: Tx, handlerName: string, eventId: string, at: Date): Promise<boolean>;
561
583
  /** Deletes records processed before `at`; returns how many. */
562
584
  deleteBefore(tx: Tx, at: Date): Promise<number>;
563
585
  }
564
586
  declare function createProcessedEventRepository(store: CommandStore): ProcessedEventRepository;
565
587
 
588
+ /** The record an event is about: what `events.subject_type` and `events.subject_id` hold. */
589
+ interface EventSubject {
590
+ type: string;
591
+ id: string;
592
+ }
593
+
566
594
  interface LoggedEvent {
567
595
  seq: number;
568
596
  event: NymbalEvent<unknown>;
@@ -584,11 +612,22 @@ interface EventLogFilter {
584
612
  interface EventLogRepository extends StoreRepository {
585
613
  /** Appends in array order, so `seq` follows publish order. */
586
614
  append(tx: Tx, events: NymbalEvent<unknown>[]): Promise<void>;
587
- /** Neither delivered nor dead, by `seq`; `afterSeq` pages through one pass without re-reading rows it just tried. */
588
- listUndelivered(tx: ReadTx, limit: number, afterSeq?: number): Promise<LoggedEvent[]>;
615
+ /**
616
+ * Neither delivered nor dead, by `seq`; `afterSeq` pages through one pass without re-reading rows it just tried.
617
+ * Given `now`, a row whose `retry_at` is after it is left out.
618
+ */
619
+ listUndelivered(tx: ReadTx, limit: number, afterSeq?: number, now?: Date): Promise<LoggedEvent[]>;
589
620
  markDelivered(tx: Tx, ids: string[], at: Date): Promise<void>;
590
- /** One more failed attempt; the event is dead (`dead_at = at`) once its attempts reach `maxAttempts`. */
591
- recordFailure(tx: Tx, id: string, at: Date, maxAttempts: number): Promise<void>;
621
+ /**
622
+ * One more failed attempt; the event is dead (`dead_at = at`) once its attempts reach `maxAttempts`. `retryAt`, when
623
+ * given, is the earliest the next attempt may be made.
624
+ */
625
+ recordFailure(tx: Tx, id: string, at: Date, maxAttempts: number, retryAt?: Date): Promise<void>;
626
+ countDead(tx: ReadTx): Promise<number>;
627
+ /** Dead events, oldest first. */
628
+ listDead(tx: ReadTx, limit: number): Promise<LoggedEvent[]>;
629
+ /** Neither delivered nor dead, with at least one failed attempt. */
630
+ countRetrying(tx: ReadTx): Promise<number>;
592
631
  /** Deletes delivered events delivered before `at`; returns how many. Undelivered and dead events are never deleted. */
593
632
  deleteDeliveredBefore(tx: Tx, at: Date): Promise<number>;
594
633
  listAll(tx: ReadTx): Promise<LoggedEvent[]>;
@@ -610,6 +649,15 @@ interface EventLogRepository extends StoreRepository {
610
649
  listDeliveredBefore(tx: ReadTx, at: Date, limit: number): Promise<LoggedEvent[]>;
611
650
  /** Deletes the delivered events with these `seq`s; returns how many. */
612
651
  deleteSeqs(tx: Tx, seqs: number[]): Promise<number>;
652
+ /**
653
+ * The events whose subject is one of `subjects`, by `seq`: those appended at or before `until`, above `afterSeq`, at
654
+ * most `limit`.
655
+ */
656
+ listBySubjects(tx: ReadTx, subjects: EventSubject[], page: {
657
+ until?: Date;
658
+ afterSeq?: number;
659
+ limit: number;
660
+ }): Promise<LoggedEvent[]>;
613
661
  }
614
662
  declare function createEventLogRepository(store: CommandStore): EventLogRepository;
615
663
 
@@ -739,6 +787,61 @@ interface AuditEntryRepository extends StoreRepository {
739
787
  }
740
788
  declare function createAuditEntryRepository(store: CommandStore): AuditEntryRepository;
741
789
 
790
+ /** A row of `alert_subscriptions`: one address's alert of one kind on one variant. */
791
+ interface AlertSubscription {
792
+ id: string;
793
+ /** Trimmed and lower-cased. */
794
+ email: string;
795
+ kind: AlertKind;
796
+ variantId: string;
797
+ productId: string;
798
+ status: AlertStatus;
799
+ confirmToken: string;
800
+ unsubscribeToken: string;
801
+ /** The storefront origin its links point at. */
802
+ origin: string;
803
+ baselinePriceMinor: number | null;
804
+ createdAt: Date;
805
+ updatedAt: Date;
806
+ confirmedAt: Date | null;
807
+ }
808
+ /** A subscribe request: a new row's values, of which a row already there takes only what its status allows. */
809
+ interface AlertSubscriptionRequest {
810
+ id: string;
811
+ email: string;
812
+ kind: AlertKind;
813
+ variantId: string;
814
+ productId: string;
815
+ confirmToken: string;
816
+ unsubscribeToken: string;
817
+ origin: string;
818
+ /** A price-drop row's price at subscribe time; null for a back-in-stock row. */
819
+ baselinePriceMinor: number | null;
820
+ at: Date;
821
+ }
822
+ interface AlertSubscriptionPatch {
823
+ status: AlertStatus;
824
+ updatedAt: Date;
825
+ confirmedAt?: Date;
826
+ /** The price a price-drop row was last told. */
827
+ baselinePriceMinor?: number;
828
+ }
829
+ interface AlertSubscriptionRepository extends StoreRepository {
830
+ /**
831
+ * One write on the unique (email, variant, kind): a new row is `pending`; a `pending` row takes the request's origin;
832
+ * 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.
834
+ */
835
+ upsertPending(tx: Tx, request: AlertSubscriptionRequest): Promise<AlertSubscription>;
836
+ findById(tx: ReadTx, id: string): Promise<AlertSubscription | null>;
837
+ findByConfirmToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
838
+ findByUnsubscribeToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
839
+ listActive(tx: ReadTx, variantId: string, kind: AlertKind): Promise<AlertSubscription[]>;
840
+ /** Applies `patch` when the row's status is one of `from`; the row after, or null when nothing changed. */
841
+ update(tx: Tx, id: string, patch: AlertSubscriptionPatch, from: readonly AlertStatus[]): Promise<AlertSubscription | null>;
842
+ }
843
+ declare function createAlertSubscriptionRepository(store: CommandStore): AlertSubscriptionRepository;
844
+
742
845
  interface Repositories {
743
846
  product: ProductRepository;
744
847
  variant: VariantRepository;
@@ -750,6 +853,7 @@ interface Repositories {
750
853
  orderHistory: OrderHistoryRepository;
751
854
  orderRefund: OrderRefundRepository;
752
855
  orderSequence: OrderSequenceRepository;
856
+ orderAccessKey: OrderAccessKeyRepository;
753
857
  inventoryReservation: InventoryReservationRepository;
754
858
  stockAdjustment: StockAdjustmentRepository;
755
859
  review: ReviewRepository;
@@ -758,6 +862,7 @@ interface Repositories {
758
862
  cart: CartRepository;
759
863
  settings: SettingsRepository;
760
864
  auditEntry: AuditEntryRepository;
865
+ alertSubscription: AlertSubscriptionRepository;
761
866
  }
762
867
  declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
763
868
 
@@ -836,6 +941,10 @@ interface CreateRelayOptions {
836
941
  /** Failed bus publishes after which an event is dead and never handed to the bus again. */
837
942
  maxAttempts?: number;
838
943
  intervalMs?: number;
944
+ /** The wait before the first retry of a failed event (default `intervalMs`); each later wait doubles it. */
945
+ retryDelayMs?: number;
946
+ /** The clock failures and retry waits are read from. */
947
+ now?: () => Date;
839
948
  }
840
949
  declare function createRelay(opts: CreateRelayOptions): Relay;
841
950
 
@@ -850,6 +959,14 @@ interface EventPublisher {
850
959
  options?: PublishOptions;
851
960
  };
852
961
  }[NymbalEventType]>): Promise<void>;
962
+ /**
963
+ * Events of types the kernel does not declare (an adapter's own, already checked by the caller), with the same
964
+ * append and drain as `publish`.
965
+ */
966
+ publishUntyped(events: ReadonlyArray<{
967
+ type: string;
968
+ payload: unknown;
969
+ }>, options?: PublishOptions): Promise<NymbalEvent<unknown>[]>;
853
970
  correlated(correlationId: string): EventPublisher;
854
971
  }
855
972
  interface CreatePublisherOptions {
@@ -933,16 +1050,72 @@ interface BuildAdaptersDeps {
933
1050
  }
934
1051
  declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
935
1052
 
1053
+ interface AlertSubscribeInput {
1054
+ email: string;
1055
+ variantId: string;
1056
+ kind: AlertKind;
1057
+ /** The request's `Origin` header: the storefront the links in its emails point at. */
1058
+ origin: string | undefined;
1059
+ }
1060
+ interface AlertConfirmed {
1061
+ status: 'active';
1062
+ kind: AlertKind;
1063
+ product: {
1064
+ name: string;
1065
+ slug: string;
1066
+ };
1067
+ }
1068
+ interface AlertService {
1069
+ /**
1070
+ * 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.
1072
+ */
1073
+ subscribe(input: AlertSubscribeInput): Promise<{
1074
+ status: 'pending';
1075
+ }>;
1076
+ confirm(token: string): Promise<AlertConfirmed>;
1077
+ unsubscribe(token: string): Promise<{
1078
+ status: 'unsubscribed';
1079
+ }>;
1080
+ /**
1081
+ * 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.
1083
+ */
1084
+ recordSent(tx: Tx, subscription: AlertSubscription, trigger: NymbalEvent<unknown>): Promise<void>;
1085
+ }
1086
+ interface CreateAlertServiceDeps {
1087
+ store: CommandStore;
1088
+ repos: Repositories;
1089
+ publisher: EventPublisher;
1090
+ /** `http.cors.allowedOrigins`: the storefronts a subscribe may come from. A `*` entry matches no origin. */
1091
+ allowedOrigins: readonly string[];
1092
+ /** Whether the store's email reaches a mailbox; a store whose email only logs takes no subscription. */
1093
+ delivers(): boolean;
1094
+ }
1095
+ declare function createAlertService(deps: CreateAlertServiceDeps): AlertService;
1096
+
936
1097
  interface RegisterHandlersDeps {
937
1098
  config: NymbalConfig;
938
1099
  eventBus: EventBusAdapter;
939
1100
  documentStore: DocumentStoreAdapter;
940
1101
  repos: Repositories;
941
1102
  adapters: AdapterRegistry;
1103
+ /** Records each alert's send: the row fired and `alert.sent.v1` published. */
1104
+ alerts: AlertService;
942
1105
  logger: Logger;
943
1106
  }
944
1107
  declare function registerHandlers(deps: RegisterHandlersDeps): Promise<void>;
945
1108
 
1109
+ interface RegisterAlertHandlerDeps {
1110
+ eventBus: EventBusAdapter;
1111
+ email: EmailAdapter;
1112
+ logger: Logger;
1113
+ repos: Pick<Repositories, 'alertSubscription' | 'processedEvent' | 'product'>;
1114
+ alerts: AlertService;
1115
+ storeName: string;
1116
+ }
1117
+ declare function registerAlertHandler(deps: RegisterAlertHandlerDeps): Promise<void>;
1118
+
946
1119
  interface ProductCreateInput {
947
1120
  slug: string;
948
1121
  name: string;
@@ -959,8 +1132,16 @@ interface ProductCreateInput {
959
1132
  id?: string;
960
1133
  }>;
961
1134
  }
1135
+ /** A variant's prices: `compareAtPriceMinor` omitted keeps the stored one, null clears it. */
1136
+ interface VariantPriceInput {
1137
+ id: string;
1138
+ priceMinor: number;
1139
+ compareAtPriceMinor?: number | null;
1140
+ }
962
1141
  interface ProductUpdateInput extends Omit<ProductUpdate, 'updatedAt'> {
963
1142
  categoryIds?: string[];
1143
+ /** Prices of some of the product's own variants; a variant left out is unchanged, and none is added or deleted. */
1144
+ variants?: VariantPriceInput[];
964
1145
  }
965
1146
  interface ProductService {
966
1147
  create(input: ProductCreateInput): Promise<ProductSnapshot>;
@@ -981,6 +1162,8 @@ interface CreateProductServiceDeps {
981
1162
  repos: Repositories;
982
1163
  publisher: EventPublisher;
983
1164
  logger: Logger;
1165
+ /** The store's currency, which a price event names. */
1166
+ currency: string;
984
1167
  }
985
1168
  declare function createProductService(deps: CreateProductServiceDeps): ProductService;
986
1169
 
@@ -1102,6 +1285,7 @@ interface CreateAuthServiceDeps {
1102
1285
  refreshTtl: string;
1103
1286
  issuer?: string;
1104
1287
  }
1288
+ declare function parseDurationToMs(s: string): number;
1105
1289
  declare function createAuthService(deps: CreateAuthServiceDeps): AuthService;
1106
1290
 
1107
1291
  interface OrderCreateDraftInput {
@@ -1137,11 +1321,18 @@ interface OrderService {
1137
1321
  getById(id: string): Promise<Order>;
1138
1322
  getByOrderNumber(orderNumber: string): Promise<Order>;
1139
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>;
1140
1326
  updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
1141
1327
  markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
1142
1328
  markDelivered(id: string, actor: string): Promise<Order>;
1143
1329
  /** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
1144
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>;
1145
1336
  }
1146
1337
  interface CreateOrderServiceDeps {
1147
1338
  store: CommandStore;
@@ -1198,6 +1389,8 @@ interface BeginCheckoutResult {
1198
1389
  /** The order's status as the checkout answers. */
1199
1390
  orderStatus: OrderStatus;
1200
1391
  payment: CheckoutPayment;
1392
+ /** A fresh key that reads the order with no session (`ORDER_KEY_HEADER`). Only its hash is stored. */
1393
+ orderKey: string;
1201
1394
  }
1202
1395
  /** What the payment provider captured. */
1203
1396
  interface CapturedPayment {
@@ -1300,6 +1493,27 @@ declare function refreshRefunded(repos: Repositories, tx: Tx, orderId: string, a
1300
1493
  }>;
1301
1494
  declare function createRefundService(deps: CreateRefundServiceDeps): RefundService;
1302
1495
 
1496
+ interface RecentlyViewedServiceDeps {
1497
+ store: CommandStore;
1498
+ repos: Pick<Repositories, 'product'>;
1499
+ publisher: EventPublisher;
1500
+ logger: Logger;
1501
+ /** The view's time, which its event carries. */
1502
+ now?: () => Date;
1503
+ }
1504
+ interface RecentlyViewedService {
1505
+ /** Logs a view of an active product; false, and nothing logged, for any other id. */
1506
+ record(viewer: RecentViewer, productId: string): Promise<boolean>;
1507
+ /** Moves a visitor's views to the customer who signed in carrying its cookie. */
1508
+ fold(visitorId: string, customerId: string): Promise<void>;
1509
+ }
1510
+ declare function createRecentlyViewedService(deps: RecentlyViewedServiceDeps): RecentlyViewedService;
1511
+
1512
+ /** A confirm or unsubscribe link's bearer credential: 32 random bytes, base64url (43 characters). */
1513
+ declare function newAlertToken(): string;
1514
+
1515
+ /** A `native` email adapter only logs; any other (`smtp`, a project's own) is taken to reach a mailbox. */
1516
+ declare function emailDelivers(email: EmailAdapter): boolean;
1303
1517
  interface ServiceRegistry {
1304
1518
  product: ProductService;
1305
1519
  category: CategoryService;
@@ -1311,6 +1525,8 @@ interface ServiceRegistry {
1311
1525
  checkout: CheckoutService & ManualPayments;
1312
1526
  refund: RefundService;
1313
1527
  search: SearchService;
1528
+ recentlyViewed: RecentlyViewedService;
1529
+ alert: AlertService;
1314
1530
  }
1315
1531
  interface BuildServicesDeps {
1316
1532
  config: NymbalConfig;
@@ -1320,6 +1536,7 @@ interface BuildServicesDeps {
1320
1536
  logger: Logger;
1321
1537
  payments: PaymentsAdapter;
1322
1538
  searchAdapter: SearchAdapter;
1539
+ email: EmailAdapter;
1323
1540
  }
1324
1541
  declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
1325
1542
 
@@ -1348,6 +1565,11 @@ interface RegisterAllRoutesDeps {
1348
1565
  }
1349
1566
  declare function registerAllRoutes(deps: RegisterAllRoutesDeps): void;
1350
1567
 
1568
+ interface RegisterAlertRoutesDeps {
1569
+ alerts: AlertService;
1570
+ }
1571
+ declare function registerAlertRoutes(adapter: HttpAdapter, deps: RegisterAlertRoutesDeps): void;
1572
+
1351
1573
  /**
1352
1574
  * The input of one route: what `registerAllRoutes` parses before the handler runs, and what a tool definition is
1353
1575
  * generated from. Unknown keys are stripped, so a handler sees only what is declared here.
@@ -1402,6 +1624,8 @@ interface CreateAppOptions extends ResolvePrimitivesOptions {
1402
1624
  version?: string;
1403
1625
  /** The project's own adapters, one per slot whose provider is `custom`. */
1404
1626
  adapters?: InjectedAdapters;
1627
+ /** How the event relay retries a failed delivery (`createRelay`). */
1628
+ relay?: Pick<CreateRelayOptions, 'maxAttempts' | 'retryDelayMs' | 'intervalMs' | 'now'>;
1405
1629
  }
1406
1630
  declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
1407
1631
 
@@ -1563,8 +1787,6 @@ declare function createNativeShippingAdapter(logger: Logger): ShippingAdapter;
1563
1787
 
1564
1788
  declare function createNativeTaxAdapter(logger: Logger, defaultRate?: number): TaxAdapter;
1565
1789
 
1566
- declare function createNativeAiAdapter(_logger: Logger): AiAdapter;
1567
-
1568
1790
  interface CreateLoggerOptions {
1569
1791
  level?: string;
1570
1792
  pretty?: boolean;
@@ -1687,7 +1909,7 @@ interface DocumentWrite {
1687
1909
  doc: unknown;
1688
1910
  }
1689
1911
 
1690
- type ReadModelName = 'catalogue' | 'orders' | 'customers' | 'search';
1912
+ type ReadModelName = 'catalogue' | 'orders' | 'customers' | 'search' | 'recently-viewed';
1691
1913
  interface RebuildDeps {
1692
1914
  config: NymbalConfig;
1693
1915
  store: CommandStore;
@@ -1712,6 +1934,13 @@ interface RebuildContext {
1712
1934
  pages<T extends {
1713
1935
  id: string;
1714
1936
  }>(table: string, read: (tx: ReadTx, page: KeysetPage) => Promise<T[]>): AsyncIterable<T[]>;
1937
+ /**
1938
+ * The logged events of `types`, in seq pages, each page a read of its own (`onPage` names the table `events`). A model
1939
+ * that reads them is caught up only with events above the last one it read: re-applying one it already folded
1940
+ * would fold it twice. The bound is per model, not per collection: a model that reads both `pages()` and `events()`
1941
+ * would skip catch-up for the collections it builds from tables.
1942
+ */
1943
+ events(types: readonly string[]): AsyncIterable<LoggedEvent[]>;
1715
1944
  }
1716
1945
  interface ReadModel {
1717
1946
  name: ReadModelName;
@@ -1824,5 +2053,5 @@ interface LocalFsMediaStorageOptions {
1824
2053
  declare const LOCAL_FS_MEDIA_CAPABILITIES: readonly string[];
1825
2054
  declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
1826
2055
 
1827
- 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, 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, createNativeAiAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createSettingsRepository, createStockAdjustmentRepository, createVariantRepository, currentActor, currentCorrelationId, decrypt, diagnose, diffReadModel, encodeSearchCursor, encrypt, fillFromSettings, findAppliedByKey, importProviderPackage, installLine, isMissingSettingsTable, keyId, keyProblem, listAuditEntries, newCorrelationId, openReadModels, orderPayment, rawClients, readSecretsKey, rebuild, refreshRefunded, registerAdminStaticRoute, registerAllRoutes, registerHandlers, resolvePrimitives, routeSchemas, runAsActor, runMigrations, runSeed, runWithCorrelation, scrub, seedCategories, seedProducts, settingAad, settlementOf, sqliteFile, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, withIdempotency };
1828
- export type { AbandonedCart, AbandonedWindow, Actor, AdapterRegistry, 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, 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, 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, RefreshTokenInsert, RefreshTokenRepository, RefreshTokenRow, RefundInput, RefundResult, RefundService, 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, VariantRepository, VariantUpdate };
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 };