@nymbalhq/platform 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/chunk-UBEGSSFI.js +5332 -0
- package/dist/chunk-UBEGSSFI.js.map +1 -0
- package/dist/{chunk-PW6ILJF7.js → chunk-XVUH34US.js} +138 -10
- package/dist/chunk-XVUH34US.js.map +1 -0
- package/dist/db/schema/index.d.ts +3717 -2105
- package/dist/db/schema/index.js +1 -2
- package/dist/index.d.ts +499 -44
- package/dist/index.js +2227 -1888
- package/dist/index.js.map +1 -1
- package/dist/register-NHG3TIRQ.js +8 -0
- package/migrations/postgres/0007_native_search.sql +12 -0
- package/migrations/postgres/0008_event_correlation.sql +6 -0
- package/migrations/postgres/0009_settings.sql +13 -0
- package/migrations/postgres/0010_catch_up_index.sql +2 -0
- package/migrations/postgres/0011_audit_entries.sql +27 -0
- package/migrations/postgres/meta/0007_snapshot.json +1598 -0
- package/migrations/postgres/meta/0008_snapshot.json +1625 -0
- package/migrations/postgres/meta/0009_snapshot.json +1705 -0
- package/migrations/postgres/meta/0010_snapshot.json +1732 -0
- package/migrations/postgres/meta/0011_snapshot.json +1887 -0
- package/migrations/postgres/meta/_journal.json +35 -0
- package/migrations/sqlite/0007_native_search.sql +39 -0
- package/migrations/sqlite/0008_event_correlation.sql +7 -0
- package/migrations/sqlite/0009_settings.sql +13 -0
- package/migrations/sqlite/0010_catch_up_index.sql +2 -0
- package/migrations/sqlite/0011_audit_entries.sql +26 -0
- package/migrations/sqlite/meta/0007_snapshot.json +1470 -0
- package/migrations/sqlite/meta/0008_snapshot.json +1485 -0
- package/migrations/sqlite/meta/0009_snapshot.json +1571 -0
- package/migrations/sqlite/meta/0010_snapshot.json +1580 -0
- package/migrations/sqlite/meta/0011_snapshot.json +1705 -0
- package/migrations/sqlite/meta/_journal.json +35 -0
- package/package.json +45 -17
- package/recipes/postgres.json +17 -0
- package/dist/chunk-74KODSYJ.js +0 -2564
- package/dist/chunk-74KODSYJ.js.map +0 -1
- package/dist/chunk-PW6ILJF7.js.map +0 -1
- package/dist/chunk-PZ5AY32C.js +0 -10
- package/dist/register-IVFYBJSX.js +0 -8
- package/dist/register-IVFYBJSX.js.map +0 -1
- /package/dist/{chunk-PZ5AY32C.js.map → register-NHG3TIRQ.js.map} +0 -0
package/dist/index.d.ts
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
import { NymbalConfig } from '@nymbalhq/config';
|
|
2
|
-
import { Logger, DocumentStoreAdapter, EventBusAdapter, 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, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap,
|
|
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';
|
|
3
|
+
export { MediaStorage, buildSecurityHeaders, isValidCorrelationId } from '@nymbalhq/types';
|
|
3
4
|
import BetterSqlite3 from 'better-sqlite3';
|
|
4
5
|
import pg from 'pg';
|
|
5
6
|
import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
|
|
6
7
|
import { NodePgDatabase } from 'drizzle-orm/node-postgres';
|
|
7
|
-
import {
|
|
8
|
+
import { sqliteSchema, postgresSchema } from './db/schema/index.js';
|
|
8
9
|
import { JWTPayload } from 'jose';
|
|
9
10
|
import { ZodTypeAny } from 'zod';
|
|
11
|
+
import { DestinationStream } from 'pino';
|
|
10
12
|
import 'drizzle-orm/sqlite-core';
|
|
11
13
|
import 'drizzle-orm/pg-core';
|
|
12
14
|
|
|
@@ -54,9 +56,16 @@ type RawClients = {
|
|
|
54
56
|
interface CommandStoreOptions {
|
|
55
57
|
sqlitePath?: string;
|
|
56
58
|
postgresUrl?: string;
|
|
59
|
+
/**
|
|
60
|
+
* For a caller that must change nothing: SQLite opens `readonly` on a file that must already exist, with no pragma
|
|
61
|
+
* (`journal_mode = WAL` rewrites a rollback-mode file's header); Postgres runs every transaction read-only.
|
|
62
|
+
*/
|
|
63
|
+
readOnly?: boolean;
|
|
57
64
|
}
|
|
58
65
|
/** For migrations, seeding and tests only; no repository or service imports it. */
|
|
59
66
|
declare function rawClients(store: CommandStore): RawClients;
|
|
67
|
+
/** The SQLite file a store opens: `sqlitePath`, else `NYMBAL_SQLITE_PATH`, else `./nymbal.db`. */
|
|
68
|
+
declare function sqliteFile(options?: CommandStoreOptions): string;
|
|
60
69
|
declare function createCommandStore(config: NymbalConfig, options?: CommandStoreOptions): CommandStore;
|
|
61
70
|
|
|
62
71
|
interface Platform {
|
|
@@ -64,15 +73,41 @@ interface Platform {
|
|
|
64
73
|
commandStore: CommandStore;
|
|
65
74
|
documentStore: DocumentStoreAdapter;
|
|
66
75
|
eventBus: EventBusAdapter;
|
|
76
|
+
media: MediaStorage;
|
|
67
77
|
logger: Logger;
|
|
68
78
|
close(): Promise<void>;
|
|
69
79
|
}
|
|
70
|
-
|
|
80
|
+
/** Where the command store is, and the logger; what `createApp` and `resolvePrimitives` take as well. */
|
|
81
|
+
interface PlatformConnectionOptions {
|
|
71
82
|
logger?: Logger;
|
|
72
83
|
sqlitePath?: string;
|
|
73
84
|
postgresUrl?: string;
|
|
74
85
|
}
|
|
75
|
-
|
|
86
|
+
/** The infrastructure primitives, as instances: `resolvePrimitives` builds them from the config. */
|
|
87
|
+
interface Primitives {
|
|
88
|
+
documentStore: DocumentStoreAdapter;
|
|
89
|
+
eventBus: EventBusAdapter;
|
|
90
|
+
media: MediaStorage;
|
|
91
|
+
}
|
|
92
|
+
interface CreatePlatformOptions extends PlatformConnectionOptions, Primitives {
|
|
93
|
+
}
|
|
94
|
+
interface ResolvePrimitivesOptions extends PlatformConnectionOptions {
|
|
95
|
+
/** Where local-fs media is written; `public/imported-media` under the working directory by default. */
|
|
96
|
+
mediaRoot?: string;
|
|
97
|
+
env?: NodeJS.ProcessEnv;
|
|
98
|
+
}
|
|
99
|
+
declare const REDIS_DEFAULTS: {
|
|
100
|
+
readonly prefix: "nymbal";
|
|
101
|
+
readonly ackTimeoutMs: 15000;
|
|
102
|
+
readonly claimIdleMs: 5000;
|
|
103
|
+
readonly streamMaxLen: 10000;
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
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.
|
|
108
|
+
*/
|
|
109
|
+
declare function resolvePrimitives(config: NymbalConfig, options?: ResolvePrimitivesOptions): Promise<Primitives>;
|
|
110
|
+
declare function createPlatform(config: NymbalConfig, options: CreatePlatformOptions): Platform;
|
|
76
111
|
|
|
77
112
|
interface MigrateOptions {
|
|
78
113
|
migrationsRoot?: string;
|
|
@@ -138,6 +173,12 @@ declare function createCategoryRepository$1(store: CommandStore): {
|
|
|
138
173
|
insertMany(items: CategoryInsert$1[]): Promise<void>;
|
|
139
174
|
};
|
|
140
175
|
|
|
176
|
+
/** One page of a walk over a table by primary key: the rows whose id is above `after`, at most `limit` of them. */
|
|
177
|
+
interface KeysetPage {
|
|
178
|
+
after?: string;
|
|
179
|
+
limit: number;
|
|
180
|
+
}
|
|
181
|
+
|
|
141
182
|
interface ProductInsert {
|
|
142
183
|
id: string;
|
|
143
184
|
slug: string;
|
|
@@ -173,6 +214,8 @@ interface ProductRepository extends StoreRepository {
|
|
|
173
214
|
limit?: number;
|
|
174
215
|
offset?: number;
|
|
175
216
|
}): Promise<Product[]>;
|
|
217
|
+
/** Rows by id after `page.after`: a walk over the table that a concurrent write cannot make skip a row. */
|
|
218
|
+
listPage(tx: ReadTx, page: KeysetPage): Promise<Product[]>;
|
|
176
219
|
insert(tx: Tx, p: ProductInsert): Promise<void>;
|
|
177
220
|
update(tx: Tx, id: string, patch: ProductUpdate): Promise<void>;
|
|
178
221
|
delete(tx: Tx, id: string): Promise<void>;
|
|
@@ -240,6 +283,8 @@ interface CategoryRepository extends StoreRepository {
|
|
|
240
283
|
findById(tx: ReadTx, id: string): Promise<Category | null>;
|
|
241
284
|
findBySlug(tx: ReadTx, slug: string): Promise<Category | null>;
|
|
242
285
|
list(tx: ReadTx): Promise<Category[]>;
|
|
286
|
+
/** Rows by id after `page.after`: a walk over the table that a concurrent write cannot make skip a row. */
|
|
287
|
+
listPage(tx: ReadTx, page: KeysetPage): Promise<Category[]>;
|
|
243
288
|
insert(tx: Tx, c: CategoryInsert): Promise<void>;
|
|
244
289
|
update(tx: Tx, id: string, patch: CategoryUpdate): Promise<void>;
|
|
245
290
|
delete(tx: Tx, id: string): Promise<void>;
|
|
@@ -292,6 +337,8 @@ interface CustomerRepository extends StoreRepository {
|
|
|
292
337
|
limit?: number;
|
|
293
338
|
offset?: number;
|
|
294
339
|
}): Promise<CustomerWithHash[]>;
|
|
340
|
+
/** Rows by id after `page.after`: a walk over the table that a concurrent write cannot make skip a row. */
|
|
341
|
+
listPage(tx: ReadTx, page: KeysetPage): Promise<CustomerWithHash[]>;
|
|
295
342
|
insert(tx: Tx, c: CustomerInsert): Promise<void>;
|
|
296
343
|
update(tx: Tx, id: string, patch: CustomerUpdate): Promise<void>;
|
|
297
344
|
incrementStats(tx: Tx, id: string, deltaOrders: number, deltaSpentMinor: number, updatedAt: Date): Promise<void>;
|
|
@@ -375,6 +422,8 @@ interface OrderRepository extends StoreRepository {
|
|
|
375
422
|
limit?: number;
|
|
376
423
|
offset?: number;
|
|
377
424
|
}): Promise<Order[]>;
|
|
425
|
+
/** Rows by id after `page.after`: a walk over the table that a concurrent write cannot make skip a row. */
|
|
426
|
+
listPage(tx: ReadTx, page: KeysetPage): Promise<Order[]>;
|
|
378
427
|
insert(tx: Tx, o: OrderInsert): Promise<void>;
|
|
379
428
|
setStatus(tx: Tx, id: string, status: OrderStatus, updatedAt: Date): Promise<void>;
|
|
380
429
|
/** Sets `status` only while the order is still `from`; false when it was not, so a concurrent writer got there
|
|
@@ -484,9 +533,15 @@ interface ReviewInsert {
|
|
|
484
533
|
moderationStatus?: ReviewModerationStatus;
|
|
485
534
|
submittedAt: Date;
|
|
486
535
|
}
|
|
536
|
+
/** Where a page of a product's reviews starts: after this review, in the newest-first, then id-descending order. */
|
|
537
|
+
interface ReviewKey {
|
|
538
|
+
submittedAt: string;
|
|
539
|
+
id: string;
|
|
540
|
+
}
|
|
487
541
|
interface ReviewRepository extends StoreRepository {
|
|
488
542
|
findById(tx: ReadTx, id: string): Promise<Review | null>;
|
|
489
|
-
|
|
543
|
+
/** Newest first, ties by id descending; `after` is the last review of the previous page. */
|
|
544
|
+
listByProduct(tx: ReadTx, productId: string, status?: ReviewModerationStatus, limit?: number, after?: ReviewKey): Promise<Review[]>;
|
|
490
545
|
listByStatus(tx: ReadTx, status: ReviewModerationStatus, limit?: number): Promise<Review[]>;
|
|
491
546
|
insert(tx: Tx, r: ReviewInsert): Promise<void>;
|
|
492
547
|
setModerationStatus(tx: Tx, id: string, status: ReviewModerationStatus, moderatedBy: string, moderatedAt: Date): Promise<void>;
|
|
@@ -514,6 +569,17 @@ interface LoggedEvent {
|
|
|
514
569
|
deliveredAt: Date | null;
|
|
515
570
|
attempts: number;
|
|
516
571
|
deadAt: Date | null;
|
|
572
|
+
createdAt: Date;
|
|
573
|
+
}
|
|
574
|
+
/** Filters for reading the log. A type glob's `*` matches any run of characters, dots included (`order.*`). */
|
|
575
|
+
interface EventLogFilter {
|
|
576
|
+
/** Type globs; an event matches when its type matches any of them. */
|
|
577
|
+
types?: string[];
|
|
578
|
+
/** Appended at or after. */
|
|
579
|
+
since?: Date;
|
|
580
|
+
/** Appended before. */
|
|
581
|
+
until?: Date;
|
|
582
|
+
limit: number;
|
|
517
583
|
}
|
|
518
584
|
interface EventLogRepository extends StoreRepository {
|
|
519
585
|
/** Appends in array order, so `seq` follows publish order. */
|
|
@@ -526,6 +592,24 @@ interface EventLogRepository extends StoreRepository {
|
|
|
526
592
|
/** Deletes delivered events delivered before `at`; returns how many. Undelivered and dead events are never deleted. */
|
|
527
593
|
deleteDeliveredBefore(tx: Tx, at: Date): Promise<number>;
|
|
528
594
|
listAll(tx: ReadTx): Promise<LoggedEvent[]>;
|
|
595
|
+
/** One correlation id's events, by `seq`. */
|
|
596
|
+
queryByCorrelation(tx: ReadTx, correlationId: string, filter: EventLogFilter): Promise<LoggedEvent[]>;
|
|
597
|
+
/** Events above `seq`, by `seq`. */
|
|
598
|
+
listAfter(tx: ReadTx, seq: number, filter: Pick<EventLogFilter, 'types' | 'limit'>): Promise<LoggedEvent[]>;
|
|
599
|
+
/** The highest `seq` in the log, or 0 when it is empty. */
|
|
600
|
+
maxSeq(tx: ReadTx): Promise<number>;
|
|
601
|
+
/**
|
|
602
|
+
* What a read-model rebuild re-applies after its swap: every event that is not dead and was delivered at or after
|
|
603
|
+
* `since`, or not yet delivered, by `seq`. `afterSeq` and `limit` page through them.
|
|
604
|
+
*/
|
|
605
|
+
listForCatchUp(tx: ReadTx, since: Date, page?: {
|
|
606
|
+
afterSeq?: number;
|
|
607
|
+
limit?: number;
|
|
608
|
+
}): Promise<LoggedEvent[]>;
|
|
609
|
+
/** Delivered events delivered before `at`, by `seq`: what retention may archive. Undelivered and dead events never are. */
|
|
610
|
+
listDeliveredBefore(tx: ReadTx, at: Date, limit: number): Promise<LoggedEvent[]>;
|
|
611
|
+
/** Deletes the delivered events with these `seq`s; returns how many. */
|
|
612
|
+
deleteSeqs(tx: Tx, seqs: number[]): Promise<number>;
|
|
529
613
|
}
|
|
530
614
|
declare function createEventLogRepository(store: CommandStore): EventLogRepository;
|
|
531
615
|
|
|
@@ -570,6 +654,91 @@ interface CartRepository extends StoreRepository {
|
|
|
570
654
|
}
|
|
571
655
|
declare function createCartRepository(store: CommandStore): CartRepository;
|
|
572
656
|
|
|
657
|
+
/** A row of `settings`: a secret's ciphertext with its IV, tag and key id, or a non-secret's `plain` value. */
|
|
658
|
+
interface SettingRow {
|
|
659
|
+
slot: string;
|
|
660
|
+
path: string;
|
|
661
|
+
ciphertext: Buffer | null;
|
|
662
|
+
plain: string | null;
|
|
663
|
+
iv: Buffer | null;
|
|
664
|
+
tag: Buffer | null;
|
|
665
|
+
keyId: string | null;
|
|
666
|
+
updatedAt: Date;
|
|
667
|
+
updatedBy: string | null;
|
|
668
|
+
}
|
|
669
|
+
interface SettingsRepository extends StoreRepository {
|
|
670
|
+
list(tx: ReadTx): Promise<SettingRow[]>;
|
|
671
|
+
get(tx: ReadTx, slot: string, path: string): Promise<SettingRow | undefined>;
|
|
672
|
+
/** Inserts the row, or replaces the one at its slot and path. */
|
|
673
|
+
put(tx: Tx, row: SettingRow): Promise<void>;
|
|
674
|
+
/** Whether a row was there to delete. */
|
|
675
|
+
delete(tx: Tx, slot: string, path: string): Promise<boolean>;
|
|
676
|
+
/** Every row, or those of one slot, or one path of it; how many went. */
|
|
677
|
+
clear(tx: Tx, filter?: {
|
|
678
|
+
slot?: string;
|
|
679
|
+
path?: string;
|
|
680
|
+
}): Promise<number>;
|
|
681
|
+
}
|
|
682
|
+
declare function createSettingsRepository(store: CommandStore): SettingsRepository;
|
|
683
|
+
|
|
684
|
+
interface AuditEntryInsert {
|
|
685
|
+
id: string;
|
|
686
|
+
at: Date;
|
|
687
|
+
actor: AuditActor;
|
|
688
|
+
command: string;
|
|
689
|
+
subjects: AuditSubject[];
|
|
690
|
+
correlationId: string | null;
|
|
691
|
+
idempotencyKey: string | null;
|
|
692
|
+
requestHash: string | null;
|
|
693
|
+
outcome: AuditOutcome;
|
|
694
|
+
responseStatus: number | null;
|
|
695
|
+
/** Kept only on a keyed `applied` row, to answer its replays. */
|
|
696
|
+
responseBody: unknown;
|
|
697
|
+
}
|
|
698
|
+
/** A keyed `applied` row: what its replays answer. */
|
|
699
|
+
interface AppliedEntry {
|
|
700
|
+
requestHash: string | null;
|
|
701
|
+
subjects: AuditSubject[];
|
|
702
|
+
responseStatus: number;
|
|
703
|
+
responseBody: unknown;
|
|
704
|
+
}
|
|
705
|
+
/** A position in the (at, id) order the entries are listed in. */
|
|
706
|
+
interface AuditCursor {
|
|
707
|
+
at: string;
|
|
708
|
+
id: string;
|
|
709
|
+
}
|
|
710
|
+
interface AuditQuery {
|
|
711
|
+
/** `kind:id`, a kind alone, or an actor id. */
|
|
712
|
+
actor?: string;
|
|
713
|
+
command?: string;
|
|
714
|
+
/** A subject's id. */
|
|
715
|
+
subject?: string;
|
|
716
|
+
correlation?: string;
|
|
717
|
+
outcome?: AuditOutcome;
|
|
718
|
+
/** From `since` inclusive to `until` exclusive. */
|
|
719
|
+
since?: Date;
|
|
720
|
+
until?: Date;
|
|
721
|
+
/** `desc`: newest first, the entries before `cursor`; `asc`: oldest first, the entries after it. */
|
|
722
|
+
order: 'asc' | 'desc';
|
|
723
|
+
cursor?: AuditCursor;
|
|
724
|
+
limit: number;
|
|
725
|
+
}
|
|
726
|
+
/** Appends one entry in `tx`. Entries are never updated or deleted (the tables' triggers refuse it). */
|
|
727
|
+
declare function appendAuditEntry(tx: Tx, e: AuditEntryInsert): Promise<void>;
|
|
728
|
+
/** The `applied` entry `actorId` made of `command` under `key`, if any. */
|
|
729
|
+
declare function findAppliedByKey(tx: ReadTx, actorId: string, command: string, key: string): Promise<AppliedEntry | null>;
|
|
730
|
+
/** Entries matching `q`, in its order, at most `q.limit`; never a stored response body. */
|
|
731
|
+
declare function listAuditEntries(tx: ReadTx, q: AuditQuery): Promise<AuditEntry[]>;
|
|
732
|
+
type AuditFilter = Omit<AuditQuery, 'order' | 'cursor' | 'limit'>;
|
|
733
|
+
/** Every entry matching `filter`, oldest first, one read per page: what both exports print, a line each. */
|
|
734
|
+
declare function auditEntriesInOrder(store: CommandStore, filter: AuditFilter, pageSize?: number): AsyncGenerator<AuditEntry>;
|
|
735
|
+
interface AuditEntryRepository extends StoreRepository {
|
|
736
|
+
append(tx: Tx, entry: AuditEntryInsert): Promise<void>;
|
|
737
|
+
findAppliedByKey(tx: ReadTx, actorId: string, command: string, key: string): Promise<AppliedEntry | null>;
|
|
738
|
+
list(tx: ReadTx, query: AuditQuery): Promise<AuditEntry[]>;
|
|
739
|
+
}
|
|
740
|
+
declare function createAuditEntryRepository(store: CommandStore): AuditEntryRepository;
|
|
741
|
+
|
|
573
742
|
interface Repositories {
|
|
574
743
|
product: ProductRepository;
|
|
575
744
|
variant: VariantRepository;
|
|
@@ -587,6 +756,8 @@ interface Repositories {
|
|
|
587
756
|
processedEvent: ProcessedEventRepository;
|
|
588
757
|
eventLog: EventLogRepository;
|
|
589
758
|
cart: CartRepository;
|
|
759
|
+
settings: SettingsRepository;
|
|
760
|
+
auditEntry: AuditEntryRepository;
|
|
590
761
|
}
|
|
591
762
|
declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
|
|
592
763
|
|
|
@@ -598,17 +769,19 @@ declare class InMemoryDocumentStore implements DocumentStoreAdapter {
|
|
|
598
769
|
#private;
|
|
599
770
|
constructor(options?: InMemoryDocumentStoreOptions);
|
|
600
771
|
capabilities(): readonly string[];
|
|
772
|
+
/** The process's own memory: healthy whenever it can answer. */
|
|
773
|
+
healthCheck(): Promise<HealthReport>;
|
|
601
774
|
get<T>(collection: string, key: string): Promise<T | null>;
|
|
602
775
|
put<T>(collection: string, key: string, document: T, options?: PutOptions): Promise<void>;
|
|
603
776
|
delete(collection: string, key: string): Promise<void>;
|
|
604
777
|
query<T>(collection: string, params: QueryParams): Promise<QueryResult<T>>;
|
|
605
778
|
batchGet<T>(collection: string, keys: string[]): Promise<Map<string, T>>;
|
|
606
779
|
batchPut<T>(collection: string, items: Map<string, T>): Promise<void>;
|
|
780
|
+
/** Builds the new contents in a map of their own and swaps it in, so a reader sees one set or the other. */
|
|
781
|
+
replaceCollection<T>(collection: string, entries: AsyncIterable<[string, T]>): Promise<void>;
|
|
607
782
|
close(): Promise<void>;
|
|
608
783
|
}
|
|
609
784
|
|
|
610
|
-
declare function createDocumentStore(config: NymbalConfig): DocumentStoreAdapter;
|
|
611
|
-
|
|
612
785
|
interface InProcessEventBusOptions {
|
|
613
786
|
logger?: Logger;
|
|
614
787
|
}
|
|
@@ -616,6 +789,8 @@ declare class InProcessEventBus implements EventBusAdapter {
|
|
|
616
789
|
#private;
|
|
617
790
|
constructor(options?: InProcessEventBusOptions);
|
|
618
791
|
capabilities(): readonly string[];
|
|
792
|
+
/** Delivery within the process: healthy whenever it can answer. */
|
|
793
|
+
healthCheck(): Promise<HealthReport>;
|
|
619
794
|
publish<T>(event: NymbalEvent<T>): Promise<void>;
|
|
620
795
|
publishBatch(events: NymbalEvent<unknown>[]): Promise<void>;
|
|
621
796
|
replay(events: NymbalEvent<unknown>[]): Promise<void>;
|
|
@@ -624,8 +799,6 @@ declare class InProcessEventBus implements EventBusAdapter {
|
|
|
624
799
|
close(): Promise<void>;
|
|
625
800
|
}
|
|
626
801
|
|
|
627
|
-
declare function createEventBus(config: NymbalConfig, logger?: Logger): EventBusAdapter;
|
|
628
|
-
|
|
629
802
|
interface EventBuilderContext {
|
|
630
803
|
storeId: string;
|
|
631
804
|
environment: NymbalEnvironment;
|
|
@@ -648,6 +821,12 @@ interface Relay {
|
|
|
648
821
|
/** Stops the interval and starts no new pass; resolves when the pass in flight, if any, has finished, so the
|
|
649
822
|
* store can be closed without cutting a delivery off between the handler and its bookkeeping. */
|
|
650
823
|
stop(): Promise<void>;
|
|
824
|
+
/**
|
|
825
|
+
* `handler`, run as part of a delivery: a drain it asks for (by running a command) returns at once instead of
|
|
826
|
+
* waiting on the pass that waits on it. The app wraps every subscribed handler in it, so this holds whether the bus
|
|
827
|
+
* calls the handler inside `publish` or from a consumer loop of its own.
|
|
828
|
+
*/
|
|
829
|
+
asDelivery(handler: EventHandler): EventHandler;
|
|
651
830
|
}
|
|
652
831
|
interface CreateRelayOptions {
|
|
653
832
|
store: CommandStore;
|
|
@@ -684,23 +863,53 @@ interface CreatePublisherOptions {
|
|
|
684
863
|
}
|
|
685
864
|
declare function createEventPublisher(opts: CreatePublisherOptions): EventPublisher;
|
|
686
865
|
|
|
866
|
+
/** Runs `fn` with `id` as the correlation id of every event it publishes, across its awaits, and returns its result. */
|
|
867
|
+
declare function runWithCorrelation<T>(id: string, fn: () => T): T;
|
|
868
|
+
declare function currentCorrelationId(): string | undefined;
|
|
869
|
+
/** A fresh id for one run of work that starts outside HTTP (a sweep, an import): `<origin>:<uuidv7>`. */
|
|
870
|
+
declare function newCorrelationId(origin: string): string;
|
|
871
|
+
|
|
872
|
+
type Actor = AuditActor;
|
|
873
|
+
/** Runs `fn` as `actor`, across its awaits, and returns its result. */
|
|
874
|
+
declare function runAsActor<T>(actor: Actor, fn: () => T): T;
|
|
875
|
+
declare function currentActor(): Actor | undefined;
|
|
876
|
+
/** A request's actor from its principal. A guest is anonymous: a cart's token is a credential, never an id. */
|
|
877
|
+
declare function actorOf(auth: RequestAuth | undefined): Actor;
|
|
878
|
+
|
|
879
|
+
declare const audit: {
|
|
880
|
+
/**
|
|
881
|
+
* A service names the command it runs and the records it touches. It writes nothing itself: the open command's
|
|
882
|
+
* entry carries them. Call it before the command can refuse, so a refusal is recorded as the command's.
|
|
883
|
+
*/
|
|
884
|
+
note(command: string, subjects?: readonly AuditSubject[]): void;
|
|
885
|
+
};
|
|
886
|
+
/**
|
|
887
|
+
* Runs `fn` as one command, `command` (or, when undefined, the first command a service notes). Inside an open command
|
|
888
|
+
* it joins that one. A refusal thrown out of `fn` is recorded as the command's `refused` entry.
|
|
889
|
+
*/
|
|
890
|
+
declare function auditedCommand<T>(store: CommandStore, command: string | undefined, fn: () => Promise<T>): Promise<T>;
|
|
891
|
+
|
|
687
892
|
interface IdempotencyOptions {
|
|
688
893
|
repo: ProcessedEventRepository;
|
|
689
894
|
logger?: Logger;
|
|
690
895
|
}
|
|
691
896
|
declare function withIdempotency<T = unknown>(handlerName: string, handler: EventHandler<T>, { repo, logger }: IdempotencyOptions): EventHandler<T>;
|
|
692
897
|
|
|
693
|
-
/**
|
|
694
|
-
interface
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
search: SearchAdapter;
|
|
699
|
-
analytics: AnalyticsAdapter;
|
|
700
|
-
shipping: ShippingAdapter;
|
|
701
|
-
tax: TaxAdapter;
|
|
702
|
-
ai: AiAdapter;
|
|
898
|
+
/** A settings row as the fill uses it: decrypted, or a non-secret's plain value. */
|
|
899
|
+
interface SettingValue {
|
|
900
|
+
slot: string;
|
|
901
|
+
path: string;
|
|
902
|
+
value: string;
|
|
703
903
|
}
|
|
904
|
+
type SettingSource = 'config' | 'env' | 'settings';
|
|
905
|
+
/**
|
|
906
|
+
* The slot's config block with each declared path resolved as block, then its declared env, then this slot's row
|
|
907
|
+
* (the deploy always wins). Nothing undeclared is added and `block` is not changed.
|
|
908
|
+
*/
|
|
909
|
+
declare function fillFromSettings(slot: string, block: Record<string, unknown>, declared: readonly AdapterSetting[], rows: readonly SettingValue[], env: NodeJS.ProcessEnv): Record<string, unknown>;
|
|
910
|
+
|
|
911
|
+
/** One adapter per commerce slot. */
|
|
912
|
+
type CommerceAdapters = CommerceSlotAdapters;
|
|
704
913
|
/** Adapters a project hands `createApp`, each for a slot whose provider is `custom`. */
|
|
705
914
|
type InjectedAdapters = Partial<CommerceAdapters>;
|
|
706
915
|
interface AdapterRegistry extends Omit<CommerceAdapters, 'ai'> {
|
|
@@ -711,11 +920,16 @@ interface AdapterRegistry extends Omit<CommerceAdapters, 'ai'> {
|
|
|
711
920
|
interface BuildAdaptersDeps {
|
|
712
921
|
config: NymbalConfig;
|
|
713
922
|
logger: Logger;
|
|
714
|
-
|
|
923
|
+
/** The command store's own connection: the native search index lives in its database. */
|
|
924
|
+
sql: RawClients;
|
|
715
925
|
repos: Repositories;
|
|
716
926
|
injected?: InjectedAdapters;
|
|
717
927
|
/** The payments adapter `createApp` resolved before it opened the store. */
|
|
718
928
|
payments: PaymentsAdapter;
|
|
929
|
+
/** The security adapter `createApp` resolved before it opened the store. */
|
|
930
|
+
security: SecurityAdapter;
|
|
931
|
+
/** The values Settings hold for the slots' declared fields, decrypted: what fills what the config leaves unset. */
|
|
932
|
+
settings?: readonly SettingValue[];
|
|
719
933
|
}
|
|
720
934
|
declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
|
|
721
935
|
|
|
@@ -1109,6 +1323,15 @@ interface BuildServicesDeps {
|
|
|
1109
1323
|
}
|
|
1110
1324
|
declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
|
|
1111
1325
|
|
|
1326
|
+
/** A slot whose provider package declares settings. */
|
|
1327
|
+
interface DeclaredSlot {
|
|
1328
|
+
slot: CommerceSlot;
|
|
1329
|
+
provider: string;
|
|
1330
|
+
declared: readonly AdapterSetting[];
|
|
1331
|
+
}
|
|
1332
|
+
/** A store from before migration 0008 has no `settings` relation: it holds no settings. */
|
|
1333
|
+
declare function isMissingSettingsTable(error: unknown): boolean;
|
|
1334
|
+
|
|
1112
1335
|
interface RegisterAllRoutesDeps {
|
|
1113
1336
|
config: NymbalConfig;
|
|
1114
1337
|
adapter: HttpAdapter;
|
|
@@ -1118,6 +1341,8 @@ interface RegisterAllRoutesDeps {
|
|
|
1118
1341
|
documentStore: DocumentStoreAdapter;
|
|
1119
1342
|
eventBus: EventBusAdapter;
|
|
1120
1343
|
publisher: EventPublisher;
|
|
1344
|
+
/** The slots whose provider packages declare settings, as the store booted with them. */
|
|
1345
|
+
settingsSlots: readonly DeclaredSlot[];
|
|
1121
1346
|
/** The admin's dist directory, or null for a 404 that says how to build it; undefined serves no admin. */
|
|
1122
1347
|
adminRoot?: string | null | undefined;
|
|
1123
1348
|
}
|
|
@@ -1134,6 +1359,16 @@ interface RouteSchema {
|
|
|
1134
1359
|
params?: ZodTypeAny;
|
|
1135
1360
|
query?: ZodTypeAny;
|
|
1136
1361
|
body?: ZodTypeAny;
|
|
1362
|
+
/**
|
|
1363
|
+
* Every route but a GET says what its audit entry names it: the command it runs when it changes the store's records,
|
|
1364
|
+
* or null when it changes none an audit covers (a cart, a session, a ticket).
|
|
1365
|
+
*/
|
|
1366
|
+
command?: string | null;
|
|
1367
|
+
/**
|
|
1368
|
+
* The command moves money through the payments provider. A keyed one does not run inside the key's transaction:
|
|
1369
|
+
* the service commits its own steps around the provider call, so what it holds is committed before money moves.
|
|
1370
|
+
*/
|
|
1371
|
+
provider?: true;
|
|
1137
1372
|
}
|
|
1138
1373
|
declare const routeSchemas: Record<string, RouteSchema>;
|
|
1139
1374
|
|
|
@@ -1163,7 +1398,7 @@ type CapabilitiesReport = Record<CapabilitySlot, SlotCapabilities>;
|
|
|
1163
1398
|
interface AttachHttpOptions {
|
|
1164
1399
|
adminRoot?: string | null;
|
|
1165
1400
|
}
|
|
1166
|
-
interface CreateAppOptions extends
|
|
1401
|
+
interface CreateAppOptions extends ResolvePrimitivesOptions {
|
|
1167
1402
|
version?: string;
|
|
1168
1403
|
/** The project's own adapters, one per slot whose provider is `custom`. */
|
|
1169
1404
|
adapters?: InjectedAdapters;
|
|
@@ -1208,6 +1443,10 @@ interface CartAbandonmentSweeperDeps {
|
|
|
1208
1443
|
*/
|
|
1209
1444
|
declare function startCartAbandonmentSweeper(deps: CartAbandonmentSweeperDeps): SweeperHandle;
|
|
1210
1445
|
|
|
1446
|
+
/** Where retention writes events before it deletes them: one object per batch, private to the operator. */
|
|
1447
|
+
interface EventArchiveWriter {
|
|
1448
|
+
put(key: string, body: Uint8Array, contentType: string): Promise<void>;
|
|
1449
|
+
}
|
|
1211
1450
|
interface EventRetentionSweeperDeps {
|
|
1212
1451
|
store: CommandStore;
|
|
1213
1452
|
eventLog: EventLogRepository;
|
|
@@ -1215,21 +1454,40 @@ interface EventRetentionSweeperDeps {
|
|
|
1215
1454
|
logger: Logger;
|
|
1216
1455
|
retentionDays?: number;
|
|
1217
1456
|
intervalMs?: number;
|
|
1457
|
+
/** When set, delivered events past retention are archived here first, and deleted only once the put succeeds. */
|
|
1458
|
+
archive?: EventArchiveWriter;
|
|
1218
1459
|
}
|
|
1219
|
-
/**
|
|
1460
|
+
/**
|
|
1461
|
+
* Deletes delivered events and processed-event records older than the window; undelivered and dead events stay. With
|
|
1462
|
+
* an archive, events go to it in `seq`-ordered batches first.
|
|
1463
|
+
*/
|
|
1220
1464
|
declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
|
|
1221
1465
|
|
|
1222
1466
|
interface ProviderPackage {
|
|
1223
1467
|
/** The adapter package, which exports `createAdapter(ctx: AdapterContext)`. */
|
|
1224
1468
|
package: string;
|
|
1225
|
-
/** The provider SDK the package peers, which the project installs beside it. */
|
|
1226
|
-
sdk
|
|
1469
|
+
/** The provider SDK the package peers, which the project installs beside it; none when it talks HTTP itself. */
|
|
1470
|
+
sdk?: string;
|
|
1227
1471
|
}
|
|
1472
|
+
type Packages<P extends ProviderPackage> = Readonly<Record<string, P>>;
|
|
1228
1473
|
/**
|
|
1229
1474
|
* The providers that live in their own package, by slot then provider. The kernel imports a package only when the
|
|
1230
|
-
* config names its provider; `native`, `none
|
|
1475
|
+
* config names its provider; `native`, `none`, `custom` and the kernel's own primitives (`in-memory`, `in-process`,
|
|
1476
|
+
* `local-fs`) have no entry. Every package peers its provider's SDK but the security ones, which call an HTTP API.
|
|
1231
1477
|
*/
|
|
1232
|
-
declare const PROVIDER_PACKAGES: Readonly<Partial<Record<
|
|
1478
|
+
declare const PROVIDER_PACKAGES: Readonly<Partial<Record<Exclude<Slot, 'security'>, Packages<Required<ProviderPackage>>>>> & {
|
|
1479
|
+
readonly security: Packages<ProviderPackage>;
|
|
1480
|
+
};
|
|
1481
|
+
/** The command that installs `packages` with the project's package manager, as `packageManager` picks it. */
|
|
1482
|
+
declare function installLine(packages: readonly string[], env: NodeJS.ProcessEnv, cwd: string): string;
|
|
1483
|
+
type ProviderModule = ProviderPackageModule;
|
|
1484
|
+
/**
|
|
1485
|
+
* The module of a provider that lives in its own package, imported from the kernel as `loadProviderAdapter` imports
|
|
1486
|
+
* it, or `undefined` when the provider is built in. A missing package or SDK is a `ConfigError`
|
|
1487
|
+
* (`adapter.package_missing`) carrying the install line, a module with no `createAdapter` is `adapter.package_invalid`,
|
|
1488
|
+
* and any other load error is rethrown as it is.
|
|
1489
|
+
*/
|
|
1490
|
+
declare function importProviderPackage(slot: Slot, provider: string, env: NodeJS.ProcessEnv): Promise<ProviderModule | undefined>;
|
|
1233
1491
|
|
|
1234
1492
|
/**
|
|
1235
1493
|
* v0.1 security adapter.
|
|
@@ -1259,7 +1517,6 @@ declare class RateLimiter {
|
|
|
1259
1517
|
reset(): void;
|
|
1260
1518
|
}
|
|
1261
1519
|
|
|
1262
|
-
declare function buildSecurityHeaders(security: SecurityConfigLike): Record<string, string>;
|
|
1263
1520
|
declare const CSRF_COOKIE = "nymbal.csrf";
|
|
1264
1521
|
declare const CSRF_HEADER = "x-csrf-token";
|
|
1265
1522
|
|
|
@@ -1283,8 +1540,15 @@ declare function createNativeEmailAdapter(deps: {
|
|
|
1283
1540
|
config?: NativeEmailAdapterConfig;
|
|
1284
1541
|
}): EmailAdapter;
|
|
1285
1542
|
|
|
1543
|
+
/** The cursor for a page starting at `offset`. It encodes any number; `search` rejects one that is not an offset. */
|
|
1544
|
+
declare function encodeSearchCursor(offset: number): string;
|
|
1545
|
+
/**
|
|
1546
|
+
* Full-text search in the command store's own database: FTS5 on SQLite, a GIN-indexed tsvector on Postgres. Both
|
|
1547
|
+
* match by `searchTerms` (every query term a prefix of a term in the name, a SKU, a variant name or the description)
|
|
1548
|
+
* and rank every-term-in-the-name matches first, then name/SKU/variant-name matches, then by the engine's score.
|
|
1549
|
+
*/
|
|
1286
1550
|
declare function createNativeSearchAdapter(deps: {
|
|
1287
|
-
|
|
1551
|
+
sql: RawClients;
|
|
1288
1552
|
logger: Logger;
|
|
1289
1553
|
}): SearchAdapter;
|
|
1290
1554
|
|
|
@@ -1305,9 +1569,42 @@ interface CreateLoggerOptions {
|
|
|
1305
1569
|
level?: string;
|
|
1306
1570
|
pretty?: boolean;
|
|
1307
1571
|
base?: Record<string, unknown>;
|
|
1572
|
+
/** Where the JSON lines go instead of stdout; a destination is never pretty-printed. */
|
|
1573
|
+
destination?: DestinationStream;
|
|
1308
1574
|
}
|
|
1309
1575
|
declare function createLogger(options?: CreateLoggerOptions): Logger;
|
|
1310
1576
|
|
|
1577
|
+
/** `ok` is a check with no health semantics (config, a package, migrations); the rest are a health report's. */
|
|
1578
|
+
type DiagnosisStatus = HealthStatus | 'ok';
|
|
1579
|
+
interface DiagnosisCheck {
|
|
1580
|
+
name: string;
|
|
1581
|
+
status: DiagnosisStatus;
|
|
1582
|
+
detail: string;
|
|
1583
|
+
}
|
|
1584
|
+
interface DiagnosisReport {
|
|
1585
|
+
checks: DiagnosisCheck[];
|
|
1586
|
+
}
|
|
1587
|
+
interface DiagnoseOptions {
|
|
1588
|
+
/** The project's adapters, one per slot whose provider is `custom`, as `createApp` takes them. */
|
|
1589
|
+
adapters?: InjectedAdapters;
|
|
1590
|
+
logger?: Logger;
|
|
1591
|
+
/** Each check's bound; `HEALTH_CHECK_TIMEOUT_MS` when not given. */
|
|
1592
|
+
timeoutMs?: number;
|
|
1593
|
+
env?: NodeJS.ProcessEnv;
|
|
1594
|
+
sqlitePath?: string;
|
|
1595
|
+
postgresUrl?: string;
|
|
1596
|
+
mediaRoot?: string;
|
|
1597
|
+
/** Where the migrations journal is read; the platform's own migrations when not given. */
|
|
1598
|
+
migrationsRoot?: string;
|
|
1599
|
+
}
|
|
1600
|
+
/**
|
|
1601
|
+
* Checks a project without changing it: its config, the packages its providers live in, the command store and its
|
|
1602
|
+
* migrations, and the health of every commerce slot, the security slot and every primitive. It builds what `createApp`
|
|
1603
|
+
* builds, through the same registry and constructors, and nothing more: no warm-up, no relay, no sweeper, no migrator,
|
|
1604
|
+
* 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.
|
|
1605
|
+
*/
|
|
1606
|
+
declare function diagnose(input: NymbalConfig, options?: DiagnoseOptions): Promise<DiagnosisReport>;
|
|
1607
|
+
|
|
1311
1608
|
interface SeedDeps {
|
|
1312
1609
|
config: NymbalConfig;
|
|
1313
1610
|
commandStore: CommandStore;
|
|
@@ -1315,6 +1612,13 @@ interface SeedDeps {
|
|
|
1315
1612
|
eventBus: EventBusAdapter;
|
|
1316
1613
|
logger: Logger;
|
|
1317
1614
|
version: string;
|
|
1615
|
+
/**
|
|
1616
|
+
* When given, each product's image is generated and written here, and the product points at the stored copy
|
|
1617
|
+
* instead of the third-party placeholder host: a store measured or run offline then serves its own images.
|
|
1618
|
+
*/
|
|
1619
|
+
media?: MediaStorage;
|
|
1620
|
+
/** The search index to rebuild with the document store; without it the next start's rebuild fills it. */
|
|
1621
|
+
search?: SearchAdapter;
|
|
1318
1622
|
}
|
|
1319
1623
|
interface SeedResult {
|
|
1320
1624
|
categories: number;
|
|
@@ -1327,19 +1631,174 @@ interface SeedResult {
|
|
|
1327
1631
|
}
|
|
1328
1632
|
declare function runSeed(deps: SeedDeps): Promise<SeedResult>;
|
|
1329
1633
|
|
|
1330
|
-
|
|
1634
|
+
/** The binary columns of an encrypted settings row. */
|
|
1635
|
+
interface EncryptedValue {
|
|
1636
|
+
ciphertext: Buffer;
|
|
1637
|
+
iv: Buffer;
|
|
1638
|
+
tag: Buffer;
|
|
1639
|
+
}
|
|
1640
|
+
/** The same columns as a driver hands them back (a Buffer, or a Uint8Array). */
|
|
1641
|
+
interface StoredCipher {
|
|
1642
|
+
ciphertext: Uint8Array | null;
|
|
1643
|
+
iv: Uint8Array | null;
|
|
1644
|
+
tag: Uint8Array | null;
|
|
1645
|
+
}
|
|
1646
|
+
/** The environment variable holding the master key, and the one `nymbal secrets rotate` reads the old key from. */
|
|
1647
|
+
declare const SECRETS_KEY_ENV = "NYMBAL_SECRETS_KEY";
|
|
1648
|
+
declare const SECRETS_KEY_OLD_ENV = "NYMBAL_SECRETS_KEY_OLD";
|
|
1649
|
+
/** AES-256-GCM under a fresh IV, bound to `aad` (`<slot>:<path>`), so a row moved to another field fails to decrypt. */
|
|
1650
|
+
declare function encrypt(key: Buffer, aad: string, plaintext: string): EncryptedValue;
|
|
1651
|
+
/** The plaintext, or a throw when the key, the AAD or any byte of the row is not what encrypted it. */
|
|
1652
|
+
declare function decrypt(key: Buffer, aad: string, row: StoredCipher): string;
|
|
1653
|
+
/** The first 8 hex characters of the key's SHA-256: which key a row was written under, without the key. */
|
|
1654
|
+
declare function keyId(key: Buffer): string;
|
|
1655
|
+
type SecretsKey = {
|
|
1656
|
+
ok: true;
|
|
1657
|
+
key: Buffer;
|
|
1658
|
+
id: string;
|
|
1659
|
+
} | {
|
|
1660
|
+
ok: false;
|
|
1661
|
+
reason: 'missing' | 'malformed';
|
|
1662
|
+
};
|
|
1663
|
+
/** The master key in `env[name]`: 32 bytes as base64, else why it cannot be used. */
|
|
1664
|
+
declare function readSecretsKey(env: NodeJS.ProcessEnv, name?: string): SecretsKey;
|
|
1665
|
+
/** What to tell an operator about a key `readSecretsKey` refused, naming the variable and never its value. */
|
|
1666
|
+
declare function keyProblem(reason: 'missing' | 'malformed', name?: string): string;
|
|
1667
|
+
/** The AAD of a settings row. */
|
|
1668
|
+
declare function settingAad(slot: string, path: string): string;
|
|
1669
|
+
|
|
1670
|
+
/** `text` with every secret in the set replaced by `***`. */
|
|
1671
|
+
declare function scrub(text: string): string;
|
|
1672
|
+
|
|
1673
|
+
/**
|
|
1674
|
+
* One subscription of a projection: the bus delivers live events to it, and a read-model rebuild calls it directly in
|
|
1675
|
+
* its catch-up, so a failure there is seen rather than logged by the bus.
|
|
1676
|
+
*/
|
|
1677
|
+
interface DerivedHandler {
|
|
1678
|
+
name: string;
|
|
1679
|
+
types: readonly string[];
|
|
1680
|
+
handle: EventHandler;
|
|
1681
|
+
}
|
|
1682
|
+
|
|
1683
|
+
/** A document of a collection, under its key. */
|
|
1684
|
+
interface DocumentWrite {
|
|
1685
|
+
collection: string;
|
|
1686
|
+
key: string;
|
|
1687
|
+
doc: unknown;
|
|
1688
|
+
}
|
|
1689
|
+
|
|
1690
|
+
type ReadModelName = 'catalogue' | 'orders' | 'customers' | 'search';
|
|
1691
|
+
interface RebuildDeps {
|
|
1331
1692
|
config: NymbalConfig;
|
|
1693
|
+
store: CommandStore;
|
|
1332
1694
|
repos: Repositories;
|
|
1333
|
-
|
|
1695
|
+
/** Where the document models are rebuilt and caught up. */
|
|
1696
|
+
documentStore: DocumentStoreAdapter;
|
|
1697
|
+
/** Where the search model is rebuilt and caught up; the search model cannot be rebuilt without it. */
|
|
1698
|
+
search?: SearchAdapter;
|
|
1334
1699
|
logger: Logger;
|
|
1335
|
-
|
|
1700
|
+
/** Rows per page read from the command store. */
|
|
1701
|
+
pageSize?: number;
|
|
1702
|
+
/** Called before each page is read. */
|
|
1703
|
+
onPage?: (page: {
|
|
1704
|
+
model: ReadModelName;
|
|
1705
|
+
table: string;
|
|
1706
|
+
page: number;
|
|
1707
|
+
}) => void | Promise<void>;
|
|
1708
|
+
}
|
|
1709
|
+
/** What a rebuilder reads with: the command store in pages, each page a read of its own. */
|
|
1710
|
+
interface RebuildContext {
|
|
1711
|
+
deps: RebuildDeps;
|
|
1712
|
+
pages<T extends {
|
|
1713
|
+
id: string;
|
|
1714
|
+
}>(table: string, read: (tx: ReadTx, page: KeysetPage) => Promise<T[]>): AsyncIterable<T[]>;
|
|
1715
|
+
}
|
|
1716
|
+
interface ReadModel {
|
|
1717
|
+
name: ReadModelName;
|
|
1718
|
+
/** Where its documents go: document-store collections, or the search adapter. */
|
|
1719
|
+
target: 'documents' | 'search';
|
|
1720
|
+
/** The document-store collections it owns; the search model owns none. */
|
|
1721
|
+
collections: readonly string[];
|
|
1722
|
+
/** Every document of the model, from the authoritative tables. A search model writes to `SEARCH_INDEX`. */
|
|
1723
|
+
rebuild(ctx: RebuildContext): AsyncIterable<DocumentWrite>;
|
|
1724
|
+
/** The live projections that keep the model, bound to `deps`' document store and search adapter. */
|
|
1725
|
+
handlers(deps: RebuildDeps): DerivedHandler[];
|
|
1726
|
+
}
|
|
1727
|
+
|
|
1728
|
+
/** Every derived read model, in the order a rebuild of all of them runs. */
|
|
1729
|
+
declare const READ_MODELS: readonly ReadModel[];
|
|
1730
|
+
declare const READ_MODEL_NAMES: readonly ReadModelName[];
|
|
1731
|
+
/**
|
|
1732
|
+
* How long before the rebuild started a delivery may be stamped and still be caught up. The relay stamps
|
|
1733
|
+
* `delivered_at` on its own host's clock, which can run behind this process's; re-applying an event costs little,
|
|
1734
|
+
* skipping one loses a write.
|
|
1735
|
+
*/
|
|
1736
|
+
declare const CATCH_UP_MARGIN_MS: number;
|
|
1737
|
+
interface CatchUpFailure {
|
|
1738
|
+
seq: number;
|
|
1739
|
+
eventId: string;
|
|
1740
|
+
type: string;
|
|
1741
|
+
handler: string;
|
|
1742
|
+
error: string;
|
|
1743
|
+
}
|
|
1744
|
+
interface RebuildReportEntry {
|
|
1745
|
+
model: ReadModelName;
|
|
1746
|
+
/** Each collection swapped in and the documents it was given (the search model's is `index`). */
|
|
1747
|
+
collections: Array<{
|
|
1748
|
+
name: string;
|
|
1749
|
+
documents: number;
|
|
1750
|
+
}>;
|
|
1751
|
+
/** Logged events re-applied after the swap. */
|
|
1752
|
+
caughtUpEvents: number;
|
|
1753
|
+
/** Catch-up events a handler failed on: the model is swapped all the same. */
|
|
1754
|
+
failures: CatchUpFailure[];
|
|
1755
|
+
ms: number;
|
|
1756
|
+
/** Set when the search adapter has no `replaceAll`: it was given every document, and kept any others it held. */
|
|
1757
|
+
note?: string;
|
|
1336
1758
|
}
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1759
|
+
type RebuildReport = RebuildReportEntry[];
|
|
1760
|
+
/** A rebuilder failed: nothing was swapped, so every read model keeps its old contents. */
|
|
1761
|
+
declare class RebuildError extends Error {
|
|
1762
|
+
readonly model: ReadModelName;
|
|
1763
|
+
constructor(model: ReadModelName, cause: unknown);
|
|
1764
|
+
}
|
|
1765
|
+
/**
|
|
1766
|
+
* Rebuilds `names` from the command store's tables: every model is read first, then each is swapped in (atomically
|
|
1767
|
+
* per collection) and caught up with the events delivered since its read began. A rebuilder that throws rejects with
|
|
1768
|
+
* a `RebuildError` before anything is swapped. Catch-up failures are in the report.
|
|
1769
|
+
*/
|
|
1770
|
+
declare function rebuild(names: readonly ReadModelName[], deps: RebuildDeps): Promise<RebuildReport>;
|
|
1771
|
+
interface CollectionDiff {
|
|
1772
|
+
name: string;
|
|
1773
|
+
added: number;
|
|
1774
|
+
changed: number;
|
|
1775
|
+
removed: number;
|
|
1776
|
+
}
|
|
1777
|
+
interface ReadModelDiff {
|
|
1778
|
+
model: ReadModelName;
|
|
1779
|
+
collections: CollectionDiff[];
|
|
1780
|
+
/** Why the model was not compared, when it was not. */
|
|
1781
|
+
skipped?: string;
|
|
1341
1782
|
}
|
|
1342
|
-
|
|
1783
|
+
/** Rebuilds `name` into memory and counts, per collection, what differs from the live read model; writes nothing. */
|
|
1784
|
+
declare function diffReadModel(name: ReadModelName, deps: RebuildDeps): Promise<ReadModelDiff>;
|
|
1785
|
+
|
|
1786
|
+
interface OpenReadModelsOptions {
|
|
1787
|
+
logger: Logger;
|
|
1788
|
+
/** The project's own adapters, for a `custom` search slot. */
|
|
1789
|
+
adapters?: InjectedAdapters;
|
|
1790
|
+
sqlitePath?: string;
|
|
1791
|
+
postgresUrl?: string;
|
|
1792
|
+
env?: NodeJS.ProcessEnv;
|
|
1793
|
+
}
|
|
1794
|
+
/**
|
|
1795
|
+
* What a rebuild outside the server needs, built as `createApp` builds it: the command store (writable), the document
|
|
1796
|
+
* store and the search adapter. No bus, relay, sweeper or other slot. `close()` closes what it opened.
|
|
1797
|
+
*/
|
|
1798
|
+
declare function openReadModels(config: NymbalConfig, options: OpenReadModelsOptions): Promise<{
|
|
1799
|
+
deps: RebuildDeps;
|
|
1800
|
+
close(): Promise<void>;
|
|
1801
|
+
}>;
|
|
1343
1802
|
|
|
1344
1803
|
interface SeedCategory {
|
|
1345
1804
|
slug: string;
|
|
@@ -1357,17 +1816,13 @@ interface SeedProduct {
|
|
|
1357
1816
|
declare const seedCategories: SeedCategory[];
|
|
1358
1817
|
declare const seedProducts: SeedProduct[];
|
|
1359
1818
|
|
|
1360
|
-
interface MediaStorage {
|
|
1361
|
-
capabilities(): readonly string[];
|
|
1362
|
-
put(key: string, body: Uint8Array, contentType: string): Promise<{
|
|
1363
|
-
url: string;
|
|
1364
|
-
}>;
|
|
1365
|
-
}
|
|
1366
|
-
|
|
1367
1819
|
interface LocalFsMediaStorageOptions {
|
|
1368
1820
|
root: string;
|
|
1369
1821
|
urlPrefix?: string;
|
|
1370
1822
|
}
|
|
1823
|
+
/** What the local filesystem storage offers, whatever its root: the app reports it for the media slot. */
|
|
1824
|
+
declare const LOCAL_FS_MEDIA_CAPABILITIES: readonly string[];
|
|
1371
1825
|
declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
|
|
1372
1826
|
|
|
1373
|
-
export {
|
|
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 };
|