@nymbalhq/platform 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +6 -0
- package/dist/{chunk-GMV3B3SC.js → chunk-KH3BABMV.js} +10570 -7364
- package/dist/chunk-KH3BABMV.js.map +1 -0
- package/dist/{chunk-SNNK2OX3.js → chunk-TVKV5GBY.js} +172 -9
- package/dist/chunk-TVKV5GBY.js.map +1 -0
- package/dist/db/schema/index.d.ts +6537 -3506
- package/dist/db/schema/index.js +1 -1
- package/dist/index.d.ts +893 -129
- package/dist/index.js +4321 -1905
- package/dist/index.js.map +1 -1
- package/dist/register-XP5XVAXM.js +8 -0
- package/migrations/postgres/0016_email_suppressions.sql +7 -0
- package/migrations/postgres/0017_order_shipments.sql +14 -0
- package/migrations/postgres/0018_order_key_expiry.sql +8 -0
- package/migrations/postgres/0019_carts_customer_idx.sql +1 -0
- package/migrations/postgres/0020_alert_confirmation_sent.sql +1 -0
- package/migrations/postgres/0021_proposals.sql +27 -0
- package/migrations/postgres/0022_order_source.sql +3 -0
- package/migrations/postgres/meta/0016_snapshot.json +2233 -0
- package/migrations/postgres/meta/0017_snapshot.json +2300 -0
- package/migrations/postgres/meta/0018_snapshot.json +2306 -0
- package/migrations/postgres/meta/0019_snapshot.json +2322 -0
- package/migrations/postgres/meta/0020_snapshot.json +2328 -0
- package/migrations/postgres/meta/0021_snapshot.json +2543 -0
- package/migrations/postgres/meta/0022_snapshot.json +2578 -0
- package/migrations/postgres/meta/_journal.json +49 -0
- package/migrations/sqlite/0016_email_suppressions.sql +7 -0
- package/migrations/sqlite/0017_order_shipments.sql +9 -0
- package/migrations/sqlite/0018_order_key_expiry.sql +25 -0
- package/migrations/sqlite/0019_carts_customer_idx.sql +1 -0
- package/migrations/sqlite/0020_alert_confirmation_sent.sql +1 -0
- package/migrations/sqlite/0021_proposals.sql +27 -0
- package/migrations/sqlite/0022_order_source.sql +3 -0
- package/migrations/sqlite/meta/0016_snapshot.json +1981 -0
- package/migrations/sqlite/meta/0017_snapshot.json +2041 -0
- package/migrations/sqlite/meta/0018_snapshot.json +2048 -0
- package/migrations/sqlite/meta/0019_snapshot.json +2056 -0
- package/migrations/sqlite/meta/0020_snapshot.json +2063 -0
- package/migrations/sqlite/meta/0021_snapshot.json +2246 -0
- package/migrations/sqlite/meta/0022_snapshot.json +2270 -0
- package/migrations/sqlite/meta/_journal.json +49 -0
- package/package.json +25 -52
- package/dist/chunk-GMV3B3SC.js.map +0 -1
- package/dist/chunk-SNNK2OX3.js.map +0 -1
- package/dist/register-N2XGSFUF.js +0 -8
- /package/dist/{register-N2XGSFUF.js.map → register-XP5XVAXM.js.map} +0 -0
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { NymbalConfig } from '@nymbalhq/config';
|
|
2
|
-
|
|
2
|
+
export { secureCookies } from '@nymbalhq/config';
|
|
3
|
+
import { Logger, DocumentStoreAdapter, EventBusAdapter, MediaStorage, Product, ProductStatus, ProductType, ProductMedia, Variant, VariantDimensions, VariantOption, VariantStatus, Category, Customer, Role, CustomerAddress, Order, OrderStatus, Address, OrderLineItem, CaptureMethod, OrderSource, OrderHistoryEntry, OrderRefundStatus, OrderRefund, InventoryReservation, StockAdjustmentReason, StockAdjustment, Review, ReviewModerationStatus, NymbalEvent, Cart, AuditSubject, AuditActor, AuditOutcome, AuditEntry, AlertKind, AlertStatus, ProposalStatus, ProposalDecider, ProposalView, HealthReport, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, RequestAuth, AdapterSetting, CommerceSlotAdapters, SecurityAdapter, AiAdapter, PaymentsAdapter, CartSource, EmailAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, SearchAdapter, OrderPayment, Refund, RecentViewer, ReviewsAdapter, Caller, ToolResult, ProposalPage, CommerceSlot, HttpAdapter, ToolSurface, RequestContext, ResponseEnvelope, RouteHandler, ToolDefinition, JsonSchemaObject, AssistantFrame, ResolvedNetwork, AgentSurfaces, AgentSurfaceUrls, AgentSurfaceAdapter, HealthStatus, SecurityNetwork, OriginLockRule, Slot, ProviderPackageModule, RateLimitAction, AnalyticsAdapter, ShippingAdapter, TaxAdapter } from '@nymbalhq/types';
|
|
3
4
|
export { MediaStorage, buildSecurityHeaders, isValidCorrelationId } from '@nymbalhq/types';
|
|
4
5
|
import BetterSqlite3 from 'better-sqlite3';
|
|
5
6
|
import pg from 'pg';
|
|
@@ -104,7 +105,9 @@ declare const REDIS_DEFAULTS: {
|
|
|
104
105
|
};
|
|
105
106
|
/**
|
|
106
107
|
* The document store, event bus and media storage the config names. A primitive that lives in its own package is
|
|
107
|
-
* imported only when named
|
|
108
|
+
* imported only when named, from its block's `package` or `@nymbalhq/<slot>-<provider>`; a missing package fails
|
|
109
|
+
* `adapter.package_missing` with the install line. A provider whose connection the kernel does not build gets its
|
|
110
|
+
* block's `config`.
|
|
108
111
|
*/
|
|
109
112
|
declare function resolvePrimitives(config: NymbalConfig, options?: ResolvePrimitivesOptions): Promise<Primitives>;
|
|
110
113
|
declare function createPlatform(config: NymbalConfig, options: CreatePlatformOptions): Platform;
|
|
@@ -113,6 +116,17 @@ interface MigrateOptions {
|
|
|
113
116
|
migrationsRoot?: string;
|
|
114
117
|
}
|
|
115
118
|
declare function runMigrations(store: CommandStore, options?: MigrateOptions): Promise<void>;
|
|
119
|
+
interface MigrationState {
|
|
120
|
+
/** Rows in the store's migrations table. */
|
|
121
|
+
applied: number;
|
|
122
|
+
/** Journal entries `runMigrations` would apply. */
|
|
123
|
+
pending: number;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* What `runMigrations` would do to `store`, read without writing. Drizzle applies every journal entry created after the
|
|
127
|
+
* newest one its table records, so that is what counts as pending; a store with no table has every entry pending.
|
|
128
|
+
*/
|
|
129
|
+
declare function migrationState(store: CommandStore, options?: MigrateOptions): Promise<MigrationState>;
|
|
116
130
|
|
|
117
131
|
interface ProductInsert$1 {
|
|
118
132
|
id: string;
|
|
@@ -254,6 +268,9 @@ interface VariantRepository extends StoreRepository {
|
|
|
254
268
|
findById(tx: ReadTx, id: string): Promise<Variant | null>;
|
|
255
269
|
findBySku(tx: ReadTx, sku: string): Promise<Variant | null>;
|
|
256
270
|
findByProduct(tx: ReadTx, productId: string): Promise<Variant[]>;
|
|
271
|
+
/** `findByProduct`, holding the rows for the rest of the transaction so concurrent commands on them queue behind
|
|
272
|
+
* this one (Postgres `FOR UPDATE`; SQLite's `BEGIN IMMEDIATE` already holds the database). */
|
|
273
|
+
lockByProduct(tx: Tx, productId: string): Promise<Variant[]>;
|
|
257
274
|
insert(tx: Tx, v: VariantInsert): Promise<void>;
|
|
258
275
|
update(tx: Tx, id: string, patch: VariantUpdate): Promise<void>;
|
|
259
276
|
/** One conditional UPDATE: the new stock, or null when the variant is missing or holds fewer than `qty`. */
|
|
@@ -365,13 +382,46 @@ interface RefreshTokenRow {
|
|
|
365
382
|
interface RefreshTokenRepository extends StoreRepository {
|
|
366
383
|
insert(tx: Tx, t: RefreshTokenInsert): Promise<void>;
|
|
367
384
|
findById(tx: ReadTx, id: string): Promise<RefreshTokenRow | null>;
|
|
385
|
+
/**
|
|
386
|
+
* Inserts `next` as the successor of `oldJti`. The old row's `revokedAt` is set only if it has none: re-rotating a
|
|
387
|
+
* token inside the reuse window keeps the instant of its first rotation, so the window never slides.
|
|
388
|
+
*/
|
|
368
389
|
rotate(tx: Tx, oldJti: string, next: RefreshTokenInsert): Promise<void>;
|
|
369
390
|
revoke(tx: Tx, id: string): Promise<void>;
|
|
391
|
+
/** Revokes every row of the customer not revoked already, leaving earlier `revokedAt` instants as they were. */
|
|
370
392
|
revokeAllForCustomer(tx: Tx, customerId: string): Promise<void>;
|
|
371
393
|
purgeExpired(tx: Tx, now: Date): Promise<number>;
|
|
394
|
+
/**
|
|
395
|
+
* Deletes rotated rows (a successor is recorded) revoked before `revokedBefore`. Rows revoked with no successor
|
|
396
|
+
* (logout, sign-out of every session) stay until they expire, so presenting one stays a plain refusal.
|
|
397
|
+
*/
|
|
398
|
+
purgeRotated(tx: Tx, revokedBefore: Date): Promise<number>;
|
|
399
|
+
deleteByCustomer(tx: Tx, customerId: string): Promise<void>;
|
|
372
400
|
}
|
|
373
401
|
declare function createRefreshTokenRepository(store: CommandStore): RefreshTokenRepository;
|
|
374
402
|
|
|
403
|
+
interface CustomerOrderTotals {
|
|
404
|
+
orderCount: number;
|
|
405
|
+
/** Σ (captured − refunded): the money the store kept. */
|
|
406
|
+
keptMinor: number;
|
|
407
|
+
/** Orders that captured any money. */
|
|
408
|
+
capturedCount: number;
|
|
409
|
+
firstAt: string | null;
|
|
410
|
+
lastAt: string | null;
|
|
411
|
+
}
|
|
412
|
+
/** One agent's orders in a window: how many, and Σ (captured − refunded). */
|
|
413
|
+
interface AgentSourceTotals {
|
|
414
|
+
source: `agent:${string}`;
|
|
415
|
+
count: number;
|
|
416
|
+
revenueMinor: number;
|
|
417
|
+
}
|
|
418
|
+
/** Every agent order in a window, and the agents that brought the most money. */
|
|
419
|
+
interface AgentTotals {
|
|
420
|
+
count: number;
|
|
421
|
+
revenueMinor: number;
|
|
422
|
+
/** At most `top` sources: revenue descending, then count descending, then source ascending. */
|
|
423
|
+
bySource: AgentSourceTotals[];
|
|
424
|
+
}
|
|
375
425
|
interface OrderInsert {
|
|
376
426
|
id: string;
|
|
377
427
|
orderNumber: string;
|
|
@@ -397,6 +447,8 @@ interface OrderInsert {
|
|
|
397
447
|
capture?: OrderCapture & {
|
|
398
448
|
refundedMinor: number;
|
|
399
449
|
};
|
|
450
|
+
/** Who brought the order; `storefront` when not given. */
|
|
451
|
+
source?: OrderSource;
|
|
400
452
|
createdAt: Date;
|
|
401
453
|
updatedAt: Date;
|
|
402
454
|
}
|
|
@@ -417,6 +469,15 @@ interface OrderRepository extends StoreRepository {
|
|
|
417
469
|
/** The newest order the cart became: neither pending nor cancelled. */
|
|
418
470
|
findLastConvertedByCartToken(tx: ReadTx, cartToken: string): Promise<Order | null>;
|
|
419
471
|
listByCustomer(tx: ReadTx, customerId: string, limit?: number): Promise<Order[]>;
|
|
472
|
+
/**
|
|
473
|
+
* The customer's newest order (by `createdAt`, then id) in one of `statuses` whose line items hold the product, or
|
|
474
|
+
* null: their orders are read newest first a page at a time until one does.
|
|
475
|
+
*/
|
|
476
|
+
newestHolding(tx: ReadTx, customerId: string, productId: string, statuses: readonly OrderStatus[]): Promise<Order | null>;
|
|
477
|
+
/** Totals over every order the customer has, however many. */
|
|
478
|
+
totalsByCustomer(tx: ReadTx, customerId: string): Promise<CustomerOrderTotals>;
|
|
479
|
+
/** The `agent:` orders created at or after `since`, any status, and the `top` agents among them. */
|
|
480
|
+
agentTotals(tx: ReadTx, since: Date, top: number): Promise<AgentTotals>;
|
|
420
481
|
list(tx: ReadTx, opts?: {
|
|
421
482
|
status?: OrderStatus;
|
|
422
483
|
limit?: number;
|
|
@@ -433,6 +494,10 @@ interface OrderRepository extends StoreRepository {
|
|
|
433
494
|
recordCapture(tx: Tx, id: string, capture: OrderCapture): Promise<void>;
|
|
434
495
|
setRefunded(tx: Tx, id: string, refundedMinor: number, updatedAt: Date): Promise<void>;
|
|
435
496
|
setNotes(tx: Tx, id: string, notes: string, updatedAt: Date): Promise<void>;
|
|
497
|
+
/** Deletes the order's row alone: the rows that reference it go first. */
|
|
498
|
+
delete(tx: Tx, id: string): Promise<void>;
|
|
499
|
+
/** Ids of the orders created at or after `since`. */
|
|
500
|
+
idsCreatedSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
436
501
|
}
|
|
437
502
|
declare function createOrderRepository(store: CommandStore): OrderRepository;
|
|
438
503
|
|
|
@@ -448,6 +513,9 @@ interface OrderHistoryInsert {
|
|
|
448
513
|
interface OrderHistoryRepository extends StoreRepository {
|
|
449
514
|
append(tx: Tx, entry: OrderHistoryInsert): Promise<void>;
|
|
450
515
|
listByOrder(tx: ReadTx, orderId: string): Promise<OrderHistoryEntry[]>;
|
|
516
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
517
|
+
/** The order of each entry written at or after `since`, once per entry. */
|
|
518
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
451
519
|
}
|
|
452
520
|
declare function createOrderHistoryRepository(store: CommandStore): OrderHistoryRepository;
|
|
453
521
|
|
|
@@ -477,6 +545,9 @@ interface OrderRefundRepository extends StoreRepository {
|
|
|
477
545
|
listByOrder(tx: ReadTx, orderId: string): Promise<OrderRefund[]>;
|
|
478
546
|
/** The refunds of each order, oldest first; an order without refunds is absent. */
|
|
479
547
|
listByOrders(tx: ReadTx, orderIds: string[]): Promise<Map<string, OrderRefund[]>>;
|
|
548
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
549
|
+
/** The order of each refund made at or after `since`, once per refund. */
|
|
550
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
480
551
|
}
|
|
481
552
|
declare function createOrderRefundRepository(store: CommandStore): OrderRefundRepository;
|
|
482
553
|
|
|
@@ -487,6 +558,8 @@ declare function createOrderSequenceRepository(store: CommandStore): OrderSequen
|
|
|
487
558
|
|
|
488
559
|
/** Who minted the key: a checkout answer, or the order-placed email. */
|
|
489
560
|
type OrderAccessKeyPurpose = 'checkout' | 'email';
|
|
561
|
+
/** What a key does for an order: opens it, has expired, or is not one of its keys. */
|
|
562
|
+
type OrderKeyState = 'open' | 'expired' | 'none';
|
|
490
563
|
interface OrderAccessKeyInsert {
|
|
491
564
|
id: string;
|
|
492
565
|
orderId: string;
|
|
@@ -494,11 +567,17 @@ interface OrderAccessKeyInsert {
|
|
|
494
567
|
keyHash: string;
|
|
495
568
|
purpose: OrderAccessKeyPurpose;
|
|
496
569
|
createdAt: Date;
|
|
570
|
+
expiresAt: Date;
|
|
497
571
|
}
|
|
498
572
|
interface OrderAccessKeyRepository extends StoreRepository {
|
|
499
573
|
insert(tx: Tx, k: OrderAccessKeyInsert): Promise<void>;
|
|
500
|
-
/**
|
|
501
|
-
opens(tx: ReadTx, orderId: string, keyHash: string): Promise<
|
|
574
|
+
/** What a key with this hash does for this order at `now`: another order's key is `none` here. */
|
|
575
|
+
opens(tx: ReadTx, orderId: string, keyHash: string, now: Date): Promise<OrderKeyState>;
|
|
576
|
+
/** Deletes the order's oldest keys of `purpose`, by `(created_at, id)`, until at most `keep` remain. */
|
|
577
|
+
keepNewest(tx: Tx, orderId: string, purpose: OrderAccessKeyPurpose, keep: number): Promise<void>;
|
|
578
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
579
|
+
/** The order of each key minted at or after `since`, once per key. */
|
|
580
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
502
581
|
}
|
|
503
582
|
declare function createOrderAccessKeyRepository(store: CommandStore): OrderAccessKeyRepository;
|
|
504
583
|
|
|
@@ -557,10 +636,20 @@ interface ReviewKey {
|
|
|
557
636
|
}
|
|
558
637
|
interface ReviewRepository extends StoreRepository {
|
|
559
638
|
findById(tx: ReadTx, id: string): Promise<Review | null>;
|
|
639
|
+
/** The customer's review of the product, whatever its moderation status. */
|
|
640
|
+
findByProductAndCustomer(tx: ReadTx, productId: string, customerId: string): Promise<Review | null>;
|
|
641
|
+
/**
|
|
642
|
+
* Holds the (product, customer) pair until the transaction ends, so a find then insert for it runs one at a time:
|
|
643
|
+
* a Postgres advisory lock; on SQLite the open `BEGIN IMMEDIATE` transaction already holds every write.
|
|
644
|
+
*/
|
|
645
|
+
lockPair(tx: Tx, productId: string, customerId: string): Promise<void>;
|
|
560
646
|
/** Newest first, ties by id descending; `after` is the last review of the previous page. */
|
|
561
647
|
listByProduct(tx: ReadTx, productId: string, status?: ReviewModerationStatus, limit?: number, after?: ReviewKey): Promise<Review[]>;
|
|
562
648
|
listByStatus(tx: ReadTx, status: ReviewModerationStatus, limit?: number): Promise<Review[]>;
|
|
563
649
|
insert(tx: Tx, r: ReviewInsert): Promise<void>;
|
|
650
|
+
delete(tx: Tx, id: string): Promise<void>;
|
|
651
|
+
/** Ids of the reviews submitted at or after `since`. */
|
|
652
|
+
idsSubmittedSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
564
653
|
setModerationStatus(tx: Tx, id: string, status: ReviewModerationStatus, moderatedBy: string, moderatedAt: Date): Promise<void>;
|
|
565
654
|
aggregateByProduct(tx: ReadTx, productId: string): Promise<{
|
|
566
655
|
average: number;
|
|
@@ -623,12 +712,17 @@ interface EventLogRepository extends StoreRepository {
|
|
|
623
712
|
* given, is the earliest the next attempt may be made.
|
|
624
713
|
*/
|
|
625
714
|
recordFailure(tx: Tx, id: string, at: Date, maxAttempts: number, retryAt?: Date): Promise<void>;
|
|
715
|
+
/** A delivery that failed during an adapter outage: only the earliest next attempt moves, nothing is counted. */
|
|
716
|
+
recordOutage(tx: Tx, id: string, retryAt: Date): Promise<void>;
|
|
626
717
|
countDead(tx: ReadTx): Promise<number>;
|
|
627
718
|
/** Dead events, oldest first. */
|
|
628
719
|
listDead(tx: ReadTx, limit: number): Promise<LoggedEvent[]>;
|
|
629
720
|
/** Neither delivered nor dead, with at least one failed attempt. */
|
|
630
721
|
countRetrying(tx: ReadTx): Promise<number>;
|
|
631
|
-
/**
|
|
722
|
+
/**
|
|
723
|
+
* Deletes delivered events delivered before `at`; returns how many. Undelivered and dead events, a dead one also
|
|
724
|
+
* marked delivered included, are never deleted.
|
|
725
|
+
*/
|
|
632
726
|
deleteDeliveredBefore(tx: Tx, at: Date): Promise<number>;
|
|
633
727
|
listAll(tx: ReadTx): Promise<LoggedEvent[]>;
|
|
634
728
|
/** One correlation id's events, by `seq`. */
|
|
@@ -677,6 +771,8 @@ interface CartRepository extends StoreRepository {
|
|
|
677
771
|
/** `findByToken`, holding the row for the rest of the transaction so concurrent commands on the cart queue behind
|
|
678
772
|
* this one (Postgres `FOR UPDATE`; SQLite's `BEGIN IMMEDIATE` already holds the database). */
|
|
679
773
|
lock(tx: Tx, token: string): Promise<Cart | null>;
|
|
774
|
+
/** The customer's most recently written cart that is still live at `at`; holds nothing. */
|
|
775
|
+
findLiveByCustomer(tx: ReadTx, customerId: string, at: Date): Promise<Cart | null>;
|
|
680
776
|
/** Inserts the cart, or replaces an expired row on its token. A live row on the token is left as it is and
|
|
681
777
|
* returned with `created: false`. */
|
|
682
778
|
create(tx: Tx, cart: Cart): Promise<{
|
|
@@ -804,6 +900,8 @@ interface AlertSubscription {
|
|
|
804
900
|
createdAt: Date;
|
|
805
901
|
updatedAt: Date;
|
|
806
902
|
confirmedAt: Date | null;
|
|
903
|
+
/** When its last confirmation was sent; null on a new or reissued row. */
|
|
904
|
+
confirmationSentAt: Date | null;
|
|
807
905
|
}
|
|
808
906
|
/** A subscribe request: a new row's values, of which a row already there takes only what its status allows. */
|
|
809
907
|
interface AlertSubscriptionRequest {
|
|
@@ -830,9 +928,11 @@ interface AlertSubscriptionRepository extends StoreRepository {
|
|
|
830
928
|
/**
|
|
831
929
|
* One write on the unique (email, variant, kind): a new row is `pending`; a `pending` row takes the request's origin;
|
|
832
930
|
* an `unsubscribed` or `fired` row returns to `pending` with the request's origin, confirm token and baseline (its
|
|
833
|
-
* unsubscribe token is kept); an `active` row only has `updated_at` touched. Answers the
|
|
931
|
+
* unsubscribe token is kept) and no confirmation sent; an `active` row only has `updated_at` touched. Answers the
|
|
932
|
+
* row after the write.
|
|
834
933
|
*/
|
|
835
934
|
upsertPending(tx: Tx, request: AlertSubscriptionRequest): Promise<AlertSubscription>;
|
|
935
|
+
markConfirmationSent(tx: Tx, id: string, at: Date): Promise<void>;
|
|
836
936
|
findById(tx: ReadTx, id: string): Promise<AlertSubscription | null>;
|
|
837
937
|
findByConfirmToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
|
|
838
938
|
findByUnsubscribeToken(tx: ReadTx, token: string): Promise<AlertSubscription | null>;
|
|
@@ -842,6 +942,111 @@ interface AlertSubscriptionRepository extends StoreRepository {
|
|
|
842
942
|
}
|
|
843
943
|
declare function createAlertSubscriptionRepository(store: CommandStore): AlertSubscriptionRepository;
|
|
844
944
|
|
|
945
|
+
type EmailSuppressionReason = 'hard_bounce' | 'complaint';
|
|
946
|
+
interface EmailSuppressionInput {
|
|
947
|
+
email: string;
|
|
948
|
+
reason: EmailSuppressionReason;
|
|
949
|
+
/** The feedback event that suppresses the address. */
|
|
950
|
+
eventId: string;
|
|
951
|
+
at: Date;
|
|
952
|
+
}
|
|
953
|
+
/** Addresses that hard-bounced or complained. Each method normalises the address it is given. */
|
|
954
|
+
interface EmailSuppressionRepository extends StoreRepository {
|
|
955
|
+
/** True when this call suppressed the address; false when it already was, whose first reason stays. */
|
|
956
|
+
suppress(tx: Tx, input: EmailSuppressionInput): Promise<boolean>;
|
|
957
|
+
isSuppressed(tx: ReadTx, email: string): Promise<boolean>;
|
|
958
|
+
}
|
|
959
|
+
declare function createEmailSuppressionRepository(store: CommandStore): EmailSuppressionRepository;
|
|
960
|
+
|
|
961
|
+
interface OrderShipmentInput {
|
|
962
|
+
orderId: string;
|
|
963
|
+
carrier: string;
|
|
964
|
+
trackingNumber: string;
|
|
965
|
+
at: Date;
|
|
966
|
+
}
|
|
967
|
+
/** The parcel each shipped order went out in. Each method normalises the tracking number it is given. */
|
|
968
|
+
interface OrderShipmentRepository extends StoreRepository {
|
|
969
|
+
record(tx: Tx, input: OrderShipmentInput): Promise<void>;
|
|
970
|
+
/** The ids of every order shipped under the number, in no particular order. */
|
|
971
|
+
ordersByTrackingNumber(tx: ReadTx, trackingNumber: string): Promise<string[]>;
|
|
972
|
+
deleteByOrder(tx: Tx, orderId: string): Promise<void>;
|
|
973
|
+
/** The orders shipped at or after `since`. */
|
|
974
|
+
orderIdsSince(tx: ReadTx, since: Date): Promise<string[]>;
|
|
975
|
+
}
|
|
976
|
+
declare function createOrderShipmentRepository(store: CommandStore): OrderShipmentRepository;
|
|
977
|
+
|
|
978
|
+
/** One `proposals` row. */
|
|
979
|
+
interface ProposalRecord {
|
|
980
|
+
id: string;
|
|
981
|
+
tool: string;
|
|
982
|
+
command: string;
|
|
983
|
+
args: Record<string, unknown>;
|
|
984
|
+
/** Argument name to value: the credentials (a cart id) the call carried as handles. */
|
|
985
|
+
handles: Record<string, string> | null;
|
|
986
|
+
idempotencyKey: string | null;
|
|
987
|
+
proposerId: string | null;
|
|
988
|
+
agentName: string;
|
|
989
|
+
agentVersion: string | null;
|
|
990
|
+
correlationId: string;
|
|
991
|
+
status: ProposalStatus;
|
|
992
|
+
decidedByKind: 'admin' | 'policy' | null;
|
|
993
|
+
decidedBy: string | null;
|
|
994
|
+
decidedAt: string | null;
|
|
995
|
+
reason: string | null;
|
|
996
|
+
outcomeStatus: number | null;
|
|
997
|
+
outcomeCode: string | null;
|
|
998
|
+
outcomeMessage: string | null;
|
|
999
|
+
createdAt: string;
|
|
1000
|
+
settledAt: string | null;
|
|
1001
|
+
}
|
|
1002
|
+
type ProposalInsert = Pick<ProposalRecord, 'id' | 'tool' | 'command' | 'args' | 'handles' | 'idempotencyKey' | 'proposerId' | 'agentName' | 'agentVersion' | 'correlationId'> & {
|
|
1003
|
+
createdAt: Date;
|
|
1004
|
+
};
|
|
1005
|
+
interface ProposalDecision {
|
|
1006
|
+
status: 'approved' | 'rejected';
|
|
1007
|
+
by: ProposalDecider;
|
|
1008
|
+
at: Date;
|
|
1009
|
+
reason?: string | undefined;
|
|
1010
|
+
}
|
|
1011
|
+
interface ProposalSettlement {
|
|
1012
|
+
status: 'applied' | 'failed';
|
|
1013
|
+
outcome: {
|
|
1014
|
+
status: number;
|
|
1015
|
+
code?: string;
|
|
1016
|
+
message?: string;
|
|
1017
|
+
};
|
|
1018
|
+
at: Date;
|
|
1019
|
+
}
|
|
1020
|
+
/** A position in the (created_at, id) order proposals are listed in, newest first. */
|
|
1021
|
+
interface ProposalCursor {
|
|
1022
|
+
at: string;
|
|
1023
|
+
id: string;
|
|
1024
|
+
}
|
|
1025
|
+
interface ProposalQuery {
|
|
1026
|
+
status: 'pending' | 'decided' | 'all';
|
|
1027
|
+
cursor?: ProposalCursor;
|
|
1028
|
+
limit: number;
|
|
1029
|
+
}
|
|
1030
|
+
interface ProposalRepository extends StoreRepository {
|
|
1031
|
+
/** False when the proposer already has a row for the tool under the key: that row stands. */
|
|
1032
|
+
insert(tx: Tx, row: ProposalInsert): Promise<boolean>;
|
|
1033
|
+
findById(tx: ReadTx, id: string): Promise<ProposalRecord | null>;
|
|
1034
|
+
findByKey(tx: ReadTx, proposerId: string, tool: string, key: string): Promise<ProposalRecord | null>;
|
|
1035
|
+
/** Decides a pending row; false when it was not pending (or does not exist). */
|
|
1036
|
+
decide(tx: Tx, id: string, decision: ProposalDecision): Promise<boolean>;
|
|
1037
|
+
/** Settles an approved row with what its command answered; false when it was not approved. */
|
|
1038
|
+
settle(tx: Tx, id: string, settlement: ProposalSettlement): Promise<boolean>;
|
|
1039
|
+
/** Newest first, the rows before `cursor`, at most `limit`. */
|
|
1040
|
+
list(tx: ReadTx, q: ProposalQuery): Promise<ProposalRecord[]>;
|
|
1041
|
+
countPending(tx: ReadTx): Promise<number>;
|
|
1042
|
+
}
|
|
1043
|
+
declare function encodeProposalCursor(row: Pick<ProposalRecord, 'createdAt' | 'id'>): string;
|
|
1044
|
+
/** A cursor `encodeProposalCursor` made, or undefined for anything else. */
|
|
1045
|
+
declare function decodeProposalCursor(value: string): ProposalCursor | undefined;
|
|
1046
|
+
/** The row as the admin reads it: a handle by its argument's name only. */
|
|
1047
|
+
declare function proposalView(row: ProposalRecord): ProposalView;
|
|
1048
|
+
declare function createProposalRepository(store: CommandStore): ProposalRepository;
|
|
1049
|
+
|
|
845
1050
|
interface Repositories {
|
|
846
1051
|
product: ProductRepository;
|
|
847
1052
|
variant: VariantRepository;
|
|
@@ -863,6 +1068,9 @@ interface Repositories {
|
|
|
863
1068
|
settings: SettingsRepository;
|
|
864
1069
|
auditEntry: AuditEntryRepository;
|
|
865
1070
|
alertSubscription: AlertSubscriptionRepository;
|
|
1071
|
+
emailSuppression: EmailSuppressionRepository;
|
|
1072
|
+
orderShipment: OrderShipmentRepository;
|
|
1073
|
+
proposal: ProposalRepository;
|
|
866
1074
|
}
|
|
867
1075
|
declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
|
|
868
1076
|
|
|
@@ -917,6 +1125,15 @@ interface MakeEventOptions {
|
|
|
917
1125
|
}
|
|
918
1126
|
declare function createEventBuilder(ctx: EventBuilderContext): <T>(type: string, payload: T, options?: MakeEventOptions) => NymbalEvent<T>;
|
|
919
1127
|
|
|
1128
|
+
interface OutageReport {
|
|
1129
|
+
/** True when any checked subject is down, threw or did not answer in time. */
|
|
1130
|
+
outage: boolean;
|
|
1131
|
+
down: readonly {
|
|
1132
|
+
name: string;
|
|
1133
|
+
detail: string;
|
|
1134
|
+
}[];
|
|
1135
|
+
}
|
|
1136
|
+
|
|
920
1137
|
/** Hands committed events from the log to the bus. */
|
|
921
1138
|
interface Relay {
|
|
922
1139
|
/** Delivers every undelivered, non-dead event in `seq` order. Never rejects. */
|
|
@@ -945,6 +1162,13 @@ interface CreateRelayOptions {
|
|
|
945
1162
|
retryDelayMs?: number;
|
|
946
1163
|
/** The clock failures and retry waits are read from. */
|
|
947
1164
|
now?: () => Date;
|
|
1165
|
+
/**
|
|
1166
|
+
* Asked once a pass, at its first failed delivery: a failure during an outage is not counted toward `maxAttempts`.
|
|
1167
|
+
* Absent, no failure is an outage.
|
|
1168
|
+
*/
|
|
1169
|
+
outage?: () => Promise<OutageReport>;
|
|
1170
|
+
/** How long the relay waits on `outage` before taking the pass as an outage (default the health check bound + 1 s). */
|
|
1171
|
+
outageTimeoutMs?: number;
|
|
948
1172
|
}
|
|
949
1173
|
declare function createRelay(opts: CreateRelayOptions): Relay;
|
|
950
1174
|
|
|
@@ -1050,6 +1274,10 @@ interface BuildAdaptersDeps {
|
|
|
1050
1274
|
}
|
|
1051
1275
|
declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
|
|
1052
1276
|
|
|
1277
|
+
/** A pending row is sent its confirmation again only once this long has passed since the last one. */
|
|
1278
|
+
declare const ALERT_CONFIRMATION_INTERVAL_MS = 600000;
|
|
1279
|
+
/** Whether a row's last confirmation, if any, was sent at least the interval before `now`. */
|
|
1280
|
+
declare function confirmationDue(row: AlertSubscription, now: Date): boolean;
|
|
1053
1281
|
interface AlertSubscribeInput {
|
|
1054
1282
|
email: string;
|
|
1055
1283
|
variantId: string;
|
|
@@ -1068,7 +1296,8 @@ interface AlertConfirmed {
|
|
|
1068
1296
|
interface AlertService {
|
|
1069
1297
|
/**
|
|
1070
1298
|
* Answers `pending` whatever the address's account or subscription, so the answer reveals neither; every accepted
|
|
1071
|
-
* request writes the row once.
|
|
1299
|
+
* request writes the row once. A new or reissued row is sent its confirmation; a row already pending only once the
|
|
1300
|
+
* interval has passed since its last one.
|
|
1072
1301
|
*/
|
|
1073
1302
|
subscribe(input: AlertSubscribeInput): Promise<{
|
|
1074
1303
|
status: 'pending';
|
|
@@ -1079,9 +1308,12 @@ interface AlertService {
|
|
|
1079
1308
|
}>;
|
|
1080
1309
|
/**
|
|
1081
1310
|
* In the transaction that marks an alert's send: a back-in-stock row is `fired`, a price-drop row stays `active` with
|
|
1082
|
-
* the trigger's price as its baseline; `alert.sent.v1` names the trigger.
|
|
1311
|
+
* the trigger's price as its baseline; `alert.sent.v1` names the trigger. A row no longer `active` is left as it is,
|
|
1312
|
+
* with no event: answers whether the row moved.
|
|
1083
1313
|
*/
|
|
1084
|
-
recordSent(tx: Tx, subscription: AlertSubscription, trigger: NymbalEvent<unknown>): Promise<
|
|
1314
|
+
recordSent(tx: Tx, subscription: AlertSubscription, trigger: NymbalEvent<unknown>): Promise<boolean>;
|
|
1315
|
+
/** In the transaction that marks a confirmation's send: the row's interval starts at `at`. */
|
|
1316
|
+
recordConfirmationSent(tx: Tx, subscription: AlertSubscription, request: NymbalEvent<unknown>, at: Date): Promise<void>;
|
|
1085
1317
|
}
|
|
1086
1318
|
interface CreateAlertServiceDeps {
|
|
1087
1319
|
store: CommandStore;
|
|
@@ -1094,6 +1326,73 @@ interface CreateAlertServiceDeps {
|
|
|
1094
1326
|
}
|
|
1095
1327
|
declare function createAlertService(deps: CreateAlertServiceDeps): AlertService;
|
|
1096
1328
|
|
|
1329
|
+
interface OrderCreateDraftInput {
|
|
1330
|
+
orderId: string;
|
|
1331
|
+
customerId: string | null;
|
|
1332
|
+
email: string;
|
|
1333
|
+
billingAddress: Address;
|
|
1334
|
+
shippingAddress: Address;
|
|
1335
|
+
lineItems: OrderLineItem[];
|
|
1336
|
+
subtotalMinor: number;
|
|
1337
|
+
taxTotalMinor: number;
|
|
1338
|
+
shippingTotalMinor: number;
|
|
1339
|
+
discountTotalMinor: number;
|
|
1340
|
+
totalMinor: number;
|
|
1341
|
+
currency: string;
|
|
1342
|
+
notes?: string;
|
|
1343
|
+
metadata?: Record<string, unknown>;
|
|
1344
|
+
paymentIntentId?: string | null;
|
|
1345
|
+
cartToken?: string | null;
|
|
1346
|
+
/** The source of the cart the order is placed from; `storefront` when not given. */
|
|
1347
|
+
source?: CartSource;
|
|
1348
|
+
}
|
|
1349
|
+
/** An imported order's source is always `import`. */
|
|
1350
|
+
interface OrderImportInput extends Omit<OrderCreateDraftInput, 'source'> {
|
|
1351
|
+
orderNumber: string;
|
|
1352
|
+
status: OrderStatus;
|
|
1353
|
+
createdAt: Date;
|
|
1354
|
+
/** What the imported order was paid, taken as captured when it was placed; nothing when absent. */
|
|
1355
|
+
capturedMinor?: number;
|
|
1356
|
+
refundedMinor?: number;
|
|
1357
|
+
captureMethod?: CaptureMethod | null;
|
|
1358
|
+
}
|
|
1359
|
+
interface OrderService {
|
|
1360
|
+
createFromCheckout(input: OrderCreateDraftInput): Promise<Order>;
|
|
1361
|
+
importOrder(input: OrderImportInput): Promise<Order>;
|
|
1362
|
+
getById(id: string): Promise<Order>;
|
|
1363
|
+
getByOrderNumber(orderNumber: string): Promise<Order>;
|
|
1364
|
+
listByCustomer(customerId: string): Promise<Order[]>;
|
|
1365
|
+
/** Whether `key` opens the order now: one of its own keys, well formed and unexpired. */
|
|
1366
|
+
keyOpens(orderId: string, key: string): Promise<boolean>;
|
|
1367
|
+
/** What `key` does for the order at `now`: another order's key, or a malformed one, is `none`. */
|
|
1368
|
+
keyState(orderId: string, key: string, now?: Date): Promise<OrderKeyState>;
|
|
1369
|
+
/**
|
|
1370
|
+
* "Send me my order link": when the number and email name an order a confirmation is due for (confirmed or later),
|
|
1371
|
+
* its order-placed email is sent again, with a fresh link for a guest's order. Anything else does nothing, and the
|
|
1372
|
+
* caller is told nothing either way.
|
|
1373
|
+
*/
|
|
1374
|
+
requestLink(orderNumber: string, email: string): Promise<void>;
|
|
1375
|
+
updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
|
|
1376
|
+
markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
|
|
1377
|
+
markDelivered(id: string, actor: string): Promise<Order>;
|
|
1378
|
+
/** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
|
|
1379
|
+
cancel(id: string, reason: string, actor: string): Promise<Order>;
|
|
1380
|
+
/**
|
|
1381
|
+
* Asks for the order's confirmation email again; the email handler sends it. Refuses with `order.unpaid` for an
|
|
1382
|
+
* order no confirmation is due for (pending, or cancelled and so never paid). Changes nothing on the order.
|
|
1383
|
+
*/
|
|
1384
|
+
resendConfirmation(id: string): Promise<Order>;
|
|
1385
|
+
}
|
|
1386
|
+
interface CreateOrderServiceDeps {
|
|
1387
|
+
store: CommandStore;
|
|
1388
|
+
repos: Repositories;
|
|
1389
|
+
publisher: EventPublisher;
|
|
1390
|
+
logger: Logger;
|
|
1391
|
+
orderNumberPrefix: string;
|
|
1392
|
+
orderNumberStart: number;
|
|
1393
|
+
}
|
|
1394
|
+
declare function createOrderService(deps: CreateOrderServiceDeps): OrderService;
|
|
1395
|
+
|
|
1097
1396
|
interface RegisterHandlersDeps {
|
|
1098
1397
|
config: NymbalConfig;
|
|
1099
1398
|
eventBus: EventBusAdapter;
|
|
@@ -1102,6 +1401,8 @@ interface RegisterHandlersDeps {
|
|
|
1102
1401
|
adapters: AdapterRegistry;
|
|
1103
1402
|
/** Records each alert's send: the row fired and `alert.sent.v1` published. */
|
|
1104
1403
|
alerts: AlertService;
|
|
1404
|
+
/** Moves an order a tracking update reports delivered. */
|
|
1405
|
+
orders: OrderService;
|
|
1105
1406
|
logger: Logger;
|
|
1106
1407
|
}
|
|
1107
1408
|
declare function registerHandlers(deps: RegisterHandlersDeps): Promise<void>;
|
|
@@ -1110,7 +1411,7 @@ interface RegisterAlertHandlerDeps {
|
|
|
1110
1411
|
eventBus: EventBusAdapter;
|
|
1111
1412
|
email: EmailAdapter;
|
|
1112
1413
|
logger: Logger;
|
|
1113
|
-
repos: Pick<Repositories, 'alertSubscription' | 'processedEvent' | 'product'>;
|
|
1414
|
+
repos: Pick<Repositories, 'alertSubscription' | 'emailSuppression' | 'processedEvent' | 'product'>;
|
|
1114
1415
|
alerts: AlertService;
|
|
1115
1416
|
storeName: string;
|
|
1116
1417
|
}
|
|
@@ -1195,7 +1496,8 @@ declare function createCategoryService(deps: {
|
|
|
1195
1496
|
}): CategoryService;
|
|
1196
1497
|
|
|
1197
1498
|
interface CartService {
|
|
1198
|
-
|
|
1499
|
+
/** The live cart on `token`, or a new one opened with `source`; an existing cart keeps its own source. */
|
|
1500
|
+
getOrCreate(token?: string, customerId?: string | null, source?: CartSource): Promise<Cart>;
|
|
1199
1501
|
get(token: string): Promise<Cart | null>;
|
|
1200
1502
|
addItem(token: string, item: Omit<CartItem, 'qty'> & {
|
|
1201
1503
|
qty?: number;
|
|
@@ -1205,13 +1507,29 @@ interface CartService {
|
|
|
1205
1507
|
clear(token: string): Promise<Cart>;
|
|
1206
1508
|
merge(guestToken: string, customerToken: string): Promise<Cart>;
|
|
1207
1509
|
attachCustomer(token: string, customerId: string): Promise<Cart>;
|
|
1510
|
+
/** The customer's cart once the guest cart at `guestToken` is folded into it; null when there is neither. */
|
|
1511
|
+
signIn(guestToken: string | undefined, customerId: string): Promise<Cart | null>;
|
|
1512
|
+
}
|
|
1513
|
+
/** A variant can go on a cart while it and its product are both active. */
|
|
1514
|
+
declare function isSellable(variant: Pick<Variant, 'status'>, product: Pick<Product, 'status'>): boolean;
|
|
1515
|
+
/** Which variants can be on a cart: the variant and its product both exist and are sellable. */
|
|
1516
|
+
interface CartCatalogue {
|
|
1517
|
+
sellable(tx: ReadTx, variantIds: readonly string[]): Promise<ReadonlySet<string>>;
|
|
1208
1518
|
}
|
|
1519
|
+
declare function createCartCatalogue(repos: {
|
|
1520
|
+
variant: VariantRepository;
|
|
1521
|
+
product: ProductRepository;
|
|
1522
|
+
}): CartCatalogue;
|
|
1209
1523
|
interface CreateCartServiceDeps {
|
|
1210
1524
|
store: CommandStore;
|
|
1211
1525
|
carts: CartRepository;
|
|
1212
1526
|
publisher: EventPublisher;
|
|
1213
1527
|
logger: Logger;
|
|
1214
1528
|
currency: string;
|
|
1529
|
+
/** Which variants a cart may keep at a sign-in; the store's variants and products by default. */
|
|
1530
|
+
catalogue?: CartCatalogue;
|
|
1531
|
+
/** Finds a guest cart's checkout in progress, which keeps that cart at a sign-in; the store's orders by default. */
|
|
1532
|
+
pendingOrders?: Pick<OrderRepository, 'findPendingByCartToken'>;
|
|
1215
1533
|
ttlSeconds?: number;
|
|
1216
1534
|
now?: () => Date;
|
|
1217
1535
|
}
|
|
@@ -1222,12 +1540,20 @@ interface ProfileUpdate {
|
|
|
1222
1540
|
lastName?: string;
|
|
1223
1541
|
phone?: string;
|
|
1224
1542
|
}
|
|
1543
|
+
/** An admin's note on a customer, kept in its metadata. */
|
|
1544
|
+
interface CustomerNote {
|
|
1545
|
+
body: string;
|
|
1546
|
+
actor: string;
|
|
1547
|
+
at: string;
|
|
1548
|
+
}
|
|
1225
1549
|
interface CustomerService {
|
|
1226
1550
|
getProfile(customerId: string): Promise<Customer>;
|
|
1227
1551
|
updateProfile(customerId: string, patch: ProfileUpdate): Promise<Customer>;
|
|
1228
1552
|
listAddresses(customerId: string): Promise<CustomerAddress[]>;
|
|
1229
1553
|
addAddress(customerId: string, addr: Omit<CustomerAddress, 'id'>): Promise<CustomerAddress>;
|
|
1230
1554
|
deleteAddress(customerId: string, addressId: string): Promise<void>;
|
|
1555
|
+
/** Appends `note` to the customer's admin notes. */
|
|
1556
|
+
addNote(customerId: string, note: CustomerNote): Promise<void>;
|
|
1231
1557
|
}
|
|
1232
1558
|
declare function createCustomerService(deps: {
|
|
1233
1559
|
repos: Repositories;
|
|
@@ -1286,64 +1612,13 @@ interface CreateAuthServiceDeps {
|
|
|
1286
1612
|
issuer?: string;
|
|
1287
1613
|
}
|
|
1288
1614
|
declare function parseDurationToMs(s: string): number;
|
|
1615
|
+
/**
|
|
1616
|
+
* How long after its first rotation a refresh token may be rotated again: two tabs restored together present one cookie
|
|
1617
|
+
* at once. The window is anchored at that first rotation and never slides.
|
|
1618
|
+
*/
|
|
1619
|
+
declare const REFRESH_REUSE_WINDOW_MS = 30000;
|
|
1289
1620
|
declare function createAuthService(deps: CreateAuthServiceDeps): AuthService;
|
|
1290
1621
|
|
|
1291
|
-
interface OrderCreateDraftInput {
|
|
1292
|
-
orderId: string;
|
|
1293
|
-
customerId: string | null;
|
|
1294
|
-
email: string;
|
|
1295
|
-
billingAddress: Address;
|
|
1296
|
-
shippingAddress: Address;
|
|
1297
|
-
lineItems: OrderLineItem[];
|
|
1298
|
-
subtotalMinor: number;
|
|
1299
|
-
taxTotalMinor: number;
|
|
1300
|
-
shippingTotalMinor: number;
|
|
1301
|
-
discountTotalMinor: number;
|
|
1302
|
-
totalMinor: number;
|
|
1303
|
-
currency: string;
|
|
1304
|
-
notes?: string;
|
|
1305
|
-
metadata?: Record<string, unknown>;
|
|
1306
|
-
paymentIntentId?: string | null;
|
|
1307
|
-
cartToken?: string | null;
|
|
1308
|
-
}
|
|
1309
|
-
interface OrderImportInput extends OrderCreateDraftInput {
|
|
1310
|
-
orderNumber: string;
|
|
1311
|
-
status: OrderStatus;
|
|
1312
|
-
createdAt: Date;
|
|
1313
|
-
/** What the imported order was paid, taken as captured when it was placed; nothing when absent. */
|
|
1314
|
-
capturedMinor?: number;
|
|
1315
|
-
refundedMinor?: number;
|
|
1316
|
-
captureMethod?: CaptureMethod | null;
|
|
1317
|
-
}
|
|
1318
|
-
interface OrderService {
|
|
1319
|
-
createFromCheckout(input: OrderCreateDraftInput): Promise<Order>;
|
|
1320
|
-
importOrder(input: OrderImportInput): Promise<Order>;
|
|
1321
|
-
getById(id: string): Promise<Order>;
|
|
1322
|
-
getByOrderNumber(orderNumber: string): Promise<Order>;
|
|
1323
|
-
listByCustomer(customerId: string): Promise<Order[]>;
|
|
1324
|
-
/** Whether `key` opens the order: one of its own keys, well formed. Another order's key opens nothing. */
|
|
1325
|
-
keyOpens(orderId: string, key: string): Promise<boolean>;
|
|
1326
|
-
updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
|
|
1327
|
-
markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
|
|
1328
|
-
markDelivered(id: string, actor: string): Promise<Order>;
|
|
1329
|
-
/** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
|
|
1330
|
-
cancel(id: string, reason: string, actor: string): Promise<Order>;
|
|
1331
|
-
/**
|
|
1332
|
-
* Asks for the order's confirmation email again; the email handler sends it. Refuses with `order.unpaid` for an
|
|
1333
|
-
* order no confirmation is due for (pending, or cancelled and so never paid). Changes nothing on the order.
|
|
1334
|
-
*/
|
|
1335
|
-
resendConfirmation(id: string): Promise<Order>;
|
|
1336
|
-
}
|
|
1337
|
-
interface CreateOrderServiceDeps {
|
|
1338
|
-
store: CommandStore;
|
|
1339
|
-
repos: Repositories;
|
|
1340
|
-
publisher: EventPublisher;
|
|
1341
|
-
logger: Logger;
|
|
1342
|
-
orderNumberPrefix: string;
|
|
1343
|
-
orderNumberStart: number;
|
|
1344
|
-
}
|
|
1345
|
-
declare function createOrderService(deps: CreateOrderServiceDeps): OrderService;
|
|
1346
|
-
|
|
1347
1622
|
interface ReserveStockResult {
|
|
1348
1623
|
reservationId: string;
|
|
1349
1624
|
expiresAt: string;
|
|
@@ -1379,6 +1654,13 @@ interface BeginCheckoutInput {
|
|
|
1379
1654
|
billingAddress: Address;
|
|
1380
1655
|
shippingAddress: Address;
|
|
1381
1656
|
notes?: string;
|
|
1657
|
+
/**
|
|
1658
|
+
* A payment credential an agent holds for the buyer (an ACP Shared Payment Token), charged at once. No one is there
|
|
1659
|
+
* to complete a challenge, so an intent that neither succeeds nor fails is cancelled.
|
|
1660
|
+
*/
|
|
1661
|
+
delegatedPayment?: {
|
|
1662
|
+
token: string;
|
|
1663
|
+
};
|
|
1382
1664
|
}
|
|
1383
1665
|
interface BeginCheckoutResult {
|
|
1384
1666
|
orderId: string;
|
|
@@ -1389,8 +1671,11 @@ interface BeginCheckoutResult {
|
|
|
1389
1671
|
/** The order's status as the checkout answers. */
|
|
1390
1672
|
orderStatus: OrderStatus;
|
|
1391
1673
|
payment: CheckoutPayment;
|
|
1392
|
-
/**
|
|
1393
|
-
|
|
1674
|
+
/**
|
|
1675
|
+
* A guest order's fresh key, which reads it with no session (`ORDER_KEY_HEADER`) until it expires. Only its hash is
|
|
1676
|
+
* stored. A signed-in customer's order has none: their account is its home.
|
|
1677
|
+
*/
|
|
1678
|
+
orderKey?: string;
|
|
1394
1679
|
}
|
|
1395
1680
|
/** What the payment provider captured. */
|
|
1396
1681
|
interface CapturedPayment {
|
|
@@ -1413,7 +1698,11 @@ interface CheckoutService {
|
|
|
1413
1698
|
* there is an order, a history note) and leaves the order as it was. Joins the caller's transaction.
|
|
1414
1699
|
*/
|
|
1415
1700
|
finalize(paymentIntentId: string, paid: CapturedPayment): Promise<FinalizeResult>;
|
|
1416
|
-
|
|
1701
|
+
/**
|
|
1702
|
+
* Cancels an order and gives back the stock it still holds, in one transaction under the order's row lock. `actor`
|
|
1703
|
+
* names who cancelled in the order's history.
|
|
1704
|
+
*/
|
|
1705
|
+
cancel(orderId: string, reason: string, actor?: string): Promise<Order>;
|
|
1417
1706
|
}
|
|
1418
1707
|
/** The admin's side of a checkout: a payment taken outside the store. */
|
|
1419
1708
|
interface ManualPayments {
|
|
@@ -1434,6 +1723,8 @@ interface CreateCheckoutServiceDeps {
|
|
|
1434
1723
|
inventory: InventoryService;
|
|
1435
1724
|
payments: PaymentsAdapter;
|
|
1436
1725
|
currency: string;
|
|
1726
|
+
/** How long a checkout's order key opens the order on its own; 48 hours when not given. */
|
|
1727
|
+
keyLifetimeMs?: number;
|
|
1437
1728
|
}
|
|
1438
1729
|
declare function createCheckoutService(deps: CreateCheckoutServiceDeps): CheckoutService & ManualPayments;
|
|
1439
1730
|
|
|
@@ -1486,7 +1777,10 @@ interface Settlement {
|
|
|
1486
1777
|
}
|
|
1487
1778
|
/** The provider's answer settles a refund row as succeeded only when it is for the row's amount and currency. */
|
|
1488
1779
|
declare function settlementOf(answer: Refund, row: Pick<OrderRefund, 'amountMinor' | 'currency'>): Settlement;
|
|
1489
|
-
/**
|
|
1780
|
+
/**
|
|
1781
|
+
* Writes `refunded_minor` as Σ of the order's succeeded refunds, when that moves it: a refund that moved no money (failed
|
|
1782
|
+
* or still pending) leaves the order row as it was, so it needs no order event. The caller holds the order's lock.
|
|
1783
|
+
*/
|
|
1490
1784
|
declare function refreshRefunded(repos: Repositories, tx: Tx, orderId: string, at: Date): Promise<{
|
|
1491
1785
|
refunds: OrderRefund[];
|
|
1492
1786
|
refundedMinor: number;
|
|
@@ -1509,9 +1803,129 @@ interface RecentlyViewedService {
|
|
|
1509
1803
|
}
|
|
1510
1804
|
declare function createRecentlyViewedService(deps: RecentlyViewedServiceDeps): RecentlyViewedService;
|
|
1511
1805
|
|
|
1806
|
+
/** The order statuses that make a review verified: the order was paid and not wholly refunded or cancelled. */
|
|
1807
|
+
declare const REVIEW_VERIFYING_STATUSES: readonly OrderStatus[];
|
|
1808
|
+
interface ReviewSubmitInput {
|
|
1809
|
+
customerId: string;
|
|
1810
|
+
productId: string;
|
|
1811
|
+
rating: number;
|
|
1812
|
+
title: string;
|
|
1813
|
+
body: string;
|
|
1814
|
+
}
|
|
1815
|
+
interface ReviewService {
|
|
1816
|
+
/**
|
|
1817
|
+
* Files the signed-in customer's review of an active product through the reviews adapter, as theirs and verified
|
|
1818
|
+
* by their newest paid order holding the product, and publishes `review.submitted.v1` for what the adapter stored.
|
|
1819
|
+
*/
|
|
1820
|
+
submit(input: ReviewSubmitInput): Promise<Review>;
|
|
1821
|
+
}
|
|
1822
|
+
interface ReviewServiceDeps {
|
|
1823
|
+
store: CommandStore;
|
|
1824
|
+
repos: Pick<Repositories, 'product' | 'customer' | 'order'>;
|
|
1825
|
+
publisher: EventPublisher;
|
|
1826
|
+
reviews: ReviewsAdapter;
|
|
1827
|
+
logger: Logger;
|
|
1828
|
+
}
|
|
1829
|
+
declare function createReviewService(deps: ReviewServiceDeps): ReviewService;
|
|
1830
|
+
|
|
1831
|
+
/** A command tool's call, admitted by its route's gate and schema, as the proposal it is kept as. */
|
|
1832
|
+
interface Proposal {
|
|
1833
|
+
tool: string;
|
|
1834
|
+
command: string;
|
|
1835
|
+
/** The arguments as sent, less the idempotency key and the handles. */
|
|
1836
|
+
args: Record<string, unknown>;
|
|
1837
|
+
/** Argument name to value, for the handles the call carried (a cart). */
|
|
1838
|
+
handles?: Record<string, string>;
|
|
1839
|
+
idempotencyKey?: string;
|
|
1840
|
+
caller: Caller;
|
|
1841
|
+
correlationId: string;
|
|
1842
|
+
at: string;
|
|
1843
|
+
}
|
|
1844
|
+
/** What a proposal's route answered when it ran: the tool's result, and the status and error it was answered with. */
|
|
1845
|
+
interface Executed {
|
|
1846
|
+
result: ToolResult;
|
|
1847
|
+
outcome: {
|
|
1848
|
+
status: number;
|
|
1849
|
+
code?: string;
|
|
1850
|
+
message?: string;
|
|
1851
|
+
};
|
|
1852
|
+
}
|
|
1853
|
+
/** Who approves a command at the call, or null when an admin must. */
|
|
1854
|
+
type Policy = (command: string) => ProposalDecider | null;
|
|
1855
|
+
/**
|
|
1856
|
+
* The policy `agents` sets. `writes: 'apply'` approves every command; `autoApprove` the commands it names, each of
|
|
1857
|
+
* which must be a route's command that moves no money (`provider`), or createApp stops.
|
|
1858
|
+
*/
|
|
1859
|
+
declare function policyOf(agents: NymbalConfig['agents']): Policy;
|
|
1860
|
+
|
|
1861
|
+
interface ProposalServiceDeps {
|
|
1862
|
+
store: CommandStore;
|
|
1863
|
+
proposals: ProposalRepository;
|
|
1864
|
+
publisher: EventPublisher;
|
|
1865
|
+
/** Runs a stored proposal's request through its route as `auth`. */
|
|
1866
|
+
execute(row: ProposalRecord, auth: RequestAuth | undefined): Promise<Executed>;
|
|
1867
|
+
}
|
|
1868
|
+
interface ProposalService {
|
|
1869
|
+
/** Keeps a proposal pending; a proposer's repeat under one idempotency key answers the row it already has. */
|
|
1870
|
+
propose(p: Proposal): Promise<ProposalView>;
|
|
1871
|
+
/** Approves a pending proposal and runs it as the approving admin; answers the settled row. */
|
|
1872
|
+
approve(id: string, by: RequestAuth): Promise<ProposalView>;
|
|
1873
|
+
reject(id: string, by: RequestAuth, reason?: string): Promise<ProposalView>;
|
|
1874
|
+
/** Approves a pending proposal by a policy and runs it as `executor`, answering what its route answered. */
|
|
1875
|
+
run(id: string, by: ProposalDecider, executor: RequestAuth | undefined): Promise<Executed>;
|
|
1876
|
+
get(id: string): Promise<ProposalView | null>;
|
|
1877
|
+
list(q: ProposalQuery): Promise<ProposalPage>;
|
|
1878
|
+
}
|
|
1879
|
+
/**
|
|
1880
|
+
* Proposals as rows a person or a policy decides. A decision is one conditional update, so of two deciders one wins
|
|
1881
|
+
* and the other is told the status it lost to. The command runs between the decision and the settlement, in no
|
|
1882
|
+
* transaction of this service's: a provider command commits its own steps around the money it moves.
|
|
1883
|
+
*/
|
|
1884
|
+
declare function createProposalService(deps: ProposalServiceDeps): ProposalService;
|
|
1885
|
+
|
|
1886
|
+
/** A record already gone is `absent`, not an error, so a removal stopped half way can run again. */
|
|
1887
|
+
type RemovalOutcome = 'removed' | 'absent';
|
|
1888
|
+
/** What the store did on its own since an import began: orders and reviews no import created. */
|
|
1889
|
+
interface StoreActivity {
|
|
1890
|
+
/** Orders not held, created since; and held orders that have been shipped, refunded or given a key since. */
|
|
1891
|
+
orders: number;
|
|
1892
|
+
/** Reviews not held, submitted since. */
|
|
1893
|
+
reviews: number;
|
|
1894
|
+
}
|
|
1895
|
+
/**
|
|
1896
|
+
* Takes records an import created back out of the store. Each removal is one transaction under its own audit entry.
|
|
1897
|
+
* Products and categories go through their own services' `delete`.
|
|
1898
|
+
*/
|
|
1899
|
+
interface ImportRemovalService {
|
|
1900
|
+
/** Deletes the order with its history, refunds, access keys and shipment, and publishes `order.deleted.v1`. */
|
|
1901
|
+
removeOrder(id: string): Promise<RemovalOutcome>;
|
|
1902
|
+
/** Deletes the customer and its refresh tokens, and publishes `customer.deleted.v1`. */
|
|
1903
|
+
removeCustomer(id: string): Promise<RemovalOutcome>;
|
|
1904
|
+
/** Deletes the review row; as a submission publishes nothing, neither does this. */
|
|
1905
|
+
removeReview(id: string): Promise<RemovalOutcome>;
|
|
1906
|
+
activitySince(since: string, held: {
|
|
1907
|
+
orders: string[];
|
|
1908
|
+
reviews: string[];
|
|
1909
|
+
}): Promise<StoreActivity>;
|
|
1910
|
+
}
|
|
1911
|
+
interface ImportRemovalServiceDeps {
|
|
1912
|
+
store: CommandStore;
|
|
1913
|
+
repos: Repositories;
|
|
1914
|
+
publisher: EventPublisher;
|
|
1915
|
+
logger: Logger;
|
|
1916
|
+
}
|
|
1917
|
+
declare function createImportRemovalService(deps: ImportRemovalServiceDeps): ImportRemovalService;
|
|
1918
|
+
|
|
1512
1919
|
/** A confirm or unsubscribe link's bearer credential: 32 random bytes, base64url (43 characters). */
|
|
1513
1920
|
declare function newAlertToken(): string;
|
|
1514
1921
|
|
|
1922
|
+
/**
|
|
1923
|
+
* A product description as the store keeps it: an HTML fragment of the allowlisted tags, links only to http(s) and
|
|
1924
|
+
* mailto with `rel="nofollow noopener noreferrer"`, no other attribute, and text `<` and `&` written as entities.
|
|
1925
|
+
* Sanitising its own output changes nothing.
|
|
1926
|
+
*/
|
|
1927
|
+
declare function sanitizeDescription(html: string): string;
|
|
1928
|
+
|
|
1515
1929
|
/** A `native` email adapter only logs; any other (`smtp`, a project's own) is taken to reach a mailbox. */
|
|
1516
1930
|
declare function emailDelivers(email: EmailAdapter): boolean;
|
|
1517
1931
|
interface ServiceRegistry {
|
|
@@ -1527,6 +1941,9 @@ interface ServiceRegistry {
|
|
|
1527
1941
|
search: SearchService;
|
|
1528
1942
|
recentlyViewed: RecentlyViewedService;
|
|
1529
1943
|
alert: AlertService;
|
|
1944
|
+
review: ReviewService;
|
|
1945
|
+
proposals: ProposalService;
|
|
1946
|
+
importRemoval: ImportRemovalService;
|
|
1530
1947
|
}
|
|
1531
1948
|
interface BuildServicesDeps {
|
|
1532
1949
|
config: NymbalConfig;
|
|
@@ -1537,6 +1954,11 @@ interface BuildServicesDeps {
|
|
|
1537
1954
|
payments: PaymentsAdapter;
|
|
1538
1955
|
searchAdapter: SearchAdapter;
|
|
1539
1956
|
email: EmailAdapter;
|
|
1957
|
+
reviews: ReviewsAdapter;
|
|
1958
|
+
/** The effective JWT secret (`resolveAuthSecret`), not the config's field. */
|
|
1959
|
+
jwtSecret: string;
|
|
1960
|
+
/** Runs a stored proposal through its route: the tool surface `attachHttp` builds. */
|
|
1961
|
+
executeProposal: ProposalServiceDeps['execute'];
|
|
1540
1962
|
}
|
|
1541
1963
|
declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
|
|
1542
1964
|
|
|
@@ -1546,7 +1968,10 @@ interface DeclaredSlot {
|
|
|
1546
1968
|
provider: string;
|
|
1547
1969
|
declared: readonly AdapterSetting[];
|
|
1548
1970
|
}
|
|
1549
|
-
/**
|
|
1971
|
+
/**
|
|
1972
|
+
* A store from before migration 0008 has no `settings` relation: it holds no settings. drizzle wraps a node-postgres
|
|
1973
|
+
* error in its own, the driver's as `cause`; better-sqlite3's arrive unwrapped.
|
|
1974
|
+
*/
|
|
1550
1975
|
declare function isMissingSettingsTable(error: unknown): boolean;
|
|
1551
1976
|
|
|
1552
1977
|
interface RegisterAllRoutesDeps {
|
|
@@ -1560,8 +1985,12 @@ interface RegisterAllRoutesDeps {
|
|
|
1560
1985
|
publisher: EventPublisher;
|
|
1561
1986
|
/** The slots whose provider packages declare settings, as the store booted with them. */
|
|
1562
1987
|
settingsSlots: readonly DeclaredSlot[];
|
|
1988
|
+
/** The effective JWT secret (`resolveAuthSecret`), which signs the event-stream ticket as it signs tokens. */
|
|
1989
|
+
jwtSecret: string;
|
|
1563
1990
|
/** The admin's dist directory, or null for a 404 that says how to build it; undefined serves no admin. */
|
|
1564
1991
|
adminRoot?: string | null | undefined;
|
|
1992
|
+
/** The tools the admin's assistant runs, built over these routes once they are registered. */
|
|
1993
|
+
assistantTools: () => ToolSurface | undefined;
|
|
1565
1994
|
}
|
|
1566
1995
|
declare function registerAllRoutes(deps: RegisterAllRoutesDeps): void;
|
|
1567
1996
|
|
|
@@ -1591,9 +2020,133 @@ interface RouteSchema {
|
|
|
1591
2020
|
* the service commits its own steps around the provider call, so what it holds is committed before money moves.
|
|
1592
2021
|
*/
|
|
1593
2022
|
provider?: true;
|
|
2023
|
+
/**
|
|
2024
|
+
* Kept from agents: the route mints or clears credentials, streams, takes provider-signed bytes, serves files,
|
|
2025
|
+
* records a browser's views or spends the store's AI key.
|
|
2026
|
+
*/
|
|
2027
|
+
tool?: false;
|
|
2028
|
+
/**
|
|
2029
|
+
* The cookies a route reads its caller's state from, as the tool arguments that carry it instead: argument name to
|
|
2030
|
+
* cookie name. An agent holds no cookie jar, so the cart travels as a `cart` handle.
|
|
2031
|
+
*/
|
|
2032
|
+
handles?: Record<string, string>;
|
|
2033
|
+
/**
|
|
2034
|
+
* The customer fields a read's answer can carry. The assistant sends a tool's result to the AI provider as it is, so
|
|
2035
|
+
* `agents.assistant.customerData: false` leaves every marked route off the assistant, and the docs list them.
|
|
2036
|
+
*/
|
|
2037
|
+
personal?: readonly PersonalField[];
|
|
1594
2038
|
}
|
|
2039
|
+
/** A customer field a route's answer can carry. */
|
|
2040
|
+
type PersonalField = 'email' | 'phone' | 'address';
|
|
1595
2041
|
declare const routeSchemas: Record<string, RouteSchema>;
|
|
1596
2042
|
|
|
2043
|
+
/**
|
|
2044
|
+
* The refusal for a caller who fails a route's gate, or null when the caller passes it. `scope` is the least caller
|
|
2045
|
+
* it admits: `customer` for any signed-in user, a role's name for that role.
|
|
2046
|
+
*/
|
|
2047
|
+
type Gate = ((ctx: RequestContext) => ResponseEnvelope | null) & {
|
|
2048
|
+
readonly scope?: 'customer' | Role;
|
|
2049
|
+
};
|
|
2050
|
+
|
|
2051
|
+
type Scope = ToolDefinition['scope'];
|
|
2052
|
+
interface RecordedRoute {
|
|
2053
|
+
/** The handler as the HTTP adapter runs it: gate, schema, correlation, audit and idempotency composed. */
|
|
2054
|
+
handler: RouteHandler;
|
|
2055
|
+
gate: Gate | undefined;
|
|
2056
|
+
scope: Scope;
|
|
2057
|
+
}
|
|
2058
|
+
/** Every route `registerAllRoutes` registered, by `"<METHOD> <path>"`; stream routes are not tools and not kept. */
|
|
2059
|
+
declare class RouteTable {
|
|
2060
|
+
#private;
|
|
2061
|
+
record(key: string, handler: RouteHandler): void;
|
|
2062
|
+
get(key: string): RecordedRoute | undefined;
|
|
2063
|
+
keys(): string[];
|
|
2064
|
+
}
|
|
2065
|
+
/** The innermost adapter of the route chain: it keeps each composed handler in `table`, then registers it. */
|
|
2066
|
+
declare function recordingAdapter(table: RouteTable, adapter: HttpAdapter): HttpAdapter;
|
|
2067
|
+
|
|
2068
|
+
/** `admin.products.create` → `admin_products_create`: not every model API that lists MCP tools accepts a dot. */
|
|
2069
|
+
declare function toolName(dotted: string): string;
|
|
2070
|
+
/**
|
|
2071
|
+
* One JSON Schema object for a route's input: the keys of its params, query and body side by side, each as the route
|
|
2072
|
+
* parses it. A key two parts share would make the call ambiguous, so it is refused.
|
|
2073
|
+
*/
|
|
2074
|
+
declare function jsonSchemaOf(entry: RouteSchema): JsonSchemaObject;
|
|
2075
|
+
/**
|
|
2076
|
+
* The agent tools of the routes in `table`: one per route the registry does not keep from agents (`tool: false`).
|
|
2077
|
+
* Stream routes are never in the table.
|
|
2078
|
+
*/
|
|
2079
|
+
declare function toolsOf(table: RouteTable): ToolDefinition[];
|
|
2080
|
+
|
|
2081
|
+
interface InvokerDeps {
|
|
2082
|
+
table: RouteTable;
|
|
2083
|
+
tools: ToolDefinition[];
|
|
2084
|
+
proposals: Pick<ProposalService, 'propose' | 'run'>;
|
|
2085
|
+
policy: Policy;
|
|
2086
|
+
logger: Logger;
|
|
2087
|
+
}
|
|
2088
|
+
/** The tool surface, and how a stored proposal is run through its route (for the proposal service, not for agents). */
|
|
2089
|
+
interface Invoker extends ToolSurface {
|
|
2090
|
+
execute(row: ProposalRecord, auth: RequestAuth | undefined): Promise<Executed>;
|
|
2091
|
+
}
|
|
2092
|
+
/**
|
|
2093
|
+
* Runs agent tools as the routes they are: each call is a request built from the arguments and handed to the
|
|
2094
|
+
* composed handler the HTTP adapter runs, so the gate, the schema, correlation, audit and idempotency hold for it as
|
|
2095
|
+
* for a request over HTTP. A command tool stops after the gate and the schema and becomes a proposal: an admin's is
|
|
2096
|
+
* kept for an admin to decide, a shopper's only when a policy approves it, and one a policy approves runs at once.
|
|
2097
|
+
*/
|
|
2098
|
+
declare function createInvoker(deps: InvokerDeps): Invoker;
|
|
2099
|
+
|
|
2100
|
+
/** The agent name every tool call, proposal and audit entry of the assistant carries. */
|
|
2101
|
+
declare const ASSISTANT_AGENT = "nymbal-assistant";
|
|
2102
|
+
interface AssistantDeps {
|
|
2103
|
+
ai: AiAdapter;
|
|
2104
|
+
/** The tools as the assistant runs them: writes become proposals unless `agents.autoApprove` lists them. */
|
|
2105
|
+
tools: ToolSurface;
|
|
2106
|
+
proposals: Pick<ProposalService, 'get'>;
|
|
2107
|
+
logger: Logger;
|
|
2108
|
+
/** The store's name and currency, for the model's instructions. */
|
|
2109
|
+
store?: {
|
|
2110
|
+
name: string;
|
|
2111
|
+
currency: string;
|
|
2112
|
+
};
|
|
2113
|
+
limits?: {
|
|
2114
|
+
maxSteps?: number;
|
|
2115
|
+
turnMs?: number;
|
|
2116
|
+
resultChars?: number;
|
|
2117
|
+
};
|
|
2118
|
+
/** `agents.assistant.customerData`: false leaves out every tool whose answer carries a customer's details. */
|
|
2119
|
+
customerData?: boolean;
|
|
2120
|
+
}
|
|
2121
|
+
interface AssistantTurn {
|
|
2122
|
+
/** The turn's id, the prefix of each call's correlation id; one is minted when absent. */
|
|
2123
|
+
turnId?: string;
|
|
2124
|
+
/** The signed-in admin, as agent `nymbal-assistant`. */
|
|
2125
|
+
caller: Caller;
|
|
2126
|
+
/** The conversation so far as the admin's browser holds it; the last turn is the question. */
|
|
2127
|
+
messages: Array<{
|
|
2128
|
+
role: 'user' | 'assistant';
|
|
2129
|
+
content: string;
|
|
2130
|
+
}>;
|
|
2131
|
+
/** The admin route the panel was opened on, e.g. `/products/ceramic-mug`. */
|
|
2132
|
+
page?: string;
|
|
2133
|
+
}
|
|
2134
|
+
type Stream = NonNullable<AiAdapter['chatStream']>;
|
|
2135
|
+
/**
|
|
2136
|
+
* The adapter's own `chatStream`, or for an adapter with only `chat` its answer as one text event, its calls and
|
|
2137
|
+
* `done`, so an ai adapter that cannot stream still runs the assistant. A result without `toolCalls` (an adapter of the
|
|
2138
|
+
* older contract) is read as one with none.
|
|
2139
|
+
*/
|
|
2140
|
+
declare function streamOf(ai: AiAdapter): Stream;
|
|
2141
|
+
/**
|
|
2142
|
+
* One assistant turn: the model is called with the store's tools, each tool it asks for runs through the tool surface
|
|
2143
|
+
* as the admin, and its result goes back to it, until it answers without calls. `emit` receives every frame; the turn
|
|
2144
|
+
* ends with one `done` or one `error` frame, or with none when `signal` aborts (the merchant has gone). It is bounded by
|
|
2145
|
+
* `maxSteps` model requests, `turnMs`, ten calls per reply, ten writes and 64 000 characters of results. Each call
|
|
2146
|
+
* carries its own correlation id, `<turnId>.<n>`, and logs one line without its arguments or result.
|
|
2147
|
+
*/
|
|
2148
|
+
declare function runAssistantTurn(deps: AssistantDeps, turn: AssistantTurn, emit: (frame: AssistantFrame) => void, signal?: AbortSignal): Promise<void>;
|
|
2149
|
+
|
|
1597
2150
|
interface NymbalApp {
|
|
1598
2151
|
platform: Platform;
|
|
1599
2152
|
repos: Repositories;
|
|
@@ -1602,11 +2155,22 @@ interface NymbalApp {
|
|
|
1602
2155
|
publisher: EventPublisher;
|
|
1603
2156
|
/** Delivers the event log to the bus; started by createApp, stopped by stop(). */
|
|
1604
2157
|
relay: Relay;
|
|
2158
|
+
/**
|
|
2159
|
+
* The trusted proxies, client-address header and origin lock, resolved once from the environment, the config and the
|
|
2160
|
+
* security adapter's contribution: the block every HTTP server for this app is built with.
|
|
2161
|
+
*/
|
|
2162
|
+
network: ResolvedNetwork;
|
|
1605
2163
|
/**
|
|
1606
2164
|
* Registers the API on the adapter. The admin is served at /admin/ when `adminRoot` is passed (its dist directory,
|
|
1607
2165
|
* or null for a 404 that says how to build it) or `NYMBAL_ADMIN_DIST` is set.
|
|
1608
2166
|
*/
|
|
1609
2167
|
attachHttp(adapter: HttpAdapter, options?: AttachHttpOptions): Promise<void>;
|
|
2168
|
+
/** The API's routes as agent tools, run in process through the handlers `attachHttp` registered; set by it. */
|
|
2169
|
+
readonly mcp: ToolSurface | undefined;
|
|
2170
|
+
/** The routes as the admin's assistant runs them: as `mcp`, but only `agents.autoApprove` applies a write. */
|
|
2171
|
+
readonly assistantTools: ToolSurface | undefined;
|
|
2172
|
+
/** The agent surfaces (UCP) and crawl files, over `mcp`; set by `attachHttp` once `mcp` is. */
|
|
2173
|
+
readonly agents: AgentSurfaces | undefined;
|
|
1610
2174
|
/** Each slot's provider and its adapter's own `capabilities()`; an ai slot of `none` offers nothing. */
|
|
1611
2175
|
capabilities(): CapabilitiesReport;
|
|
1612
2176
|
stop(): Promise<void>;
|
|
@@ -1626,9 +2190,203 @@ interface CreateAppOptions extends ResolvePrimitivesOptions {
|
|
|
1626
2190
|
adapters?: InjectedAdapters;
|
|
1627
2191
|
/** How the event relay retries a failed delivery (`createRelay`). */
|
|
1628
2192
|
relay?: Pick<CreateRelayOptions, 'maxAttempts' | 'retryDelayMs' | 'intervalMs' | 'now'>;
|
|
2193
|
+
/** How often expired and used refresh tokens are deleted; tests shorten it. */
|
|
2194
|
+
refreshTokenSweep?: {
|
|
2195
|
+
intervalMs?: number;
|
|
2196
|
+
};
|
|
1629
2197
|
}
|
|
1630
2198
|
declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
|
|
1631
2199
|
|
|
2200
|
+
type GoldenKind = 'read' | 'write' | 'none';
|
|
2201
|
+
/** A fact the answer must hold: a text, or any one of several (an amount in the store's format, or as digits). */
|
|
2202
|
+
type GoldenFact = string | readonly string[];
|
|
2203
|
+
/** The orders the golden store places, by the part each plays in a question. */
|
|
2204
|
+
type GoldenOrderPart = 'placed' | 'unpaid' | 'waiting' | 'refunded' | 'paid';
|
|
2205
|
+
interface GoldenOrder {
|
|
2206
|
+
id: string;
|
|
2207
|
+
orderNumber: string;
|
|
2208
|
+
email: string;
|
|
2209
|
+
capturedMinor: number;
|
|
2210
|
+
refundedMinor: number;
|
|
2211
|
+
}
|
|
2212
|
+
/** The golden store as a question reads it, at the moment the question is asked. */
|
|
2213
|
+
interface GoldenStoreView {
|
|
2214
|
+
currency: string;
|
|
2215
|
+
/** A read tool's result, run as the admin. */
|
|
2216
|
+
read(tool: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
2217
|
+
order(part: GoldenOrderPart): Promise<GoldenOrder>;
|
|
2218
|
+
/** A seeded product's id and its first variant's id, by slug. */
|
|
2219
|
+
product(slug: string): Promise<{
|
|
2220
|
+
id: string;
|
|
2221
|
+
variantId: string;
|
|
2222
|
+
}>;
|
|
2223
|
+
money(minor: number): GoldenFact;
|
|
2224
|
+
}
|
|
2225
|
+
interface GoldenProposal {
|
|
2226
|
+
tool: string;
|
|
2227
|
+
argsMatch(args: Record<string, unknown>, store: GoldenStoreView): boolean | Promise<boolean>;
|
|
2228
|
+
}
|
|
2229
|
+
interface GoldenQuestion {
|
|
2230
|
+
id: string;
|
|
2231
|
+
/** What the merchant asks; `{order:<part>}` is the number of the golden store's order for that part. */
|
|
2232
|
+
ask: string;
|
|
2233
|
+
/** The admin page the panel is opened on. */
|
|
2234
|
+
page?: string;
|
|
2235
|
+
kind: GoldenKind;
|
|
2236
|
+
/** Tools the answer must call; `a|b` is either. */
|
|
2237
|
+
calls?: string[];
|
|
2238
|
+
/** Tools it must never call. */
|
|
2239
|
+
never?: string[];
|
|
2240
|
+
/** For a write: exactly these proposals, left pending. */
|
|
2241
|
+
proposals?: GoldenProposal[];
|
|
2242
|
+
/** The facts the answer must hold, read from the store when the question is asked. */
|
|
2243
|
+
answer?: (store: GoldenStoreView) => Promise<GoldenFact[]>;
|
|
2244
|
+
/** The answer reads text a shopper or an import wrote that asks for a write the merchant did not. */
|
|
2245
|
+
injection?: boolean;
|
|
2246
|
+
}
|
|
2247
|
+
declare const GOLDEN_QUESTIONS: readonly GoldenQuestion[];
|
|
2248
|
+
/**
|
|
2249
|
+
* Fills an empty store with what the golden questions ask about, through its services: the demo seed, five orders
|
|
2250
|
+
* (two unpaid, three paid by the native payments stub, one of those partly refunded) and one pending proposal, and the
|
|
2251
|
+
* injected text: a pending review of the Stoneware Mug, checkout notes on the placed order and Shape Up's description.
|
|
2252
|
+
*/
|
|
2253
|
+
declare function goldenStore(app: NymbalApp): Promise<void>;
|
|
2254
|
+
|
|
2255
|
+
interface GoldenResult {
|
|
2256
|
+
id: string;
|
|
2257
|
+
/** The question as asked, its order numbers filled in. */
|
|
2258
|
+
ask: string;
|
|
2259
|
+
ok: boolean;
|
|
2260
|
+
/** Why it failed, one line per check; empty when it passed. */
|
|
2261
|
+
reasons: string[];
|
|
2262
|
+
/** The tools the assistant called, in order. */
|
|
2263
|
+
calls: string[];
|
|
2264
|
+
/** The ids of the proposals the turn made. */
|
|
2265
|
+
proposals: string[];
|
|
2266
|
+
answer: string;
|
|
2267
|
+
}
|
|
2268
|
+
interface GoldenReport {
|
|
2269
|
+
passed: number;
|
|
2270
|
+
total: number;
|
|
2271
|
+
results: GoldenResult[];
|
|
2272
|
+
}
|
|
2273
|
+
interface RunGoldenOptions {
|
|
2274
|
+
/** Question ids to run; all of them when omitted. */
|
|
2275
|
+
only?: string[];
|
|
2276
|
+
onResult?: (result: GoldenResult) => void;
|
|
2277
|
+
}
|
|
2278
|
+
/**
|
|
2279
|
+
* Asks each golden question of the store's assistant, one conversation each, as the seeded admin on the golden store
|
|
2280
|
+
* (`goldenStore`), and checks what it called, what it proposed, what it changed and what it answered.
|
|
2281
|
+
*/
|
|
2282
|
+
declare function runGolden(app: NymbalApp, opts?: RunGoldenOptions): Promise<GoldenReport>;
|
|
2283
|
+
|
|
2284
|
+
/** The Universal Commerce Protocol release this store speaks. */
|
|
2285
|
+
declare const UCP_VERSION = "2026-08-25";
|
|
2286
|
+
/**
|
|
2287
|
+
* The business profile served at `/.well-known/ucp`: one shopping service over MCP and the catalogue and checkout
|
|
2288
|
+
* capabilities. Payment happens on the store's own checkout page, so it names no payment handler. Every URL is built
|
|
2289
|
+
* from the configured origins, so no request header can change a cached copy.
|
|
2290
|
+
*/
|
|
2291
|
+
declare function ucpProfile(urls: AgentSurfaceUrls): Record<string, unknown>;
|
|
2292
|
+
|
|
2293
|
+
/**
|
|
2294
|
+
* The name a UCP call travels under: the host of the platform profile its `meta` names, else the MCP client's name,
|
|
2295
|
+
* else `mcp-client`. Both arguments come from the agent, so anything malformed falls through rather than throws.
|
|
2296
|
+
*/
|
|
2297
|
+
declare function agentNameOf(meta: unknown, clientInfo: unknown): string;
|
|
2298
|
+
|
|
2299
|
+
interface UcpLink {
|
|
2300
|
+
type: string;
|
|
2301
|
+
url: string;
|
|
2302
|
+
title?: string | undefined;
|
|
2303
|
+
}
|
|
2304
|
+
|
|
2305
|
+
interface UcpSurfaceDeps {
|
|
2306
|
+
/** The app's route tools, which every UCP call runs through. */
|
|
2307
|
+
mcp: Pick<ToolSurface, 'call'>;
|
|
2308
|
+
/** The slug of the product a variant id belongs to, or null. */
|
|
2309
|
+
variants: (variantId: string) => Promise<string | null>;
|
|
2310
|
+
/** The live guest cart a token names, or null for an unknown, expired or customer-claimed one. */
|
|
2311
|
+
cart: (token: string) => Promise<Cart | null>;
|
|
2312
|
+
urls: () => AgentSurfaceUrls;
|
|
2313
|
+
links: readonly UcpLink[];
|
|
2314
|
+
}
|
|
2315
|
+
/**
|
|
2316
|
+
* The UCP shopping service over MCP: catalogue search and lookup, and a checkout the buyer completes on the store's
|
|
2317
|
+
* own page. Each call runs the store's routes through `mcp` as the calling agent, so their gates and schemas hold;
|
|
2318
|
+
* none runs a command tool, so nothing here places an order or moves stock.
|
|
2319
|
+
*/
|
|
2320
|
+
declare function createUcpSurface(deps: UcpSurfaceDeps): AgentSurfaceAdapter;
|
|
2321
|
+
|
|
2322
|
+
/** `ok` is a check with no health semantics (config, a package, migrations); the rest are a health report's. */
|
|
2323
|
+
type DiagnosisStatus = HealthStatus | 'ok';
|
|
2324
|
+
interface DiagnosisCheck {
|
|
2325
|
+
name: string;
|
|
2326
|
+
status: DiagnosisStatus;
|
|
2327
|
+
detail: string;
|
|
2328
|
+
}
|
|
2329
|
+
interface DiagnosisReport {
|
|
2330
|
+
checks: DiagnosisCheck[];
|
|
2331
|
+
/**
|
|
2332
|
+
* What the security adapter offers the HTTP layer (`network()`), read from the adapter built for `slot security`:
|
|
2333
|
+
* `unknown` when it failed to build or `network()` threw. Absent when the config did not parse.
|
|
2334
|
+
*/
|
|
2335
|
+
network?: {
|
|
2336
|
+
adapter: string;
|
|
2337
|
+
contribution: SecurityNetwork;
|
|
2338
|
+
} | 'unknown';
|
|
2339
|
+
/**
|
|
2340
|
+
* Whether the CDN sends the origin secret, present only when `NYMBAL_ORIGIN_SECRET` resolves: the security adapter's
|
|
2341
|
+
* answer, `unmanaged` when it cannot tell (no `originLockRule`), `unknown` when it failed to build, threw or timed out.
|
|
2342
|
+
*/
|
|
2343
|
+
originLock?: OriginLockRule | 'unknown' | 'unmanaged';
|
|
2344
|
+
}
|
|
2345
|
+
interface DiagnoseOptions {
|
|
2346
|
+
/** The project's adapters, one per slot whose provider is `custom`, as `createApp` takes them. */
|
|
2347
|
+
adapters?: InjectedAdapters;
|
|
2348
|
+
logger?: Logger;
|
|
2349
|
+
/** Each check's bound; `HEALTH_CHECK_TIMEOUT_MS` when not given. */
|
|
2350
|
+
timeoutMs?: number;
|
|
2351
|
+
env?: NodeJS.ProcessEnv;
|
|
2352
|
+
sqlitePath?: string;
|
|
2353
|
+
postgresUrl?: string;
|
|
2354
|
+
mediaRoot?: string;
|
|
2355
|
+
/** Where the migrations journal is read; the platform's own migrations when not given. */
|
|
2356
|
+
migrationsRoot?: string;
|
|
2357
|
+
}
|
|
2358
|
+
/**
|
|
2359
|
+
* Checks a project without changing it: its config, the packages its providers live in, the command store and its
|
|
2360
|
+
* migrations, and the health of every commerce slot, the security slot and every primitive. It builds what `createApp`
|
|
2361
|
+
* builds, through the same registry and constructors, and nothing more: no warm-up, no relay, no sweeper, no migrator,
|
|
2362
|
+
* no seed, and no primitive's `initialize()` (the security adapter's makes no request). The command store is opened read-only. Every connection is closed before it returns.
|
|
2363
|
+
*/
|
|
2364
|
+
declare function diagnose(input: NymbalConfig, options?: DiagnoseOptions): Promise<DiagnosisReport>;
|
|
2365
|
+
|
|
2366
|
+
/**
|
|
2367
|
+
* How ready the agent surfaces are, from the config and the environment alone. UCP checkout advertised without a
|
|
2368
|
+
* privacy and a terms link, or on a public plain-HTTP origin, is a warning; it is never `down`, because the surface
|
|
2369
|
+
* still serves and doctor's exit code belongs to the checks that stop a store.
|
|
2370
|
+
*/
|
|
2371
|
+
declare function agentReadiness(config: NymbalConfig, env: NodeJS.ProcessEnv): DiagnosisCheck;
|
|
2372
|
+
|
|
2373
|
+
interface AuthSecret {
|
|
2374
|
+
secret: string;
|
|
2375
|
+
source: 'config' | 'env' | 'default';
|
|
2376
|
+
}
|
|
2377
|
+
/**
|
|
2378
|
+
* The secret every token is signed with: the config's own, else NYMBAL_JWT_SECRET, else the schema default. Code that
|
|
2379
|
+
* names a secret wins, as it does over the environment for adapter settings. A set variable is checked first, so a
|
|
2380
|
+
* malformed one fails the boot even when the config's secret would win.
|
|
2381
|
+
*/
|
|
2382
|
+
declare function resolveAuthSecret(config: NymbalConfig, env: NodeJS.ProcessEnv): AuthSecret;
|
|
2383
|
+
/**
|
|
2384
|
+
* Whether a listen host is reachable from this machine only: 127.0.0.0/8, ::1 or localhost. The wildcards `0.0.0.0`
|
|
2385
|
+
* and `::` listen on every interface, so they are not. Any other spelling of a loopback address is treated as
|
|
2386
|
+
* reachable, which refuses more, never less.
|
|
2387
|
+
*/
|
|
2388
|
+
declare function isLoopbackHost(host: string): boolean;
|
|
2389
|
+
|
|
1632
2390
|
/**
|
|
1633
2391
|
* Serves the admin's built files at /admin/ beside /api, one origin, so its relative API URLs and the refresh cookie
|
|
1634
2392
|
* work without a proxy. `root` is the admin's dist directory, or null when none is installed: then /admin/ answers 404
|
|
@@ -1687,38 +2445,69 @@ interface EventRetentionSweeperDeps {
|
|
|
1687
2445
|
*/
|
|
1688
2446
|
declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
|
|
1689
2447
|
|
|
1690
|
-
interface
|
|
1691
|
-
|
|
1692
|
-
|
|
1693
|
-
|
|
1694
|
-
|
|
2448
|
+
interface RefreshTokenSweeperDeps {
|
|
2449
|
+
store: CommandStore;
|
|
2450
|
+
refreshTokens: RefreshTokenRepository;
|
|
2451
|
+
logger: Logger;
|
|
2452
|
+
intervalMs?: number;
|
|
2453
|
+
}
|
|
2454
|
+
/**
|
|
2455
|
+
* Deletes expired refresh tokens and rotated ones whose reuse window has ended, so the table holds about one row per
|
|
2456
|
+
* session. A purged rotated token still reads as a replay: `refresh` treats a signed token with no row as one.
|
|
2457
|
+
*/
|
|
2458
|
+
declare function startRefreshTokenSweeper(deps: RefreshTokenSweeperDeps): SweeperHandle;
|
|
2459
|
+
|
|
2460
|
+
/** What the config names for a slot: its provider, and the package the adapter comes from when it says. */
|
|
2461
|
+
interface Choice {
|
|
2462
|
+
provider: string;
|
|
2463
|
+
package?: string | undefined;
|
|
1695
2464
|
}
|
|
1696
|
-
type Packages<P extends ProviderPackage> = Readonly<Record<string, P>>;
|
|
1697
2465
|
/**
|
|
1698
|
-
*
|
|
1699
|
-
*
|
|
1700
|
-
* `local-fs`) have no entry. Every package peers its provider's SDK but the security ones, which call an HTTP API.
|
|
2466
|
+
* Where a slot's adapter comes from: the one passed to `createApp` (`custom`), the kernel's own (`built-in`), or a
|
|
2467
|
+
* package, named by the config's `package` or by the convention, `@nymbalhq/<slot>-<provider>`.
|
|
1701
2468
|
*/
|
|
1702
|
-
|
|
1703
|
-
|
|
2469
|
+
type Resolution = {
|
|
2470
|
+
kind: 'custom';
|
|
2471
|
+
} | {
|
|
2472
|
+
kind: 'built-in';
|
|
2473
|
+
} | {
|
|
2474
|
+
kind: 'package';
|
|
2475
|
+
package: string;
|
|
2476
|
+
sdk?: string;
|
|
2477
|
+
named: 'package' | 'convention';
|
|
1704
2478
|
};
|
|
2479
|
+
/** The rule every caller shares: `custom`, then a built-in, then `package`, then the convention name. */
|
|
2480
|
+
declare function resolveChoice(slot: Slot, choice: Choice): Resolution;
|
|
1705
2481
|
/** The command that installs `packages` with the project's package manager, as `packageManager` picks it. */
|
|
1706
2482
|
declare function installLine(packages: readonly string[], env: NodeJS.ProcessEnv, cwd: string): string;
|
|
1707
|
-
type ProviderModule = ProviderPackageModule;
|
|
1708
2483
|
/**
|
|
1709
|
-
* The
|
|
1710
|
-
*
|
|
1711
|
-
|
|
1712
|
-
|
|
2484
|
+
* The package Node could not find, when `error` is a missing package and not some other failure. A path (an installed
|
|
2485
|
+
* package's own missing file) is not a package to install, so it is `null` and the error stays as Node threw it.
|
|
2486
|
+
*/
|
|
2487
|
+
declare function missingPackage(error: unknown): string | null;
|
|
2488
|
+
/**
|
|
2489
|
+
* `mod` as the adapter module of `slot` and `provider`, from `pkg`: it must export `createAdapter`, `slot` equal to the
|
|
2490
|
+
* slot and, for any provider but `custom`, `provider` equal to it. A module for another slot is `adapter.wrong_slot`,
|
|
2491
|
+
* anything else wrong `adapter.package_invalid`, each naming the package, the export, the expected and actual value.
|
|
1713
2492
|
*/
|
|
1714
|
-
declare function
|
|
2493
|
+
declare function checkAdapterModule(mod: unknown, slot: Slot, provider: string, pkg: string): ProviderPackageModule;
|
|
2494
|
+
/**
|
|
2495
|
+
* The adapter module the slot's choice resolves to, imported and checked, or `undefined` for `custom` and a built-in.
|
|
2496
|
+
* The specifier is imported from the project root, `process.cwd()`. A package that is not installed is
|
|
2497
|
+
* `adapter.package_missing` with its install line, or `adapter.provider_unknown` (with a suggestion when one is near)
|
|
2498
|
+
* for a convention name no first-party package has; an adapter that resolves another copy of @nymbalhq/types than the
|
|
2499
|
+
* kernel's is `adapter.types_duplicate`; any other load error is rethrown as it is.
|
|
2500
|
+
*/
|
|
2501
|
+
declare function importAdapterModule(slot: Slot, choice: Choice, env: NodeJS.ProcessEnv, importer?: (specifier: string) => Promise<unknown>): Promise<ProviderPackageModule | undefined>;
|
|
2502
|
+
/** The fields a provider package lets Settings fill: its `settings` export, or none. */
|
|
2503
|
+
declare function declaredSettings(mod: ProviderPackageModule | undefined): readonly AdapterSetting[];
|
|
1715
2504
|
|
|
1716
2505
|
/**
|
|
1717
2506
|
* v0.1 security adapter.
|
|
1718
2507
|
*
|
|
1719
|
-
* Rate limiting
|
|
1720
|
-
*
|
|
1721
|
-
*
|
|
2508
|
+
* Rate limiting and CSRF verification need the request before any middleware, so the
|
|
2509
|
+
* HTTP adapter runs them itself on every route (`FastifyHttpAdapter`'s guard); only
|
|
2510
|
+
* `GET /api/csrf` mints the CSRF cookie. This adapter only asserts
|
|
1722
2511
|
* static security headers via `HttpAdapter.setDefaultHeaders(...)`. A future
|
|
1723
2512
|
* WAF-native adapter will replace both layers.
|
|
1724
2513
|
*/
|
|
@@ -1754,7 +2543,7 @@ declare function createNativeStubPaymentsAdapter(deps: {
|
|
|
1754
2543
|
logger: Logger;
|
|
1755
2544
|
}): PaymentsAdapter;
|
|
1756
2545
|
|
|
1757
|
-
/** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/
|
|
2546
|
+
/** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/email-smtp). */
|
|
1758
2547
|
interface NativeEmailAdapterConfig {
|
|
1759
2548
|
transport?: 'console';
|
|
1760
2549
|
from?: string;
|
|
@@ -1783,7 +2572,8 @@ declare function createNativeReviewsAdapter(deps: {
|
|
|
1783
2572
|
|
|
1784
2573
|
declare function createNativeAnalyticsAdapter(logger: Logger): AnalyticsAdapter;
|
|
1785
2574
|
|
|
1786
|
-
|
|
2575
|
+
/** The store ships by hand: no rates, labels or tracking registration, so no word and none of their methods. */
|
|
2576
|
+
declare function createNativeShippingAdapter(_logger: Logger): ShippingAdapter;
|
|
1787
2577
|
|
|
1788
2578
|
declare function createNativeTaxAdapter(logger: Logger, defaultRate?: number): TaxAdapter;
|
|
1789
2579
|
|
|
@@ -1796,37 +2586,6 @@ interface CreateLoggerOptions {
|
|
|
1796
2586
|
}
|
|
1797
2587
|
declare function createLogger(options?: CreateLoggerOptions): Logger;
|
|
1798
2588
|
|
|
1799
|
-
/** `ok` is a check with no health semantics (config, a package, migrations); the rest are a health report's. */
|
|
1800
|
-
type DiagnosisStatus = HealthStatus | 'ok';
|
|
1801
|
-
interface DiagnosisCheck {
|
|
1802
|
-
name: string;
|
|
1803
|
-
status: DiagnosisStatus;
|
|
1804
|
-
detail: string;
|
|
1805
|
-
}
|
|
1806
|
-
interface DiagnosisReport {
|
|
1807
|
-
checks: DiagnosisCheck[];
|
|
1808
|
-
}
|
|
1809
|
-
interface DiagnoseOptions {
|
|
1810
|
-
/** The project's adapters, one per slot whose provider is `custom`, as `createApp` takes them. */
|
|
1811
|
-
adapters?: InjectedAdapters;
|
|
1812
|
-
logger?: Logger;
|
|
1813
|
-
/** Each check's bound; `HEALTH_CHECK_TIMEOUT_MS` when not given. */
|
|
1814
|
-
timeoutMs?: number;
|
|
1815
|
-
env?: NodeJS.ProcessEnv;
|
|
1816
|
-
sqlitePath?: string;
|
|
1817
|
-
postgresUrl?: string;
|
|
1818
|
-
mediaRoot?: string;
|
|
1819
|
-
/** Where the migrations journal is read; the platform's own migrations when not given. */
|
|
1820
|
-
migrationsRoot?: string;
|
|
1821
|
-
}
|
|
1822
|
-
/**
|
|
1823
|
-
* Checks a project without changing it: its config, the packages its providers live in, the command store and its
|
|
1824
|
-
* migrations, and the health of every commerce slot, the security slot and every primitive. It builds what `createApp`
|
|
1825
|
-
* builds, through the same registry and constructors, and nothing more: no warm-up, no relay, no sweeper, no migrator,
|
|
1826
|
-
* no seed, and no primitive's `initialize()` (the security adapter's makes no request). The command store is opened read-only. Every connection is closed before it returns.
|
|
1827
|
-
*/
|
|
1828
|
-
declare function diagnose(input: NymbalConfig, options?: DiagnoseOptions): Promise<DiagnosisReport>;
|
|
1829
|
-
|
|
1830
2589
|
interface SeedDeps {
|
|
1831
2590
|
config: NymbalConfig;
|
|
1832
2591
|
commandStore: CommandStore;
|
|
@@ -1927,6 +2686,8 @@ interface RebuildDeps {
|
|
|
1927
2686
|
table: string;
|
|
1928
2687
|
page: number;
|
|
1929
2688
|
}) => void | Promise<void>;
|
|
2689
|
+
/** Awaited once every model is collected, before a model is caught up and swapped, and after its swap. */
|
|
2690
|
+
onPhase?: (phase: 'collected' | 'swapped', model: ReadModelName) => void | Promise<void>;
|
|
1930
2691
|
}
|
|
1931
2692
|
/** What a rebuilder reads with: the command store in pages, each page a read of its own. */
|
|
1932
2693
|
interface RebuildContext {
|
|
@@ -1977,6 +2738,8 @@ interface RebuildReportEntry {
|
|
|
1977
2738
|
name: string;
|
|
1978
2739
|
documents: number;
|
|
1979
2740
|
}>;
|
|
2741
|
+
/** Logged events applied to the collected contents before the swap. */
|
|
2742
|
+
caughtUpBeforeSwap: number;
|
|
1980
2743
|
/** Logged events re-applied after the swap. */
|
|
1981
2744
|
caughtUpEvents: number;
|
|
1982
2745
|
/** Catch-up events a handler failed on: the model is swapped all the same. */
|
|
@@ -1992,8 +2755,9 @@ declare class RebuildError extends Error {
|
|
|
1992
2755
|
constructor(model: ReadModelName, cause: unknown);
|
|
1993
2756
|
}
|
|
1994
2757
|
/**
|
|
1995
|
-
* Rebuilds `names` from the command store's tables: every model is read first, then each is
|
|
1996
|
-
*
|
|
2758
|
+
* Rebuilds `names` from the command store's tables: every model is read first, then each is caught up in memory with
|
|
2759
|
+
* the events delivered since its read began, swapped in (atomically per collection) and caught up again, for the
|
|
2760
|
+
* events delivered while it was swapped. A rebuilder that throws rejects with
|
|
1997
2761
|
* a `RebuildError` before anything is swapped. Catch-up failures are in the report.
|
|
1998
2762
|
*/
|
|
1999
2763
|
declare function rebuild(names: readonly ReadModelName[], deps: RebuildDeps): Promise<RebuildReport>;
|
|
@@ -2053,5 +2817,5 @@ interface LocalFsMediaStorageOptions {
|
|
|
2053
2817
|
declare const LOCAL_FS_MEDIA_CAPABILITIES: readonly string[];
|
|
2054
2818
|
declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
|
|
2055
2819
|
|
|
2056
|
-
export { CATCH_UP_MARGIN_MS, CSRF_COOKIE, CSRF_HEADER, InMemoryDocumentStore, InProcessEventBus, LOCAL_FS_MEDIA_CAPABILITIES,
|
|
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,
|
|
2820
|
+
export { ALERT_CONFIRMATION_INTERVAL_MS, ASSISTANT_AGENT, CATCH_UP_MARGIN_MS, CSRF_COOKIE, CSRF_HEADER, GOLDEN_QUESTIONS, InMemoryDocumentStore, InProcessEventBus, LOCAL_FS_MEDIA_CAPABILITIES, PROVIDER_REFUND_REASON, READ_MODELS, READ_MODEL_NAMES, REDIS_DEFAULTS, REFRESH_REUSE_WINDOW_MS, REVIEW_VERIFYING_STATUSES, RateLimiter, RebuildError, RouteTable, SECRETS_KEY_ENV, SECRETS_KEY_OLD_ENV, UCP_VERSION, actorOf, agentNameOf, agentReadiness, appendAuditEntry, audit, auditEntriesInOrder, auditedCommand, buildAdapters, buildRepositories, buildServices, checkAdapterModule, confirmationDue, createAlertService, createAlertSubscriptionRepository, createApp, createAuditEntryRepository, createAuthService, createCartCatalogue, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createEmailSuppressionRepository, createEventBuilder, createEventLogRepository, createEventPublisher, createImportRemovalService, createInventoryReservationRepository, createInventoryService, createInvoker, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderAccessKeyRepository, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createOrderShipmentRepository, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createProposalRepository, createProposalService, createRecentlyViewedService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createReviewService, createSearchService, createSettingsRepository, createStockAdjustmentRepository, createUcpSurface, createVariantRepository, currentActor, currentCorrelationId, declaredSettings, decodeProposalCursor, decrypt, diagnose, diffReadModel, emailDelivers, encodeProposalCursor, encodeSearchCursor, encrypt, fillFromSettings, findAppliedByKey, goldenStore, importAdapterModule, installLine, isLoopbackHost, isMissingSettingsTable, isSellable, jsonSchemaOf, keyId, keyProblem, listAuditEntries, migrationState, missingPackage, newAlertToken, newCorrelationId, openReadModels, orderPayment, parseDurationToMs, policyOf, proposalView, rawClients, readSecretsKey, rebuild, recordingAdapter, refreshRefunded, registerAdminStaticRoute, registerAlertHandler, registerAlertRoutes, registerAllRoutes, registerHandlers, resolveAuthSecret, resolveChoice, resolvePrimitives, routeSchemas, runAsActor, runAssistantTurn, runGolden, runMigrations, runSeed, runWithCorrelation, sanitizeDescription, scrub, seedCategories, seedProducts, settingAad, settlementOf, sqliteFile, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, startRefreshTokenSweeper, streamOf, toolName, toolsOf, ucpProfile, withIdempotency };
|
|
2821
|
+
export type { AbandonedCart, AbandonedWindow, Actor, AdapterRegistry, AgentSourceTotals, AgentTotals, AlertConfirmed, AlertService, AlertSubscribeInput, AlertSubscription, AlertSubscriptionPatch, AlertSubscriptionRepository, AlertSubscriptionRequest, AppliedEntry, AssistantDeps, AssistantTurn, AttachHttpOptions, AuditCursor, AuditEntryInsert, AuditEntryRepository, AuditFilter, AuditQuery, AuthSecret, AuthService, AuthTokens, BeginCheckoutInput, BeginCheckoutResult, BuildAdaptersDeps, BuildServicesDeps, CapabilitiesReport, CapabilitySlot, CapturedPayment, CartCatalogue, CartRepository, CartService, CatchUpFailure, CategoryCreateInput, CategoryInsert, CategoryRepository, CategoryService, CategoryUpdate, CategoryUpdateInput, CheckoutService, Choice, CollectionDiff, CommandStore, CommandStoreOptions, CommerceAdapters, CreateAlertServiceDeps, CreateAppOptions, CreateAuthServiceDeps, CreateCartServiceDeps, CreateCheckoutServiceDeps, CreateInventoryServiceDeps, CreateLoggerOptions, CreateOrderServiceDeps, CreatePlatformOptions, CreateProductServiceDeps, CreatePublisherOptions, CreateRefundServiceDeps, CreateRelayOptions, CustomerInsert, CustomerJwtPayload, CustomerNote, CustomerOrderTotals, CustomerRepository, CustomerService, CustomerUpdate, CustomerWithHash, DiagnoseOptions, DiagnosisCheck, DiagnosisReport, DiagnosisStatus, EmailSuppressionInput, EmailSuppressionReason, EmailSuppressionRepository, EncryptedValue, EventArchiveWriter, EventBuilderContext, EventLogFilter, EventLogRepository, EventPublisher, EventRetentionSweeperDeps, Executed, FinalizeResult, GoldenFact, GoldenKind, GoldenQuestion, GoldenReport, GoldenResult, IdempotencyOptions, ImportCustomerInput, ImportRemovalService, ImportRemovalServiceDeps, InMemoryDocumentStoreOptions, InProcessEventBusOptions, InjectedAdapters, InventoryReservationRepository, InventoryService, Invoker, InvokerDeps, KeysetPage, CategoryInsert$1 as LegacyCategoryInsert, CategoryRow as LegacyCategoryRow, ProductInsert$1 as LegacyProductInsert, ProductRow as LegacyProductRow, LocalFsMediaStorageOptions, LoggedEvent, MakeEventOptions, ManualPayments, MigrateOptions, MigrationState, NativeEmailAdapterConfig, NymbalApp, OpenReadModelsOptions, OrderAccessKeyInsert, OrderAccessKeyPurpose, OrderAccessKeyRepository, OrderCapture, OrderCreateDraftInput, OrderHistoryInsert, OrderHistoryRepository, OrderImportInput, OrderInsert, OrderKeyState, OrderRefundInsert, OrderRefundRepository, OrderRepository, OrderSequenceRepository, OrderService, OrderShipmentInput, OrderShipmentRepository, Platform, PlatformConnectionOptions, Policy, PostgresClient, Primitives, ProcessedEventRepository, ProductCategoryRepository, ProductCreateInput, ProductInsert, ProductRepository, ProductService, ProductUpdate, ProductUpdateInput, ProfileUpdate, Proposal, ProposalCursor, ProposalDecision, ProposalInsert, ProposalQuery, ProposalRecord, ProposalRepository, ProposalService, ProposalServiceDeps, ProposalSettlement, PublishOptions, RawClients, ReadModel, ReadModelDiff, ReadModelName, ReadTx, RebuildDeps, RebuildReport, RebuildReportEntry, RecentlyViewedService, RecentlyViewedServiceDeps, RefreshTokenInsert, RefreshTokenRepository, RefreshTokenRow, RefreshTokenSweeperDeps, RefundInput, RefundResult, RefundService, RegisterAlertHandlerDeps, RegisterAlertRoutesDeps, RegisterAllRoutesDeps, RegisterHandlersDeps, RegisterInput, Relay, RemovalOutcome, Repositories, ReservationInsert, ReserveStockResult, Resolution, ResolvePrimitivesOptions, ReviewInsert, ReviewKey, ReviewRepository, ReviewService, ReviewServiceDeps, ReviewSubmitInput, RouteSchema, RunGoldenOptions, SearchService, SecretsKey, SeedCategory, SeedDeps, SeedProduct, SeedResult, ServiceRegistry, SettingRow, SettingSource, SettingValue, SettingsRepository, Settlement, SlotCapabilities, SqliteClient, StockAdjustmentInsert, StockAdjustmentRepository, StoreActivity, StoreRepository, StoredCipher, SweeperHandle, Tx, UcpSurfaceDeps, VariantInsert, VariantPriceInput, VariantRepository, VariantUpdate };
|