@nymbalhq/platform 1.4.0 → 1.5.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 (29) hide show
  1. package/dist/{chunk-SNNK2OX3.js → chunk-NNDIAIT6.js} +73 -5
  2. package/dist/chunk-NNDIAIT6.js.map +1 -0
  3. package/dist/{chunk-GMV3B3SC.js → chunk-TRLERRUI.js} +424 -137
  4. package/dist/chunk-TRLERRUI.js.map +1 -0
  5. package/dist/db/schema/index.d.ts +795 -105
  6. package/dist/db/schema/index.js +1 -1
  7. package/dist/index.d.ts +218 -85
  8. package/dist/index.js +658 -199
  9. package/dist/index.js.map +1 -1
  10. package/dist/register-SBGUI2L5.js +8 -0
  11. package/migrations/postgres/0016_email_suppressions.sql +7 -0
  12. package/migrations/postgres/0017_order_shipments.sql +14 -0
  13. package/migrations/postgres/0018_order_key_expiry.sql +8 -0
  14. package/migrations/postgres/meta/0016_snapshot.json +2233 -0
  15. package/migrations/postgres/meta/0017_snapshot.json +2300 -0
  16. package/migrations/postgres/meta/0018_snapshot.json +2306 -0
  17. package/migrations/postgres/meta/_journal.json +21 -0
  18. package/migrations/sqlite/0016_email_suppressions.sql +7 -0
  19. package/migrations/sqlite/0017_order_shipments.sql +9 -0
  20. package/migrations/sqlite/0018_order_key_expiry.sql +25 -0
  21. package/migrations/sqlite/meta/0016_snapshot.json +1981 -0
  22. package/migrations/sqlite/meta/0017_snapshot.json +2041 -0
  23. package/migrations/sqlite/meta/0018_snapshot.json +2048 -0
  24. package/migrations/sqlite/meta/_journal.json +21 -0
  25. package/package.json +17 -47
  26. package/dist/chunk-GMV3B3SC.js.map +0 -1
  27. package/dist/chunk-SNNK2OX3.js.map +0 -1
  28. package/dist/register-N2XGSFUF.js +0 -8
  29. /package/dist/{register-N2XGSFUF.js.map → register-SBGUI2L5.js.map} +0 -0
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  postgres_exports,
3
3
  sqlite_exports
4
- } from "../../chunk-SNNK2OX3.js";
4
+ } from "../../chunk-NNDIAIT6.js";
5
5
  export {
6
6
  postgres_exports as postgresSchema,
7
7
  sqlite_exports as sqliteSchema
package/dist/index.d.ts CHANGED
@@ -104,7 +104,9 @@ declare const REDIS_DEFAULTS: {
104
104
  };
105
105
  /**
106
106
  * 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.
107
+ * imported only when named, from its block's `package` or `@nymbalhq/<slot>-<provider>`; a missing package fails
108
+ * `adapter.package_missing` with the install line. A provider whose connection the kernel does not build gets its
109
+ * block's `config`.
108
110
  */
109
111
  declare function resolvePrimitives(config: NymbalConfig, options?: ResolvePrimitivesOptions): Promise<Primitives>;
110
112
  declare function createPlatform(config: NymbalConfig, options: CreatePlatformOptions): Platform;
@@ -113,6 +115,17 @@ interface MigrateOptions {
113
115
  migrationsRoot?: string;
114
116
  }
115
117
  declare function runMigrations(store: CommandStore, options?: MigrateOptions): Promise<void>;
118
+ interface MigrationState {
119
+ /** Rows in the store's migrations table. */
120
+ applied: number;
121
+ /** Journal entries `runMigrations` would apply. */
122
+ pending: number;
123
+ }
124
+ /**
125
+ * What `runMigrations` would do to `store`, read without writing. Drizzle applies every journal entry created after the
126
+ * newest one its table records, so that is what counts as pending; a store with no table has every entry pending.
127
+ */
128
+ declare function migrationState(store: CommandStore, options?: MigrateOptions): Promise<MigrationState>;
116
129
 
117
130
  interface ProductInsert$1 {
118
131
  id: string;
@@ -487,6 +500,8 @@ declare function createOrderSequenceRepository(store: CommandStore): OrderSequen
487
500
 
488
501
  /** Who minted the key: a checkout answer, or the order-placed email. */
489
502
  type OrderAccessKeyPurpose = 'checkout' | 'email';
503
+ /** What a key does for an order: opens it, has expired, or is not one of its keys. */
504
+ type OrderKeyState = 'open' | 'expired' | 'none';
490
505
  interface OrderAccessKeyInsert {
491
506
  id: string;
492
507
  orderId: string;
@@ -494,11 +509,14 @@ interface OrderAccessKeyInsert {
494
509
  keyHash: string;
495
510
  purpose: OrderAccessKeyPurpose;
496
511
  createdAt: Date;
512
+ expiresAt: Date;
497
513
  }
498
514
  interface OrderAccessKeyRepository extends StoreRepository {
499
515
  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>;
516
+ /** What a key with this hash does for this order at `now`: another order's key is `none` here. */
517
+ opens(tx: ReadTx, orderId: string, keyHash: string, now: Date): Promise<OrderKeyState>;
518
+ /** Deletes the order's oldest keys of `purpose`, by `(created_at, id)`, until at most `keep` remain. */
519
+ keepNewest(tx: Tx, orderId: string, purpose: OrderAccessKeyPurpose, keep: number): Promise<void>;
502
520
  }
503
521
  declare function createOrderAccessKeyRepository(store: CommandStore): OrderAccessKeyRepository;
504
522
 
@@ -623,6 +641,8 @@ interface EventLogRepository extends StoreRepository {
623
641
  * given, is the earliest the next attempt may be made.
624
642
  */
625
643
  recordFailure(tx: Tx, id: string, at: Date, maxAttempts: number, retryAt?: Date): Promise<void>;
644
+ /** A delivery that failed during an adapter outage: only the earliest next attempt moves, nothing is counted. */
645
+ recordOutage(tx: Tx, id: string, retryAt: Date): Promise<void>;
626
646
  countDead(tx: ReadTx): Promise<number>;
627
647
  /** Dead events, oldest first. */
628
648
  listDead(tx: ReadTx, limit: number): Promise<LoggedEvent[]>;
@@ -842,6 +862,36 @@ interface AlertSubscriptionRepository extends StoreRepository {
842
862
  }
843
863
  declare function createAlertSubscriptionRepository(store: CommandStore): AlertSubscriptionRepository;
844
864
 
865
+ type EmailSuppressionReason = 'hard_bounce' | 'complaint';
866
+ interface EmailSuppressionInput {
867
+ email: string;
868
+ reason: EmailSuppressionReason;
869
+ /** The feedback event that suppresses the address. */
870
+ eventId: string;
871
+ at: Date;
872
+ }
873
+ /** Addresses that hard-bounced or complained. Each method normalises the address it is given. */
874
+ interface EmailSuppressionRepository extends StoreRepository {
875
+ /** True when this call suppressed the address; false when it already was, whose first reason stays. */
876
+ suppress(tx: Tx, input: EmailSuppressionInput): Promise<boolean>;
877
+ isSuppressed(tx: ReadTx, email: string): Promise<boolean>;
878
+ }
879
+ declare function createEmailSuppressionRepository(store: CommandStore): EmailSuppressionRepository;
880
+
881
+ interface OrderShipmentInput {
882
+ orderId: string;
883
+ carrier: string;
884
+ trackingNumber: string;
885
+ at: Date;
886
+ }
887
+ /** The parcel each shipped order went out in. Each method normalises the tracking number it is given. */
888
+ interface OrderShipmentRepository extends StoreRepository {
889
+ record(tx: Tx, input: OrderShipmentInput): Promise<void>;
890
+ /** The ids of every order shipped under the number, in no particular order. */
891
+ ordersByTrackingNumber(tx: ReadTx, trackingNumber: string): Promise<string[]>;
892
+ }
893
+ declare function createOrderShipmentRepository(store: CommandStore): OrderShipmentRepository;
894
+
845
895
  interface Repositories {
846
896
  product: ProductRepository;
847
897
  variant: VariantRepository;
@@ -863,6 +913,8 @@ interface Repositories {
863
913
  settings: SettingsRepository;
864
914
  auditEntry: AuditEntryRepository;
865
915
  alertSubscription: AlertSubscriptionRepository;
916
+ emailSuppression: EmailSuppressionRepository;
917
+ orderShipment: OrderShipmentRepository;
866
918
  }
867
919
  declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
868
920
 
@@ -917,6 +969,15 @@ interface MakeEventOptions {
917
969
  }
918
970
  declare function createEventBuilder(ctx: EventBuilderContext): <T>(type: string, payload: T, options?: MakeEventOptions) => NymbalEvent<T>;
919
971
 
972
+ interface OutageReport {
973
+ /** True when any checked subject is down, threw or did not answer in time. */
974
+ outage: boolean;
975
+ down: readonly {
976
+ name: string;
977
+ detail: string;
978
+ }[];
979
+ }
980
+
920
981
  /** Hands committed events from the log to the bus. */
921
982
  interface Relay {
922
983
  /** Delivers every undelivered, non-dead event in `seq` order. Never rejects. */
@@ -945,6 +1006,13 @@ interface CreateRelayOptions {
945
1006
  retryDelayMs?: number;
946
1007
  /** The clock failures and retry waits are read from. */
947
1008
  now?: () => Date;
1009
+ /**
1010
+ * Asked once a pass, at its first failed delivery: a failure during an outage is not counted toward `maxAttempts`.
1011
+ * Absent, no failure is an outage.
1012
+ */
1013
+ outage?: () => Promise<OutageReport>;
1014
+ /** How long the relay waits on `outage` before taking the pass as an outage (default the health check bound + 1 s). */
1015
+ outageTimeoutMs?: number;
948
1016
  }
949
1017
  declare function createRelay(opts: CreateRelayOptions): Relay;
950
1018
 
@@ -1094,6 +1162,70 @@ interface CreateAlertServiceDeps {
1094
1162
  }
1095
1163
  declare function createAlertService(deps: CreateAlertServiceDeps): AlertService;
1096
1164
 
1165
+ interface OrderCreateDraftInput {
1166
+ orderId: string;
1167
+ customerId: string | null;
1168
+ email: string;
1169
+ billingAddress: Address;
1170
+ shippingAddress: Address;
1171
+ lineItems: OrderLineItem[];
1172
+ subtotalMinor: number;
1173
+ taxTotalMinor: number;
1174
+ shippingTotalMinor: number;
1175
+ discountTotalMinor: number;
1176
+ totalMinor: number;
1177
+ currency: string;
1178
+ notes?: string;
1179
+ metadata?: Record<string, unknown>;
1180
+ paymentIntentId?: string | null;
1181
+ cartToken?: string | null;
1182
+ }
1183
+ interface OrderImportInput extends OrderCreateDraftInput {
1184
+ orderNumber: string;
1185
+ status: OrderStatus;
1186
+ createdAt: Date;
1187
+ /** What the imported order was paid, taken as captured when it was placed; nothing when absent. */
1188
+ capturedMinor?: number;
1189
+ refundedMinor?: number;
1190
+ captureMethod?: CaptureMethod | null;
1191
+ }
1192
+ interface OrderService {
1193
+ createFromCheckout(input: OrderCreateDraftInput): Promise<Order>;
1194
+ importOrder(input: OrderImportInput): Promise<Order>;
1195
+ getById(id: string): Promise<Order>;
1196
+ getByOrderNumber(orderNumber: string): Promise<Order>;
1197
+ listByCustomer(customerId: string): Promise<Order[]>;
1198
+ /** Whether `key` opens the order now: one of its own keys, well formed and unexpired. */
1199
+ keyOpens(orderId: string, key: string): Promise<boolean>;
1200
+ /** What `key` does for the order at `now`: another order's key, or a malformed one, is `none`. */
1201
+ keyState(orderId: string, key: string, now?: Date): Promise<OrderKeyState>;
1202
+ /**
1203
+ * "Send me my order link": when the number and email name an order a confirmation is due for (confirmed or later),
1204
+ * its order-placed email is sent again, with a fresh link for a guest's order. Anything else does nothing, and the
1205
+ * caller is told nothing either way.
1206
+ */
1207
+ requestLink(orderNumber: string, email: string): Promise<void>;
1208
+ updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
1209
+ markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
1210
+ markDelivered(id: string, actor: string): Promise<Order>;
1211
+ /** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
1212
+ cancel(id: string, reason: string, actor: string): Promise<Order>;
1213
+ /**
1214
+ * Asks for the order's confirmation email again; the email handler sends it. Refuses with `order.unpaid` for an
1215
+ * order no confirmation is due for (pending, or cancelled and so never paid). Changes nothing on the order.
1216
+ */
1217
+ resendConfirmation(id: string): Promise<Order>;
1218
+ }
1219
+ interface CreateOrderServiceDeps {
1220
+ store: CommandStore;
1221
+ repos: Repositories;
1222
+ publisher: EventPublisher;
1223
+ logger: Logger;
1224
+ orderNumberPrefix: string;
1225
+ orderNumberStart: number;
1226
+ }
1227
+ declare function createOrderService(deps: CreateOrderServiceDeps): OrderService;
1228
+
1097
1229
  interface RegisterHandlersDeps {
1098
1230
  config: NymbalConfig;
1099
1231
  eventBus: EventBusAdapter;
@@ -1102,6 +1234,8 @@ interface RegisterHandlersDeps {
1102
1234
  adapters: AdapterRegistry;
1103
1235
  /** Records each alert's send: the row fired and `alert.sent.v1` published. */
1104
1236
  alerts: AlertService;
1237
+ /** Moves an order a tracking update reports delivered. */
1238
+ orders: OrderService;
1105
1239
  logger: Logger;
1106
1240
  }
1107
1241
  declare function registerHandlers(deps: RegisterHandlersDeps): Promise<void>;
@@ -1110,7 +1244,7 @@ interface RegisterAlertHandlerDeps {
1110
1244
  eventBus: EventBusAdapter;
1111
1245
  email: EmailAdapter;
1112
1246
  logger: Logger;
1113
- repos: Pick<Repositories, 'alertSubscription' | 'processedEvent' | 'product'>;
1247
+ repos: Pick<Repositories, 'alertSubscription' | 'emailSuppression' | 'processedEvent' | 'product'>;
1114
1248
  alerts: AlertService;
1115
1249
  storeName: string;
1116
1250
  }
@@ -1222,12 +1356,20 @@ interface ProfileUpdate {
1222
1356
  lastName?: string;
1223
1357
  phone?: string;
1224
1358
  }
1359
+ /** An admin's note on a customer, kept in its metadata. */
1360
+ interface CustomerNote {
1361
+ body: string;
1362
+ actor: string;
1363
+ at: string;
1364
+ }
1225
1365
  interface CustomerService {
1226
1366
  getProfile(customerId: string): Promise<Customer>;
1227
1367
  updateProfile(customerId: string, patch: ProfileUpdate): Promise<Customer>;
1228
1368
  listAddresses(customerId: string): Promise<CustomerAddress[]>;
1229
1369
  addAddress(customerId: string, addr: Omit<CustomerAddress, 'id'>): Promise<CustomerAddress>;
1230
1370
  deleteAddress(customerId: string, addressId: string): Promise<void>;
1371
+ /** Appends `note` to the customer's admin notes. */
1372
+ addNote(customerId: string, note: CustomerNote): Promise<void>;
1231
1373
  }
1232
1374
  declare function createCustomerService(deps: {
1233
1375
  repos: Repositories;
@@ -1288,62 +1430,6 @@ interface CreateAuthServiceDeps {
1288
1430
  declare function parseDurationToMs(s: string): number;
1289
1431
  declare function createAuthService(deps: CreateAuthServiceDeps): AuthService;
1290
1432
 
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
1433
  interface ReserveStockResult {
1348
1434
  reservationId: string;
1349
1435
  expiresAt: string;
@@ -1389,8 +1475,11 @@ interface BeginCheckoutResult {
1389
1475
  /** The order's status as the checkout answers. */
1390
1476
  orderStatus: OrderStatus;
1391
1477
  payment: CheckoutPayment;
1392
- /** A fresh key that reads the order with no session (`ORDER_KEY_HEADER`). Only its hash is stored. */
1393
- orderKey: string;
1478
+ /**
1479
+ * A guest order's fresh key, which reads it with no session (`ORDER_KEY_HEADER`) until it expires. Only its hash is
1480
+ * stored. A signed-in customer's order has none: their account is its home.
1481
+ */
1482
+ orderKey?: string;
1394
1483
  }
1395
1484
  /** What the payment provider captured. */
1396
1485
  interface CapturedPayment {
@@ -1434,6 +1523,8 @@ interface CreateCheckoutServiceDeps {
1434
1523
  inventory: InventoryService;
1435
1524
  payments: PaymentsAdapter;
1436
1525
  currency: string;
1526
+ /** How long a checkout's order key opens the order on its own; 48 hours when not given. */
1527
+ keyLifetimeMs?: number;
1437
1528
  }
1438
1529
  declare function createCheckoutService(deps: CreateCheckoutServiceDeps): CheckoutService & ManualPayments;
1439
1530
 
@@ -1486,7 +1577,10 @@ interface Settlement {
1486
1577
  }
1487
1578
  /** The provider's answer settles a refund row as succeeded only when it is for the row's amount and currency. */
1488
1579
  declare function settlementOf(answer: Refund, row: Pick<OrderRefund, 'amountMinor' | 'currency'>): Settlement;
1489
- /** Writes `refunded_minor` as Σ of the order's succeeded refunds. */
1580
+ /**
1581
+ * Writes `refunded_minor` as Σ of the order's succeeded refunds, when that moves it: a refund that moved no money (failed
1582
+ * or still pending) leaves the order row as it was, so it needs no order event. The caller holds the order's lock.
1583
+ */
1490
1584
  declare function refreshRefunded(repos: Repositories, tx: Tx, orderId: string, at: Date): Promise<{
1491
1585
  refunds: OrderRefund[];
1492
1586
  refundedMinor: number;
@@ -1537,6 +1631,8 @@ interface BuildServicesDeps {
1537
1631
  payments: PaymentsAdapter;
1538
1632
  searchAdapter: SearchAdapter;
1539
1633
  email: EmailAdapter;
1634
+ /** The effective JWT secret (`resolveAuthSecret`), not the config's field. */
1635
+ jwtSecret: string;
1540
1636
  }
1541
1637
  declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
1542
1638
 
@@ -1560,6 +1656,8 @@ interface RegisterAllRoutesDeps {
1560
1656
  publisher: EventPublisher;
1561
1657
  /** The slots whose provider packages declare settings, as the store booted with them. */
1562
1658
  settingsSlots: readonly DeclaredSlot[];
1659
+ /** The effective JWT secret (`resolveAuthSecret`), which signs the event-stream ticket as it signs tokens. */
1660
+ jwtSecret: string;
1563
1661
  /** The admin's dist directory, or null for a 404 that says how to build it; undefined serves no admin. */
1564
1662
  adminRoot?: string | null | undefined;
1565
1663
  }
@@ -1629,6 +1727,17 @@ interface CreateAppOptions extends ResolvePrimitivesOptions {
1629
1727
  }
1630
1728
  declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
1631
1729
 
1730
+ interface AuthSecret {
1731
+ secret: string;
1732
+ source: 'config' | 'env' | 'default';
1733
+ }
1734
+ /**
1735
+ * The secret every token is signed with: the config's own, else NYMBAL_JWT_SECRET, else the schema default. Code that
1736
+ * names a secret wins, as it does over the environment for adapter settings. A set variable is checked first, so a
1737
+ * malformed one fails the boot even when the config's secret would win.
1738
+ */
1739
+ declare function resolveAuthSecret(config: NymbalConfig, env: NodeJS.ProcessEnv): AuthSecret;
1740
+
1632
1741
  /**
1633
1742
  * Serves the admin's built files at /admin/ beside /api, one origin, so its relative API URLs and the refresh cookie
1634
1743
  * work without a proxy. `root` is the admin's dist directory, or null when none is installed: then /admin/ answers 404
@@ -1687,31 +1796,50 @@ interface EventRetentionSweeperDeps {
1687
1796
  */
1688
1797
  declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
1689
1798
 
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;
1799
+ /** What the config names for a slot: its provider, and the package the adapter comes from when it says. */
1800
+ interface Choice {
1801
+ provider: string;
1802
+ package?: string | undefined;
1695
1803
  }
1696
- type Packages<P extends ProviderPackage> = Readonly<Record<string, P>>;
1697
1804
  /**
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.
1805
+ * Where a slot's adapter comes from: the one passed to `createApp` (`custom`), the kernel's own (`built-in`), or a
1806
+ * package, named by the config's `package` or by the convention, `@nymbalhq/<slot>-<provider>`.
1701
1807
  */
1702
- declare const PROVIDER_PACKAGES: Readonly<Partial<Record<Exclude<Slot, 'security'>, Packages<Required<ProviderPackage>>>>> & {
1703
- readonly security: Packages<ProviderPackage>;
1808
+ type Resolution = {
1809
+ kind: 'custom';
1810
+ } | {
1811
+ kind: 'built-in';
1812
+ } | {
1813
+ kind: 'package';
1814
+ package: string;
1815
+ sdk?: string;
1816
+ named: 'package' | 'convention';
1704
1817
  };
1818
+ /** The rule every caller shares: `custom`, then a built-in, then `package`, then the convention name. */
1819
+ declare function resolveChoice(slot: Slot, choice: Choice): Resolution;
1705
1820
  /** The command that installs `packages` with the project's package manager, as `packageManager` picks it. */
1706
1821
  declare function installLine(packages: readonly string[], env: NodeJS.ProcessEnv, cwd: string): string;
1707
- type ProviderModule = ProviderPackageModule;
1708
1822
  /**
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.
1823
+ * The package Node could not find, when `error` is a missing package and not some other failure. A path (an installed
1824
+ * package's own missing file) is not a package to install, so it is `null` and the error stays as Node threw it.
1825
+ */
1826
+ declare function missingPackage(error: unknown): string | null;
1827
+ /**
1828
+ * `mod` as the adapter module of `slot` and `provider`, from `pkg`: it must export `createAdapter`, `slot` equal to the
1829
+ * slot and, for any provider but `custom`, `provider` equal to it. A module for another slot is `adapter.wrong_slot`,
1830
+ * anything else wrong `adapter.package_invalid`, each naming the package, the export, the expected and actual value.
1831
+ */
1832
+ declare function checkAdapterModule(mod: unknown, slot: Slot, provider: string, pkg: string): ProviderPackageModule;
1833
+ /**
1834
+ * The adapter module the slot's choice resolves to, imported and checked, or `undefined` for `custom` and a built-in.
1835
+ * The specifier is imported from the project root, `process.cwd()`. A package that is not installed is
1836
+ * `adapter.package_missing` with its install line, or `adapter.provider_unknown` (with a suggestion when one is near)
1837
+ * for a convention name no first-party package has; an adapter that resolves another copy of @nymbalhq/types than the
1838
+ * kernel's is `adapter.types_duplicate`; any other load error is rethrown as it is.
1713
1839
  */
1714
- declare function importProviderPackage(slot: Slot, provider: string, env: NodeJS.ProcessEnv): Promise<ProviderModule | undefined>;
1840
+ declare function importAdapterModule(slot: Slot, choice: Choice, env: NodeJS.ProcessEnv, importer?: (specifier: string) => Promise<unknown>): Promise<ProviderPackageModule | undefined>;
1841
+ /** The fields a provider package lets Settings fill: its `settings` export, or none. */
1842
+ declare function declaredSettings(mod: ProviderPackageModule | undefined): readonly AdapterSetting[];
1715
1843
 
1716
1844
  /**
1717
1845
  * v0.1 security adapter.
@@ -1754,7 +1882,7 @@ declare function createNativeStubPaymentsAdapter(deps: {
1754
1882
  logger: Logger;
1755
1883
  }): PaymentsAdapter;
1756
1884
 
1757
- /** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/adapter-smtp). */
1885
+ /** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/email-smtp). */
1758
1886
  interface NativeEmailAdapterConfig {
1759
1887
  transport?: 'console';
1760
1888
  from?: string;
@@ -1927,6 +2055,8 @@ interface RebuildDeps {
1927
2055
  table: string;
1928
2056
  page: number;
1929
2057
  }) => void | Promise<void>;
2058
+ /** Awaited once every model is collected, before a model is caught up and swapped, and after its swap. */
2059
+ onPhase?: (phase: 'collected' | 'swapped', model: ReadModelName) => void | Promise<void>;
1930
2060
  }
1931
2061
  /** What a rebuilder reads with: the command store in pages, each page a read of its own. */
1932
2062
  interface RebuildContext {
@@ -1977,6 +2107,8 @@ interface RebuildReportEntry {
1977
2107
  name: string;
1978
2108
  documents: number;
1979
2109
  }>;
2110
+ /** Logged events applied to the collected contents before the swap. */
2111
+ caughtUpBeforeSwap: number;
1980
2112
  /** Logged events re-applied after the swap. */
1981
2113
  caughtUpEvents: number;
1982
2114
  /** Catch-up events a handler failed on: the model is swapped all the same. */
@@ -1992,8 +2124,9 @@ declare class RebuildError extends Error {
1992
2124
  constructor(model: ReadModelName, cause: unknown);
1993
2125
  }
1994
2126
  /**
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
2127
+ * Rebuilds `names` from the command store's tables: every model is read first, then each is caught up in memory with
2128
+ * the events delivered since its read began, swapped in (atomically per collection) and caught up again, for the
2129
+ * events delivered while it was swapped. A rebuilder that throws rejects with
1997
2130
  * a `RebuildError` before anything is swapped. Catch-up failures are in the report.
1998
2131
  */
1999
2132
  declare function rebuild(names: readonly ReadModelName[], deps: RebuildDeps): Promise<RebuildReport>;
@@ -2053,5 +2186,5 @@ interface LocalFsMediaStorageOptions {
2053
2186
  declare const LOCAL_FS_MEDIA_CAPABILITIES: readonly string[];
2054
2187
  declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
2055
2188
 
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 };
2189
+ export { CATCH_UP_MARGIN_MS, CSRF_COOKIE, CSRF_HEADER, InMemoryDocumentStore, InProcessEventBus, LOCAL_FS_MEDIA_CAPABILITIES, PROVIDER_REFUND_REASON, READ_MODELS, READ_MODEL_NAMES, REDIS_DEFAULTS, RateLimiter, RebuildError, SECRETS_KEY_ENV, SECRETS_KEY_OLD_ENV, actorOf, appendAuditEntry, audit, auditEntriesInOrder, auditedCommand, buildAdapters, buildRepositories, buildServices, checkAdapterModule, createAlertService, createAlertSubscriptionRepository, createApp, createAuditEntryRepository, createAuthService, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createEmailSuppressionRepository, createEventBuilder, createEventLogRepository, createEventPublisher, createInventoryReservationRepository, createInventoryService, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderAccessKeyRepository, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createOrderShipmentRepository, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRecentlyViewedService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createSettingsRepository, createStockAdjustmentRepository, createVariantRepository, currentActor, currentCorrelationId, declaredSettings, decrypt, diagnose, diffReadModel, emailDelivers, encodeSearchCursor, encrypt, fillFromSettings, findAppliedByKey, importAdapterModule, installLine, isMissingSettingsTable, keyId, keyProblem, listAuditEntries, migrationState, missingPackage, newAlertToken, newCorrelationId, openReadModels, orderPayment, parseDurationToMs, rawClients, readSecretsKey, rebuild, refreshRefunded, registerAdminStaticRoute, registerAlertHandler, registerAlertRoutes, registerAllRoutes, registerHandlers, resolveAuthSecret, resolveChoice, resolvePrimitives, routeSchemas, runAsActor, runMigrations, runSeed, runWithCorrelation, scrub, seedCategories, seedProducts, settingAad, settlementOf, sqliteFile, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, withIdempotency };
2190
+ export type { AbandonedCart, AbandonedWindow, Actor, AdapterRegistry, AlertConfirmed, AlertService, AlertSubscribeInput, AlertSubscription, AlertSubscriptionPatch, AlertSubscriptionRepository, AlertSubscriptionRequest, AppliedEntry, AttachHttpOptions, AuditCursor, AuditEntryInsert, AuditEntryRepository, AuditFilter, AuditQuery, AuthSecret, AuthService, AuthTokens, BeginCheckoutInput, BeginCheckoutResult, BuildAdaptersDeps, BuildServicesDeps, CapabilitiesReport, CapabilitySlot, CapturedPayment, CartRepository, CartService, CatchUpFailure, CategoryCreateInput, CategoryInsert, CategoryRepository, CategoryService, CategoryUpdate, CategoryUpdateInput, CheckoutService, Choice, CollectionDiff, CommandStore, CommandStoreOptions, CommerceAdapters, CreateAlertServiceDeps, CreateAppOptions, CreateAuthServiceDeps, CreateCartServiceDeps, CreateCheckoutServiceDeps, CreateInventoryServiceDeps, CreateLoggerOptions, CreateOrderServiceDeps, CreatePlatformOptions, CreateProductServiceDeps, CreatePublisherOptions, CreateRefundServiceDeps, CreateRelayOptions, CustomerInsert, CustomerJwtPayload, CustomerNote, CustomerRepository, CustomerService, CustomerUpdate, CustomerWithHash, DiagnoseOptions, DiagnosisCheck, DiagnosisReport, DiagnosisStatus, EmailSuppressionInput, EmailSuppressionReason, EmailSuppressionRepository, EncryptedValue, EventArchiveWriter, EventBuilderContext, EventLogFilter, EventLogRepository, EventPublisher, EventRetentionSweeperDeps, FinalizeResult, IdempotencyOptions, ImportCustomerInput, InMemoryDocumentStoreOptions, InProcessEventBusOptions, InjectedAdapters, InventoryReservationRepository, InventoryService, KeysetPage, CategoryInsert$1 as LegacyCategoryInsert, CategoryRow as LegacyCategoryRow, ProductInsert$1 as LegacyProductInsert, ProductRow as LegacyProductRow, LocalFsMediaStorageOptions, LoggedEvent, MakeEventOptions, ManualPayments, MigrateOptions, MigrationState, NativeEmailAdapterConfig, NymbalApp, OpenReadModelsOptions, OrderAccessKeyInsert, OrderAccessKeyPurpose, OrderAccessKeyRepository, OrderCapture, OrderCreateDraftInput, OrderHistoryInsert, OrderHistoryRepository, OrderImportInput, OrderInsert, OrderKeyState, OrderRefundInsert, OrderRefundRepository, OrderRepository, OrderSequenceRepository, OrderService, OrderShipmentInput, OrderShipmentRepository, Platform, PlatformConnectionOptions, PostgresClient, Primitives, ProcessedEventRepository, ProductCategoryRepository, ProductCreateInput, ProductInsert, ProductRepository, ProductService, ProductUpdate, ProductUpdateInput, ProfileUpdate, PublishOptions, RawClients, ReadModel, ReadModelDiff, ReadModelName, ReadTx, RebuildDeps, RebuildReport, RebuildReportEntry, RecentlyViewedService, RecentlyViewedServiceDeps, RefreshTokenInsert, RefreshTokenRepository, RefreshTokenRow, RefundInput, RefundResult, RefundService, RegisterAlertHandlerDeps, RegisterAlertRoutesDeps, RegisterAllRoutesDeps, RegisterHandlersDeps, RegisterInput, Relay, Repositories, ReservationInsert, ReserveStockResult, Resolution, ResolvePrimitivesOptions, ReviewInsert, ReviewKey, ReviewRepository, RouteSchema, SearchService, SecretsKey, SeedCategory, SeedDeps, SeedProduct, SeedResult, ServiceRegistry, SettingRow, SettingSource, SettingValue, SettingsRepository, Settlement, SlotCapabilities, SqliteClient, StockAdjustmentInsert, StockAdjustmentRepository, StoreRepository, StoredCipher, SweeperHandle, Tx, VariantInsert, VariantPriceInput, VariantRepository, VariantUpdate };