@nymbalhq/platform 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1373 @@
+import { NymbalConfig } from '@nymbalhq/config';
+import { Logger, DocumentStoreAdapter, EventBusAdapter, Product, ProductStatus, ProductType, ProductMedia, Variant, VariantDimensions, VariantOption, VariantStatus, Category, Customer, Role, CustomerAddress, Order, OrderStatus, Address, OrderLineItem, CaptureMethod, OrderHistoryEntry, OrderRefundStatus, OrderRefund, InventoryReservation, StockAdjustmentReason, StockAdjustment, Review, ReviewModerationStatus, NymbalEvent, Cart, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, PaymentsAdapter, EmailAdapter, ReviewsAdapter, SearchAdapter, AnalyticsAdapter, ShippingAdapter, TaxAdapter, AiAdapter, SecurityAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, OrderPayment, Refund, HttpAdapter, CommerceSlot, RateLimitAction, SecurityConfigLike } from '@nymbalhq/types';
+import BetterSqlite3 from 'better-sqlite3';
+import pg from 'pg';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { postgresSchema, sqliteSchema } from './db/schema/index.js';
+import { JWTPayload } from 'jose';
+import { ZodTypeAny } from 'zod';
+import 'drizzle-orm/sqlite-core';
+import 'drizzle-orm/pg-core';
+
+type SqliteClient = BetterSQLite3Database<typeof sqliteSchema>;
+type PostgresClient = NodePgDatabase<typeof postgresSchema>;
+declare const readBrand: unique symbol;
+declare const writeBrand: unique symbol;
+/** A handle for reads: committed data, or the open transaction's view when one is open in the call chain. */
+interface ReadTx {
+    readonly kind: 'sqlite' | 'postgres';
+    readonly [readBrand]: true;
+}
+/** A handle for writes: only `CommandStore.transaction` hands one out. */
+interface Tx extends ReadTx {
+    readonly [writeBrand]: true;
+}
+interface CommandStore {
+    readonly kind: 'sqlite' | 'postgres';
+    /** Runs reads. Inside an open transaction (same async call chain) it uses that transaction's Tx; outside, committed
+     *  data only (SQLite: it takes its turn on the queue; Postgres: a pool connection for the callback). */
+    read<T>(fn: (tx: ReadTx) => Promise<T>): Promise<T>;
+    /** Opens a transaction, or joins the one open in the same async call chain (no new BEGIN; commits and rolls back
+     *  with the outermost). */
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    /** Runs `fn` behind a savepoint in the transaction open in the same async call chain: if `fn` throws, its writes
+     *  (and only its writes) are undone, the error is rethrown, and the enclosing transaction carries on. With no
+     *  transaction open it is `transaction`. */
+    savepoint<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** A repository over one command store. A caller handed only the repository (a projection, a sweeper) opens its
+ *  reads and transactions on `store`. */
+interface StoreRepository {
+    readonly store: CommandStore;
+}
+type RawClients = {
+    kind: 'sqlite';
+    db: SqliteClient;
+    raw: BetterSqlite3.Database;
+} | {
+    kind: 'postgres';
+    db: PostgresClient;
+    pool: pg.Pool;
+};
+interface CommandStoreOptions {
+    sqlitePath?: string;
+    postgresUrl?: string;
+}
+/** For migrations, seeding and tests only; no repository or service imports it. */
+declare function rawClients(store: CommandStore): RawClients;
+declare function createCommandStore(config: NymbalConfig, options?: CommandStoreOptions): CommandStore;
+
+interface Platform {
+    config: NymbalConfig;
+    commandStore: CommandStore;
+    documentStore: DocumentStoreAdapter;
+    eventBus: EventBusAdapter;
+    logger: Logger;
+    close(): Promise<void>;
+}
+interface CreatePlatformOptions {
+    logger?: Logger;
+    sqlitePath?: string;
+    postgresUrl?: string;
+}
+declare function createPlatform(config: NymbalConfig, options?: CreatePlatformOptions): Platform;
+
+interface MigrateOptions {
+    migrationsRoot?: string;
+}
+declare function runMigrations(store: CommandStore, options?: MigrateOptions): Promise<void>;
+
+interface ProductInsert$1 {
+    id: string;
+    slug: string;
+    name: string;
+    description: string;
+    shortDescription?: string;
+    status?: 'draft' | 'active' | 'archived';
+    type?: 'simple' | 'variable';
+    seoTitle?: string;
+    seoDescription?: string;
+    media?: unknown[];
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface ProductRow {
+    id: string;
+    slug: string;
+    name: string;
+    description: string;
+    shortDescription: string;
+    status: 'draft' | 'active' | 'archived';
+    type: 'simple' | 'variable';
+    seoTitle: string;
+    seoDescription: string;
+    media: unknown[];
+    metadata: Record<string, unknown>;
+    createdAt: Date | string;
+    updatedAt: Date | string;
+}
+declare function createProductRepository$1(store: CommandStore): {
+    findAll(): Promise<ProductRow[]>;
+    findBySlug(slug: string): Promise<ProductRow | null>;
+    insertMany(items: ProductInsert$1[]): Promise<void>;
+};
+
+interface CategoryInsert$1 {
+    id: string;
+    parentId?: string | null;
+    slug: string;
+    name: string;
+    description: string;
+    position?: number;
+    createdAt: Date;
+}
+interface CategoryRow {
+    id: string;
+    parentId: string | null;
+    slug: string;
+    name: string;
+    description: string;
+    position: number;
+    createdAt: Date | string;
+}
+declare function createCategoryRepository$1(store: CommandStore): {
+    findAll(): Promise<CategoryRow[]>;
+    insertMany(items: CategoryInsert$1[]): Promise<void>;
+};
+
+interface ProductInsert {
+    id: string;
+    slug: string;
+    name: string;
+    description?: string;
+    shortDescription?: string;
+    status?: ProductStatus;
+    type?: ProductType;
+    seoTitle?: string;
+    seoDescription?: string;
+    media?: ProductMedia[];
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface ProductUpdate {
+    name?: string;
+    description?: string;
+    shortDescription?: string;
+    status?: ProductStatus;
+    type?: ProductType;
+    seoTitle?: string;
+    seoDescription?: string;
+    media?: ProductMedia[];
+    metadata?: Record<string, unknown>;
+    updatedAt: Date;
+}
+interface ProductRepository extends StoreRepository {
+    findById(tx: ReadTx, id: string): Promise<Product | null>;
+    findBySlug(tx: ReadTx, slug: string): Promise<Product | null>;
+    list(tx: ReadTx, opts?: {
+        status?: ProductStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<Product[]>;
+    insert(tx: Tx, p: ProductInsert): Promise<void>;
+    update(tx: Tx, id: string, patch: ProductUpdate): Promise<void>;
+    delete(tx: Tx, id: string): Promise<void>;
+    setStatus(tx: Tx, id: string, status: ProductStatus, updatedAt: Date): Promise<void>;
+}
+declare function createProductRepository(store: CommandStore): ProductRepository;
+
+interface VariantInsert {
+    id: string;
+    productId: string;
+    sku: string;
+    name: string;
+    priceMinor: number;
+    compareAtPriceMinor?: number | null;
+    weightGrams?: number | null;
+    dimensions?: VariantDimensions | null;
+    stock: number;
+    lowStockThreshold?: number;
+    options: VariantOption[];
+    status?: VariantStatus;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface VariantUpdate {
+    name?: string;
+    priceMinor?: number;
+    compareAtPriceMinor?: number | null;
+    weightGrams?: number | null;
+    dimensions?: VariantDimensions | null;
+    lowStockThreshold?: number;
+    options?: VariantOption[];
+    status?: VariantStatus;
+    updatedAt: Date;
+}
+interface VariantRepository extends StoreRepository {
+    findById(tx: ReadTx, id: string): Promise<Variant | null>;
+    findBySku(tx: ReadTx, sku: string): Promise<Variant | null>;
+    findByProduct(tx: ReadTx, productId: string): Promise<Variant[]>;
+    insert(tx: Tx, v: VariantInsert): Promise<void>;
+    update(tx: Tx, id: string, patch: VariantUpdate): Promise<void>;
+    /** One conditional UPDATE: the new stock, or null when the variant is missing or holds fewer than `qty`. */
+    decrementStock(tx: Tx, id: string, qty: number, at: Date): Promise<number | null>;
+    /** The new stock, or null when there is no such variant. */
+    incrementStock(tx: Tx, id: string, qty: number, at: Date): Promise<number | null>;
+    delete(tx: Tx, id: string): Promise<void>;
+}
+declare function createVariantRepository(store: CommandStore): VariantRepository;
+
+interface CategoryInsert {
+    id: string;
+    parentId?: string | null;
+    slug: string;
+    name: string;
+    description?: string;
+    position?: number;
+    createdAt: Date;
+}
+interface CategoryUpdate {
+    parentId?: string | null;
+    name?: string;
+    description?: string;
+    position?: number;
+}
+interface CategoryRepository extends StoreRepository {
+    findById(tx: ReadTx, id: string): Promise<Category | null>;
+    findBySlug(tx: ReadTx, slug: string): Promise<Category | null>;
+    list(tx: ReadTx): Promise<Category[]>;
+    insert(tx: Tx, c: CategoryInsert): Promise<void>;
+    update(tx: Tx, id: string, patch: CategoryUpdate): Promise<void>;
+    delete(tx: Tx, id: string): Promise<void>;
+}
+declare function createCategoryRepository(store: CommandStore): CategoryRepository;
+
+interface ProductCategoryRepository extends StoreRepository {
+    attach(tx: Tx, productId: string, categoryId: string): Promise<void>;
+    detach(tx: Tx, productId: string, categoryId: string): Promise<void>;
+    detachAllForProduct(tx: Tx, productId: string): Promise<void>;
+    listCategoriesForProduct(tx: ReadTx, productId: string): Promise<string[]>;
+    listProductsForCategory(tx: ReadTx, categoryId: string): Promise<string[]>;
+}
+declare function createProductCategoryRepository(store: CommandStore): ProductCategoryRepository;
+
+interface CustomerInsert {
+    id: string;
+    email: string;
+    passwordHash: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    addresses?: CustomerAddress[];
+    metadata?: Record<string, unknown>;
+    /** Defaults to `['customer']`; only seed and admin code pass anything else. */
+    roles?: Role[];
+    requiresPasswordReset?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CustomerUpdate {
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    addresses?: CustomerAddress[];
+    metadata?: Record<string, unknown>;
+    passwordHash?: string;
+    requiresPasswordReset?: boolean;
+    updatedAt: Date;
+}
+/** A stored customer: its roles column is always read. */
+type CustomerWithHash = Customer & {
+    passwordHash: string;
+    roles: Role[];
+};
+interface CustomerRepository extends StoreRepository {
+    findById(tx: ReadTx, id: string): Promise<CustomerWithHash | null>;
+    findByEmail(tx: ReadTx, email: string): Promise<CustomerWithHash | null>;
+    list(tx: ReadTx, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<CustomerWithHash[]>;
+    insert(tx: Tx, c: CustomerInsert): Promise<void>;
+    update(tx: Tx, id: string, patch: CustomerUpdate): Promise<void>;
+    incrementStats(tx: Tx, id: string, deltaOrders: number, deltaSpentMinor: number, updatedAt: Date): Promise<void>;
+    delete(tx: Tx, id: string): Promise<void>;
+}
+declare function createCustomerRepository(store: CommandStore): CustomerRepository;
+
+interface RefreshTokenInsert {
+    id: string;
+    customerId: string;
+    tokenHash: string;
+    expiresAt: Date;
+    createdAt: Date;
+}
+interface RefreshTokenRow {
+    id: string;
+    customerId: string;
+    tokenHash: string;
+    revokedAt: string | null;
+    replacedByJti: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+interface RefreshTokenRepository extends StoreRepository {
+    insert(tx: Tx, t: RefreshTokenInsert): Promise<void>;
+    findById(tx: ReadTx, id: string): Promise<RefreshTokenRow | null>;
+    rotate(tx: Tx, oldJti: string, next: RefreshTokenInsert): Promise<void>;
+    revoke(tx: Tx, id: string): Promise<void>;
+    revokeAllForCustomer(tx: Tx, customerId: string): Promise<void>;
+    purgeExpired(tx: Tx, now: Date): Promise<number>;
+}
+declare function createRefreshTokenRepository(store: CommandStore): RefreshTokenRepository;
+
+interface OrderInsert {
+    id: string;
+    orderNumber: string;
+    sequence: number;
+    customerId: string | null;
+    status: OrderStatus;
+    email: string;
+    billingAddress: Address;
+    shippingAddress: Address;
+    lineItems: OrderLineItem[];
+    subtotalMinor: number;
+    taxTotalMinor: number;
+    shippingTotalMinor: number;
+    discountTotalMinor: number;
+    totalMinor: number;
+    currency: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+    paymentIntentId?: string | null;
+    /** The cart a checkout order was placed from. */
+    cartToken?: string | null;
+    /** An imported order's money; a checkout order starts with nothing captured. */
+    capture?: OrderCapture & {
+        refundedMinor: number;
+    };
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface OrderCapture {
+    amountMinor: number;
+    method: CaptureMethod;
+    at: Date;
+}
+interface OrderRepository extends StoreRepository {
+    findById(tx: ReadTx, id: string): Promise<Order | null>;
+    /** The order, read under its row lock until the transaction ends (Postgres `FOR UPDATE`; on SQLite the open
+     *  `BEGIN IMMEDIATE` transaction already holds every write). */
+    lock(tx: Tx, id: string): Promise<Order | null>;
+    findByOrderNumber(tx: ReadTx, orderNumber: string): Promise<Order | null>;
+    findByPaymentIntentId(tx: ReadTx, paymentIntentId: string): Promise<Order | null>;
+    /** The cart's pending order: at most one, by the partial unique index on `cart_token`. */
+    findPendingByCartToken(tx: ReadTx, cartToken: string): Promise<Order | null>;
+    /** The newest order the cart became: neither pending nor cancelled. */
+    findLastConvertedByCartToken(tx: ReadTx, cartToken: string): Promise<Order | null>;
+    listByCustomer(tx: ReadTx, customerId: string, limit?: number): Promise<Order[]>;
+    list(tx: ReadTx, opts?: {
+        status?: OrderStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<Order[]>;
+    insert(tx: Tx, o: OrderInsert): Promise<void>;
+    setStatus(tx: Tx, id: string, status: OrderStatus, updatedAt: Date): Promise<void>;
+    /** Sets `status` only while the order is still `from`; false when it was not, so a concurrent writer got there
+     *  first. */
+    setStatusIf(tx: Tx, id: string, from: OrderStatus, status: OrderStatus, updatedAt: Date): Promise<boolean>;
+    setPaymentIntent(tx: Tx, id: string, paymentIntentId: string, updatedAt: Date): Promise<void>;
+    recordCapture(tx: Tx, id: string, capture: OrderCapture): Promise<void>;
+    setRefunded(tx: Tx, id: string, refundedMinor: number, updatedAt: Date): Promise<void>;
+    setNotes(tx: Tx, id: string, notes: string, updatedAt: Date): Promise<void>;
+}
+declare function createOrderRepository(store: CommandStore): OrderRepository;
+
+interface OrderHistoryInsert {
+    id: string;
+    orderId: string;
+    fromStatus: OrderStatus | null;
+    toStatus: OrderStatus;
+    actor: string;
+    note?: string;
+    timestamp: Date;
+}
+interface OrderHistoryRepository extends StoreRepository {
+    append(tx: Tx, entry: OrderHistoryInsert): Promise<void>;
+    listByOrder(tx: ReadTx, orderId: string): Promise<OrderHistoryEntry[]>;
+}
+declare function createOrderHistoryRepository(store: CommandStore): OrderHistoryRepository;
+
+interface OrderRefundInsert {
+    id: string;
+    orderId: string;
+    amountMinor: number;
+    currency: string;
+    providerRefundId: string | null;
+    status: OrderRefundStatus;
+    reason: string | null;
+    actor: string;
+    createdAt: Date;
+    /** The client's key for the request that made the refund; unique per order. */
+    requestId?: string | null;
+}
+interface OrderRefundRepository extends StoreRepository {
+    insert(tx: Tx, refund: OrderRefundInsert): Promise<void>;
+    /** Settles a `pending` refund; false when the row is not pending (already settled). */
+    settle(tx: Tx, id: string, outcome: {
+        status: OrderRefundStatus;
+        providerRefundId: string | null;
+    }): Promise<boolean>;
+    /** The order's refund made by the request `requestId`, or null. */
+    findByRequestId(tx: ReadTx, orderId: string, requestId: string): Promise<OrderRefund | null>;
+    /** The order's refunds, oldest first. */
+    listByOrder(tx: ReadTx, orderId: string): Promise<OrderRefund[]>;
+    /** The refunds of each order, oldest first; an order without refunds is absent. */
+    listByOrders(tx: ReadTx, orderIds: string[]): Promise<Map<string, OrderRefund[]>>;
+}
+declare function createOrderRefundRepository(store: CommandStore): OrderRefundRepository;
+
+interface OrderSequenceRepository extends StoreRepository {
+    nextSequence(tx: Tx, startFrom?: number): Promise<number>;
+}
+declare function createOrderSequenceRepository(store: CommandStore): OrderSequenceRepository;
+
+interface ReservationInsert {
+    reservationId: string;
+    variantId: string;
+    qty: number;
+    orderRef?: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+interface InventoryReservationRepository extends StoreRepository {
+    insert(tx: Tx, r: ReservationInsert): Promise<void>;
+    findById(tx: ReadTx, reservationId: string): Promise<InventoryReservation | null>;
+    findByVariant(tx: ReadTx, variantId: string): Promise<InventoryReservation[]>;
+    /** Deletes the reservation and returns the row it removed; null when none was there. Of two concurrent callers
+     *  only one gets the row, which is what makes a release and a commit of one reservation exclusive. */
+    deleteById(tx: Tx, reservationId: string): Promise<InventoryReservation | null>;
+    /** Reservations whose expiry is before `at`; deletes nothing. */
+    findExpiredBefore(tx: ReadTx, at: Date): Promise<InventoryReservation[]>;
+    setOrderRef(tx: Tx, reservationId: string, orderRef: string): Promise<void>;
+}
+declare function createInventoryReservationRepository(store: CommandStore): InventoryReservationRepository;
+
+interface StockAdjustmentInsert {
+    id: string;
+    variantId: string;
+    adjustment: number;
+    reason: StockAdjustmentReason;
+    actor: string;
+    previousQty: number;
+    newQty: number;
+    timestamp: Date;
+}
+interface StockAdjustmentRepository extends StoreRepository {
+    append(tx: Tx, a: StockAdjustmentInsert): Promise<void>;
+    listByVariant(tx: ReadTx, variantId: string, limit?: number): Promise<StockAdjustment[]>;
+}
+declare function createStockAdjustmentRepository(store: CommandStore): StockAdjustmentRepository;
+
+interface ReviewInsert {
+    id: string;
+    productId: string;
+    customerId: string | null;
+    orderId: string | null;
+    rating: number;
+    title: string;
+    body: string;
+    moderationStatus?: ReviewModerationStatus;
+    submittedAt: Date;
+}
+interface ReviewRepository extends StoreRepository {
+    findById(tx: ReadTx, id: string): Promise<Review | null>;
+    listByProduct(tx: ReadTx, productId: string, status?: ReviewModerationStatus, limit?: number): Promise<Review[]>;
+    listByStatus(tx: ReadTx, status: ReviewModerationStatus, limit?: number): Promise<Review[]>;
+    insert(tx: Tx, r: ReviewInsert): Promise<void>;
+    setModerationStatus(tx: Tx, id: string, status: ReviewModerationStatus, moderatedBy: string, moderatedAt: Date): Promise<void>;
+    aggregateByProduct(tx: ReadTx, productId: string): Promise<{
+        average: number;
+        count: number;
+        histogram: Record<'1' | '2' | '3' | '4' | '5', number>;
+    }>;
+}
+declare function createReviewRepository(store: CommandStore): ReviewRepository;
+
+/** Which handler has already run for which event id: what stops a side effect running twice, across restarts. */
+interface ProcessedEventRepository extends StoreRepository {
+    seen(tx: ReadTx, handlerName: string, eventId: string): Promise<boolean>;
+    /** Idempotent on (handlerName, eventId): a second call keeps the first record. */
+    markProcessed(tx: Tx, handlerName: string, eventId: string, at: Date): Promise<void>;
+    /** Deletes records processed before `at`; returns how many. */
+    deleteBefore(tx: Tx, at: Date): Promise<number>;
+}
+declare function createProcessedEventRepository(store: CommandStore): ProcessedEventRepository;
+
+interface LoggedEvent {
+    seq: number;
+    event: NymbalEvent<unknown>;
+    deliveredAt: Date | null;
+    attempts: number;
+    deadAt: Date | null;
+}
+interface EventLogRepository extends StoreRepository {
+    /** Appends in array order, so `seq` follows publish order. */
+    append(tx: Tx, events: NymbalEvent<unknown>[]): Promise<void>;
+    /** Neither delivered nor dead, by `seq`; `afterSeq` pages through one pass without re-reading rows it just tried. */
+    listUndelivered(tx: ReadTx, limit: number, afterSeq?: number): Promise<LoggedEvent[]>;
+    markDelivered(tx: Tx, ids: string[], at: Date): Promise<void>;
+    /** One more failed attempt; the event is dead (`dead_at = at`) once its attempts reach `maxAttempts`. */
+    recordFailure(tx: Tx, id: string, at: Date, maxAttempts: number): Promise<void>;
+    /** Deletes delivered events delivered before `at`; returns how many. Undelivered and dead events are never deleted. */
+    deleteDeliveredBefore(tx: Tx, at: Date): Promise<number>;
+    listAll(tx: ReadTx): Promise<LoggedEvent[]>;
+}
+declare function createEventLogRepository(store: CommandStore): EventLogRepository;
+
+/** What makes a cart due an abandonment notice at `at`: live, holding items, unwritten since `cutoff`, not yet
+ *  notified in this inactivity period. */
+interface AbandonedWindow {
+    cutoff: Date;
+    at: Date;
+}
+interface AbandonedCart {
+    token: string;
+    /** The cart's last write. */
+    lastActivityAt: string;
+}
+interface CartRepository extends StoreRepository {
+    findByToken(tx: ReadTx, token: string): Promise<Cart | null>;
+    /** `findByToken`, holding the row for the rest of the transaction so concurrent commands on the cart queue behind
+     *  this one (Postgres `FOR UPDATE`; SQLite's `BEGIN IMMEDIATE` already holds the database). */
+    lock(tx: Tx, token: string): Promise<Cart | null>;
+    /** Inserts the cart, or replaces an expired row on its token. A live row on the token is left as it is and
+     *  returned with `created: false`. */
+    create(tx: Tx, cart: Cart): Promise<{
+        cart: Cart;
+        created: boolean;
+    }>;
+    /** Writes the cart whole and starts a new inactivity period (clears the abandonment claim). */
+    put(tx: Tx, cart: Cart): Promise<void>;
+    remove(tx: Tx, token: string): Promise<void>;
+    /** Empties the cart if it is still live at `at`, in one conditional write; false when there was no live row to
+     *  empty (expired, or deleted by a sweep or a merge). Starts a new inactivity period; the expiry stays as it was. */
+    clearIfLive(tx: Tx, token: string, at: Date): Promise<boolean>;
+    /** Deletes every cart whose expiry is at or before `at`; returns how many. */
+    deleteExpired(tx: Tx, at: Date): Promise<number>;
+    /** Up to `limit` tokens due a notice, in token order after `after`; claims nothing. */
+    listAbandoned(tx: ReadTx, window: AbandonedWindow, page: {
+        after: string | undefined;
+        limit: number;
+    }): Promise<string[]>;
+    /** Marks the cart notified if it is still due a notice; null when it is not (another sweeper claimed it, or a
+     *  write, expiry or delete came first). */
+    claimAbandoned(tx: Tx, token: string, window: AbandonedWindow): Promise<AbandonedCart | null>;
+}
+declare function createCartRepository(store: CommandStore): CartRepository;
+
+interface Repositories {
+    product: ProductRepository;
+    variant: VariantRepository;
+    category: CategoryRepository;
+    productCategory: ProductCategoryRepository;
+    customer: CustomerRepository;
+    refreshToken: RefreshTokenRepository;
+    order: OrderRepository;
+    orderHistory: OrderHistoryRepository;
+    orderRefund: OrderRefundRepository;
+    orderSequence: OrderSequenceRepository;
+    inventoryReservation: InventoryReservationRepository;
+    stockAdjustment: StockAdjustmentRepository;
+    review: ReviewRepository;
+    processedEvent: ProcessedEventRepository;
+    eventLog: EventLogRepository;
+    cart: CartRepository;
+}
+declare function buildRepositories(commandStore: CommandStore, _documentStore: DocumentStoreAdapter): Repositories;
+
+interface InMemoryDocumentStoreOptions {
+    sweepIntervalMs?: number;
+    now?: () => number;
+}
+declare class InMemoryDocumentStore implements DocumentStoreAdapter {
+    #private;
+    constructor(options?: InMemoryDocumentStoreOptions);
+    capabilities(): readonly string[];
+    get<T>(collection: string, key: string): Promise<T | null>;
+    put<T>(collection: string, key: string, document: T, options?: PutOptions): Promise<void>;
+    delete(collection: string, key: string): Promise<void>;
+    query<T>(collection: string, params: QueryParams): Promise<QueryResult<T>>;
+    batchGet<T>(collection: string, keys: string[]): Promise<Map<string, T>>;
+    batchPut<T>(collection: string, items: Map<string, T>): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare function createDocumentStore(config: NymbalConfig): DocumentStoreAdapter;
+
+interface InProcessEventBusOptions {
+    logger?: Logger;
+}
+declare class InProcessEventBus implements EventBusAdapter {
+    #private;
+    constructor(options?: InProcessEventBusOptions);
+    capabilities(): readonly string[];
+    publish<T>(event: NymbalEvent<T>): Promise<void>;
+    publishBatch(events: NymbalEvent<unknown>[]): Promise<void>;
+    replay(events: NymbalEvent<unknown>[]): Promise<void>;
+    subscribe(eventPattern: string | string[], handler: EventHandler, config?: SubscriptionConfig): Promise<Subscription>;
+    unsubscribe(subscription: Subscription): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare function createEventBus(config: NymbalConfig, logger?: Logger): EventBusAdapter;
+
+interface EventBuilderContext {
+    storeId: string;
+    environment: NymbalEnvironment;
+    version: string;
+    source?: string;
+}
+interface MakeEventOptions {
+    source?: string;
+    correlationId?: string;
+    timestamp?: Date;
+}
+declare function createEventBuilder(ctx: EventBuilderContext): <T>(type: string, payload: T, options?: MakeEventOptions) => NymbalEvent<T>;
+
+/** Hands committed events from the log to the bus. */
+interface Relay {
+    /** Delivers every undelivered, non-dead event in `seq` order. Never rejects. */
+    drain(): Promise<void>;
+    /** Drains on an interval (the timer does not keep the process alive). */
+    start(): void;
+    /** Stops the interval and starts no new pass; resolves when the pass in flight, if any, has finished, so the
+     *  store can be closed without cutting a delivery off between the handler and its bookkeeping. */
+    stop(): Promise<void>;
+}
+interface CreateRelayOptions {
+    store: CommandStore;
+    eventLog: EventLogRepository;
+    eventBus: EventBusAdapter;
+    logger: Logger;
+    /** Failed bus publishes after which an event is dead and never handed to the bus again. */
+    maxAttempts?: number;
+    intervalMs?: number;
+}
+declare function createRelay(opts: CreateRelayOptions): Relay;
+
+interface PublishOptions extends MakeEventOptions {
+}
+interface EventPublisher {
+    publish<E extends NymbalEventType>(type: E, payload: NymbalEventMap[E], options?: PublishOptions): Promise<NymbalEvent<NymbalEventMap[E]>>;
+    publishMany(events: Array<{
+        [E in NymbalEventType]: {
+            type: E;
+            payload: NymbalEventMap[E];
+            options?: PublishOptions;
+        };
+    }[NymbalEventType]>): Promise<void>;
+    correlated(correlationId: string): EventPublisher;
+}
+interface CreatePublisherOptions {
+    eventBus: EventBusAdapter;
+    builderContext: EventBuilderContext;
+    /** Events are appended to `eventLog` on this store and reach the bus only through `relay`. */
+    store: CommandStore;
+    eventLog: EventLogRepository;
+    relay: Relay;
+    correlationId?: string;
+}
+declare function createEventPublisher(opts: CreatePublisherOptions): EventPublisher;
+
+interface IdempotencyOptions {
+    repo: ProcessedEventRepository;
+    logger?: Logger;
+}
+declare function withIdempotency<T = unknown>(handlerName: string, handler: EventHandler<T>, { repo, logger }: IdempotencyOptions): EventHandler<T>;
+
+/** One adapter per commerce slot. */
+interface CommerceAdapters {
+    payments: PaymentsAdapter;
+    email: EmailAdapter;
+    reviews: ReviewsAdapter;
+    search: SearchAdapter;
+    analytics: AnalyticsAdapter;
+    shipping: ShippingAdapter;
+    tax: TaxAdapter;
+    ai: AiAdapter;
+}
+/** Adapters a project hands `createApp`, each for a slot whose provider is `custom`. */
+type InjectedAdapters = Partial<CommerceAdapters>;
+interface AdapterRegistry extends Omit<CommerceAdapters, 'ai'> {
+    security: SecurityAdapter;
+    /** `null` when the config's ai provider is `none`. */
+    ai: AiAdapter | null;
+}
+interface BuildAdaptersDeps {
+    config: NymbalConfig;
+    logger: Logger;
+    documentStore: DocumentStoreAdapter;
+    repos: Repositories;
+    injected?: InjectedAdapters;
+    /** The payments adapter `createApp` resolved before it opened the store. */
+    payments: PaymentsAdapter;
+}
+declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
+
+interface RegisterHandlersDeps {
+    config: NymbalConfig;
+    eventBus: EventBusAdapter;
+    documentStore: DocumentStoreAdapter;
+    repos: Repositories;
+    adapters: AdapterRegistry;
+    logger: Logger;
+}
+declare function registerHandlers(deps: RegisterHandlersDeps): Promise<void>;
+
+interface ProductCreateInput {
+    slug: string;
+    name: string;
+    description?: string;
+    shortDescription?: string;
+    status?: ProductStatus;
+    type?: 'simple' | 'variable';
+    seoTitle?: string;
+    seoDescription?: string;
+    media?: Product['media'];
+    metadata?: Record<string, unknown>;
+    categoryIds?: string[];
+    variants?: Array<Omit<VariantInsert, 'id' | 'productId' | 'createdAt' | 'updatedAt'> & {
+        id?: string;
+    }>;
+}
+interface ProductUpdateInput extends Omit<ProductUpdate, 'updatedAt'> {
+    categoryIds?: string[];
+}
+interface ProductService {
+    create(input: ProductCreateInput): Promise<ProductSnapshot>;
+    update(id: string, input: ProductUpdateInput): Promise<ProductSnapshot>;
+    delete(id: string): Promise<void>;
+    publish(id: string): Promise<void>;
+    unpublish(id: string): Promise<void>;
+    getById(id: string): Promise<ProductSnapshot>;
+    getBySlug(slug: string): Promise<ProductSnapshot>;
+    list(opts?: {
+        status?: ProductStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<ProductSnapshot[]>;
+}
+interface CreateProductServiceDeps {
+    store: CommandStore;
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+}
+declare function createProductService(deps: CreateProductServiceDeps): ProductService;
+
+interface CategoryCreateInput {
+    slug: string;
+    name: string;
+    description?: string;
+    parentId?: string | null;
+    position?: number;
+}
+interface CategoryUpdateInput {
+    name?: string;
+    description?: string;
+    parentId?: string | null;
+    position?: number;
+}
+interface CategoryService {
+    list(): Promise<Category[]>;
+    getById(id: string): Promise<Category>;
+    getBySlug(slug: string): Promise<Category>;
+    create(input: CategoryCreateInput): Promise<Category>;
+    update(id: string, input: CategoryUpdateInput): Promise<Category>;
+    delete(id: string): Promise<void>;
+}
+declare function createCategoryService(deps: {
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+}): CategoryService;
+
+interface CartService {
+    getOrCreate(token?: string, customerId?: string | null): Promise<Cart>;
+    get(token: string): Promise<Cart | null>;
+    addItem(token: string, item: Omit<CartItem, 'qty'> & {
+        qty?: number;
+    }): Promise<Cart>;
+    updateItemQuantity(token: string, variantId: string, qty: number): Promise<Cart>;
+    removeItem(token: string, variantId: string): Promise<Cart>;
+    clear(token: string): Promise<Cart>;
+    merge(guestToken: string, customerToken: string): Promise<Cart>;
+    attachCustomer(token: string, customerId: string): Promise<Cart>;
+}
+interface CreateCartServiceDeps {
+    store: CommandStore;
+    carts: CartRepository;
+    publisher: EventPublisher;
+    logger: Logger;
+    currency: string;
+    ttlSeconds?: number;
+    now?: () => Date;
+}
+declare function createCartService(deps: CreateCartServiceDeps): CartService;
+
+interface ProfileUpdate {
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+}
+interface CustomerService {
+    getProfile(customerId: string): Promise<Customer>;
+    updateProfile(customerId: string, patch: ProfileUpdate): Promise<Customer>;
+    listAddresses(customerId: string): Promise<CustomerAddress[]>;
+    addAddress(customerId: string, addr: Omit<CustomerAddress, 'id'>): Promise<CustomerAddress>;
+    deleteAddress(customerId: string, addressId: string): Promise<void>;
+}
+declare function createCustomerService(deps: {
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+}): CustomerService;
+
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+interface RegisterInput {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+}
+interface CustomerJwtPayload extends JWTPayload {
+    sub: string;
+    email: string;
+    roles: Role[];
+    type: 'access' | 'refresh';
+    jti?: string;
+}
+interface ImportCustomerInput {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    addresses?: CustomerAddress[];
+    metadata?: Record<string, unknown>;
+}
+interface AuthService {
+    register(input: RegisterInput): Promise<{
+        customer: Customer;
+        tokens: AuthTokens;
+    }>;
+    login(email: string, password: string): Promise<{
+        customer: Customer;
+        tokens: AuthTokens;
+    }>;
+    refresh(refreshToken: string): Promise<AuthTokens>;
+    logout(refreshToken: string): Promise<void>;
+    verifyAccessToken(token: string): Promise<CustomerJwtPayload>;
+    importCustomer(input: ImportCustomerInput): Promise<Customer>;
+}
+interface CreateAuthServiceDeps {
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+    jwtSecret: string;
+    accessTtl: string;
+    refreshTtl: string;
+    issuer?: string;
+}
+declare function createAuthService(deps: CreateAuthServiceDeps): AuthService;
+
+interface OrderCreateDraftInput {
+    orderId: string;
+    customerId: string | null;
+    email: string;
+    billingAddress: Address;
+    shippingAddress: Address;
+    lineItems: OrderLineItem[];
+    subtotalMinor: number;
+    taxTotalMinor: number;
+    shippingTotalMinor: number;
+    discountTotalMinor: number;
+    totalMinor: number;
+    currency: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+    paymentIntentId?: string | null;
+    cartToken?: string | null;
+}
+interface OrderImportInput extends OrderCreateDraftInput {
+    orderNumber: string;
+    status: OrderStatus;
+    createdAt: Date;
+    /** What the imported order was paid, taken as captured when it was placed; nothing when absent. */
+    capturedMinor?: number;
+    refundedMinor?: number;
+    captureMethod?: CaptureMethod | null;
+}
+interface OrderService {
+    createFromCheckout(input: OrderCreateDraftInput): Promise<Order>;
+    importOrder(input: OrderImportInput): Promise<Order>;
+    getById(id: string): Promise<Order>;
+    getByOrderNumber(orderNumber: string): Promise<Order>;
+    listByCustomer(customerId: string): Promise<Order[]>;
+    updateStatus(id: string, toStatus: OrderStatus, actor: string, note?: string): Promise<Order>;
+    markShipped(id: string, trackingNumber: string, carrier: string, actor: string): Promise<Order>;
+    markDelivered(id: string, actor: string): Promise<Order>;
+    /** Refuses with `order.paid` once anything is captured: a paid order is refunded, never cancelled. */
+    cancel(id: string, reason: string, actor: string): Promise<Order>;
+}
+interface CreateOrderServiceDeps {
+    store: CommandStore;
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+    orderNumberPrefix: string;
+    orderNumberStart: number;
+}
+declare function createOrderService(deps: CreateOrderServiceDeps): OrderService;
+
+interface ReserveStockResult {
+    reservationId: string;
+    expiresAt: string;
+}
+interface InventoryService {
+    adjustStock(variantId: string, delta: number, reason: StockAdjustmentReason, actor: string): Promise<{
+        newQty: number;
+    }>;
+    reserveStock(variantId: string, qty: number, orderRef?: string | null, ttlSeconds?: number): Promise<ReserveStockResult>;
+    /** `reserveStock`, answering null instead of throwing when the variant has less than `qty` in stock. */
+    tryReserveStock(variantId: string, qty: number, orderRef?: string | null, ttlSeconds?: number): Promise<ReserveStockResult | null>;
+    releaseReservation(reservationId: string, reason: 'expired' | 'cancelled' | 'abandoned'): Promise<void>;
+    commitReservation(reservationId: string, actor: string): Promise<void>;
+    getStockStatus(variantId: string): Promise<{
+        stock: number;
+        threshold: number;
+        status: StockStatus;
+    }>;
+}
+interface CreateInventoryServiceDeps {
+    store: CommandStore;
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+    defaultReservationTtlSeconds?: number;
+}
+declare function createInventoryService(deps: CreateInventoryServiceDeps): InventoryService;
+
+interface BeginCheckoutInput {
+    cartToken: string;
+    customerId?: string | null;
+    email: string;
+    billingAddress: Address;
+    shippingAddress: Address;
+    notes?: string;
+}
+interface BeginCheckoutResult {
+    orderId: string;
+    orderNumber: string;
+    paymentIntent: PaymentIntent;
+    currency: string;
+    totalMinor: number;
+    /** The order's status as the checkout answers. */
+    orderStatus: OrderStatus;
+    payment: CheckoutPayment;
+}
+/** What the payment provider captured. */
+interface CapturedPayment {
+    amountMinor: number;
+    /** ISO 4217, in any case. */
+    currency: string;
+}
+interface FinalizeResult {
+    /** Null when no order has the payment intent. */
+    orderNumber: string | null;
+    /** True when the order is confirmed: by this call, or already for this intent. */
+    finalized: boolean;
+    /** Why the captured payment did not confirm the order; recorded as payment.failed. */
+    reason?: string;
+}
+interface CheckoutService {
+    beginCheckout(input: BeginCheckoutInput): Promise<BeginCheckoutResult>;
+    /**
+     * Confirms the order a captured payment is for, or records why not (a payment.failed with the reason and, when
+     * there is an order, a history note) and leaves the order as it was. Joins the caller's transaction.
+     */
+    finalize(paymentIntentId: string, paid: CapturedPayment): Promise<FinalizeResult>;
+    cancel(orderId: string, reason: string): Promise<void>;
+}
+/** The admin's side of a checkout: a payment taken outside the store. */
+interface ManualPayments {
+    /**
+     * Records a payment the merchant took outside the store (a manual capture of the order's total) and confirms the
+     * pending order exactly as a provider capture does: its reservations committed (re-taken if released), stats,
+     * payment.captured and order.paid, the cart cleared. `order.stock_unavailable` when released stock is gone.
+     */
+    markPaid(orderId: string, actor: string, note?: string): Promise<Order>;
+}
+interface CreateCheckoutServiceDeps {
+    store: CommandStore;
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+    cart: CartService;
+    orders: OrderService;
+    inventory: InventoryService;
+    payments: PaymentsAdapter;
+    currency: string;
+}
+declare function createCheckoutService(deps: CreateCheckoutServiceDeps): CheckoutService & ManualPayments;
+
+interface SearchService {
+    products(query: string, params?: SearchParams): Promise<SearchResult>;
+}
+declare function createSearchService(deps: {
+    adapter: SearchAdapter;
+    logger: Logger;
+}): SearchService;
+
+/** What the shop tells the provider; the merchant's own words stay on the refund row. */
+declare const PROVIDER_REFUND_REASON = "requested_by_customer";
+interface RefundInput {
+    orderId: string;
+    amountMinor: number;
+    reason?: string;
+    actor: string;
+    /** The client's key for this request: a repeat on the order answers the refund the first one made. */
+    requestId?: string;
+}
+interface RefundResult {
+    order: Order;
+    payment: OrderPayment;
+    refund: OrderRefund;
+}
+interface RefundService {
+    /**
+     * Refunds part or all of what the order captured, through the payments provider when the provider took the money.
+     * The refund is held as a `pending` row under the order's lock, the provider is called outside any transaction with
+     * the row id as its idempotency key, and the row is settled under the lock again by the provider's answer. A
+     * `requestId` the order has already seen answers that refund as it stands and moves no money;
+     * `refund.request_reused` when the amount differs.
+     */
+    refund(input: RefundInput): Promise<RefundResult>;
+}
+interface CreateRefundServiceDeps {
+    store: CommandStore;
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+    payments: PaymentsAdapter;
+}
+declare function orderPayment(order: Order, refunds: OrderRefund[]): OrderPayment;
+interface Settlement {
+    status: OrderRefundStatus;
+    providerRefundId: string | null;
+    /** The provider answered for another amount or currency than the row's. */
+    mismatch: boolean;
+}
+/** The provider's answer settles a refund row as succeeded only when it is for the row's amount and currency. */
+declare function settlementOf(answer: Refund, row: Pick<OrderRefund, 'amountMinor' | 'currency'>): Settlement;
+/** Writes `refunded_minor` as Σ of the order's succeeded refunds. */
+declare function refreshRefunded(repos: Repositories, tx: Tx, orderId: string, at: Date): Promise<{
+    refunds: OrderRefund[];
+    refundedMinor: number;
+}>;
+declare function createRefundService(deps: CreateRefundServiceDeps): RefundService;
+
+interface ServiceRegistry {
+    product: ProductService;
+    category: CategoryService;
+    cart: CartService;
+    customer: CustomerService;
+    auth: AuthService;
+    order: OrderService;
+    inventory: InventoryService;
+    checkout: CheckoutService & ManualPayments;
+    refund: RefundService;
+    search: SearchService;
+}
+interface BuildServicesDeps {
+    config: NymbalConfig;
+    store: CommandStore;
+    repos: Repositories;
+    publisher: EventPublisher;
+    logger: Logger;
+    payments: PaymentsAdapter;
+    searchAdapter: SearchAdapter;
+}
+declare function buildServices(deps: BuildServicesDeps): ServiceRegistry;
+
+interface RegisterAllRoutesDeps {
+    config: NymbalConfig;
+    adapter: HttpAdapter;
+    services: ServiceRegistry;
+    adapters: AdapterRegistry;
+    repos: Repositories;
+    documentStore: DocumentStoreAdapter;
+    eventBus: EventBusAdapter;
+    publisher: EventPublisher;
+    /** The admin's dist directory, or null for a 404 that says how to build it; undefined serves no admin. */
+    adminRoot?: string | null | undefined;
+}
+declare function registerAllRoutes(deps: RegisterAllRoutesDeps): void;
+
+/**
+ * The input of one route: what `registerAllRoutes` parses before the handler runs, and what a tool definition is
+ * generated from. Unknown keys are stripped, so a handler sees only what is declared here.
+ */
+interface RouteSchema {
+    /** Unique, dotted: `cart.addItem`. */
+    name: string;
+    description: string;
+    params?: ZodTypeAny;
+    query?: ZodTypeAny;
+    body?: ZodTypeAny;
+}
+declare const routeSchemas: Record<string, RouteSchema>;
+
+interface NymbalApp {
+    platform: Platform;
+    repos: Repositories;
+    adapters: AdapterRegistry;
+    services: ServiceRegistry;
+    publisher: EventPublisher;
+    /** Delivers the event log to the bus; started by createApp, stopped by stop(). */
+    relay: Relay;
+    /**
+     * Registers the API on the adapter. The admin is served at /admin/ when `adminRoot` is passed (its dist directory,
+     * or null for a 404 that says how to build it) or `NYMBAL_ADMIN_DIST` is set.
+     */
+    attachHttp(adapter: HttpAdapter, options?: AttachHttpOptions): Promise<void>;
+    /** Each slot's provider and its adapter's own `capabilities()`; an ai slot of `none` offers nothing. */
+    capabilities(): CapabilitiesReport;
+    stop(): Promise<void>;
+}
+type CapabilitySlot = CommerceSlot | 'security' | 'documentStore' | 'eventBus' | 'media';
+interface SlotCapabilities {
+    provider: string;
+    capabilities: readonly string[];
+}
+type CapabilitiesReport = Record<CapabilitySlot, SlotCapabilities>;
+interface AttachHttpOptions {
+    adminRoot?: string | null;
+}
+interface CreateAppOptions extends CreatePlatformOptions {
+    version?: string;
+    /** The project's own adapters, one per slot whose provider is `custom`. */
+    adapters?: InjectedAdapters;
+}
+declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
+
+/**
+ * Serves the admin's built files at /admin/ beside /api, one origin, so its relative API URLs and the refresh cookie
+ * work without a proxy. `root` is the admin's dist directory, or null when none is installed: then /admin/ answers 404
+ * with how to build it.
+ */
+declare function registerAdminStaticRoute(adapter: HttpAdapter, root: string | null): void;
+
+interface SweeperHandle {
+    /** One sweep, awaited; the interval calls it. */
+    tick(): Promise<void>;
+    stop(): void;
+}
+interface InventoryReservationSweeperDeps {
+    inventoryService: InventoryService;
+    reservationRepo: InventoryReservationRepository;
+    logger: Logger;
+    intervalMs?: number;
+}
+declare function startInventoryReservationSweeper(deps: InventoryReservationSweeperDeps): SweeperHandle;
+
+interface CartAbandonmentSweeperDeps {
+    store: CommandStore;
+    carts: CartRepository;
+    publisher: EventPublisher;
+    logger: Logger;
+    intervalMs?: number;
+    inactivityMs?: number;
+    /** Carts claimed per transaction; a tick runs as many as it takes to reach every due cart. */
+    batchSize?: number;
+    now?: () => Date;
+}
+/**
+ * Deletes expired carts, then notifies each cart idle past `inactivityMs` once per inactivity period. The notice is
+ * a durable claim on the cart row, committed with its `cart.abandoned` event, so a restart or another replica's
+ * sweeper does not notify the same period again; a cart write clears the claim.
+ */
+declare function startCartAbandonmentSweeper(deps: CartAbandonmentSweeperDeps): SweeperHandle;
+
+interface EventRetentionSweeperDeps {
+    store: CommandStore;
+    eventLog: EventLogRepository;
+    processedEvents: ProcessedEventRepository;
+    logger: Logger;
+    retentionDays?: number;
+    intervalMs?: number;
+}
+/** Deletes delivered events and processed-event records older than the window; undelivered and dead events stay. */
+declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
+
+interface ProviderPackage {
+    /** The adapter package, which exports `createAdapter(ctx: AdapterContext)`. */
+    package: string;
+    /** The provider SDK the package peers, which the project installs beside it. */
+    sdk: string;
+}
+/**
+ * The providers that live in their own package, by slot then provider. The kernel imports a package only when the
+ * config names its provider; `native`, `none` and `custom` have no entry.
+ */
+declare const PROVIDER_PACKAGES: Readonly<Partial<Record<CommerceSlot, Readonly<Record<string, ProviderPackage>>>>>;
+
+/**
+ * v0.1 security adapter.
+ *
+ * Rate limiting, CSRF verification and CSRF cookie minting need the request before
+ * any middleware and the response after the handler, so the HTTP adapter runs them
+ * itself on every route (`FastifyHttpAdapter`'s guard). This adapter only asserts
+ * static security headers via `HttpAdapter.setDefaultHeaders(...)`. A future
+ * WAF-native adapter will replace both layers.
+ */
+declare function createMiddlewareSecurityAdapter(deps: {
+    logger: Logger;
+}): SecurityAdapter;
+
+declare class RateLimiter {
+    #private;
+    constructor(rules: Record<string, {
+        requests: number;
+        window: string;
+        action: RateLimitAction;
+    }>);
+    check(ip: string, path: string): {
+        allowed: boolean;
+        action: RateLimitAction;
+        retryAfter?: number;
+    } | null;
+    reset(): void;
+}
+
+declare function buildSecurityHeaders(security: SecurityConfigLike): Record<string, string>;
+declare const CSRF_COOKIE = "nymbal.csrf";
+declare const CSRF_HEADER = "x-csrf-token";
+
+/**
+ * Deterministic payments adapter for local development without Stripe keys.
+ * Every intent succeeds at creation unless the receipt email asks otherwise (`statusFor`); webhook verification is a
+ * no-op. Refunds follow a provider's rules for the intents this process holds (captured, and never beyond the
+ * capture); an intent of its own lost to a restart is refunded as asked, the shop's refundable check being the guard.
+ */
+declare function createNativeStubPaymentsAdapter(deps: {
+    logger: Logger;
+}): PaymentsAdapter;
+
+/** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/adapter-smtp). */
+interface NativeEmailAdapterConfig {
+    transport?: 'console';
+    from?: string;
+}
+declare function createNativeEmailAdapter(deps: {
+    logger: Logger;
+    config?: NativeEmailAdapterConfig;
+}): EmailAdapter;
+
+declare function createNativeSearchAdapter(deps: {
+    documentStore: DocumentStoreAdapter;
+    logger: Logger;
+}): SearchAdapter;
+
+declare function createNativeReviewsAdapter(deps: {
+    repos: Repositories;
+    logger: Logger;
+}): ReviewsAdapter;
+
+declare function createNativeAnalyticsAdapter(logger: Logger): AnalyticsAdapter;
+
+declare function createNativeShippingAdapter(logger: Logger): ShippingAdapter;
+
+declare function createNativeTaxAdapter(logger: Logger, defaultRate?: number): TaxAdapter;
+
+declare function createNativeAiAdapter(_logger: Logger): AiAdapter;
+
+interface CreateLoggerOptions {
+    level?: string;
+    pretty?: boolean;
+    base?: Record<string, unknown>;
+}
+declare function createLogger(options?: CreateLoggerOptions): Logger;
+
+interface SeedDeps {
+    config: NymbalConfig;
+    commandStore: CommandStore;
+    documentStore: DocumentStoreAdapter;
+    eventBus: EventBusAdapter;
+    logger: Logger;
+    version: string;
+}
+interface SeedResult {
+    categories: number;
+    products: number;
+    variants: number;
+    customers: number;
+    admins: number;
+    /** True when any demo row was already in the command store, so nothing was inserted. */
+    alreadySeeded: boolean;
+}
+declare function runSeed(deps: SeedDeps): Promise<SeedResult>;
+
+interface WarmDocumentStoreDeps {
+    config: NymbalConfig;
+    repos: Repositories;
+    eventBus: EventBusAdapter;
+    logger: Logger;
+    version: string;
+}
+interface WarmResult {
+    products: number;
+    orders: number;
+    customers: number;
+}
+declare function warmDocumentStore(deps: WarmDocumentStoreDeps): Promise<WarmResult>;
+
+interface SeedCategory {
+    slug: string;
+    name: string;
+    description: string;
+}
+interface SeedProduct {
+    slug: string;
+    title: string;
+    description: string;
+    priceMinor: number;
+    categorySlug: string;
+    imageUrl: string;
+}
+declare const seedCategories: SeedCategory[];
+declare const seedProducts: SeedProduct[];
+
+interface MediaStorage {
+    capabilities(): readonly string[];
+    put(key: string, body: Uint8Array, contentType: string): Promise<{
+        url: string;
+    }>;
+}
+
+interface LocalFsMediaStorageOptions {
+    root: string;
+    urlPrefix?: string;
+}
+declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
+
+export { type AbandonedCart, type AbandonedWindow, type AdapterRegistry, type AttachHttpOptions, type AuthService, type AuthTokens, type BeginCheckoutInput, type BeginCheckoutResult, type BuildAdaptersDeps, type BuildServicesDeps, CSRF_COOKIE, CSRF_HEADER, type CapabilitiesReport, type CapabilitySlot, type CapturedPayment, type CartRepository, type CartService, type CategoryCreateInput, type CategoryInsert, type CategoryRepository, type CategoryService, type CategoryUpdate, type CategoryUpdateInput, type CheckoutService, type CommandStore, type CommerceAdapters, type CreateAppOptions, type CreateAuthServiceDeps, type CreateCartServiceDeps, type CreateCheckoutServiceDeps, type CreateInventoryServiceDeps, type CreateLoggerOptions, type CreateOrderServiceDeps, type CreatePlatformOptions, type CreateProductServiceDeps, type CreatePublisherOptions, type CreateRefundServiceDeps, type CreateRelayOptions, type CustomerInsert, type CustomerJwtPayload, type CustomerRepository, type CustomerService, type CustomerUpdate, type CustomerWithHash, type EventBuilderContext, type EventLogRepository, type EventPublisher, type EventRetentionSweeperDeps, type FinalizeResult, type IdempotencyOptions, type ImportCustomerInput, InMemoryDocumentStore, type InMemoryDocumentStoreOptions, InProcessEventBus, type InProcessEventBusOptions, type InjectedAdapters, type InventoryReservationRepository, type InventoryService, type CategoryInsert$1 as LegacyCategoryInsert, type CategoryRow as LegacyCategoryRow, type ProductInsert$1 as LegacyProductInsert, type ProductRow as LegacyProductRow, type LocalFsMediaStorageOptions, type LoggedEvent, type MakeEventOptions, type ManualPayments, type MediaStorage, type MigrateOptions, type NativeEmailAdapterConfig, type NymbalApp, type OrderCapture, type OrderCreateDraftInput, type OrderHistoryInsert, type OrderHistoryRepository, type OrderImportInput, type OrderInsert, type OrderRefundInsert, type OrderRefundRepository, type OrderRepository, type OrderSequenceRepository, type OrderService, PROVIDER_PACKAGES, PROVIDER_REFUND_REASON, type Platform, type PostgresClient, type ProcessedEventRepository, type ProductCategoryRepository, type ProductCreateInput, type ProductInsert, type ProductRepository, type ProductService, type ProductUpdate, type ProductUpdateInput, type ProfileUpdate, type ProviderPackage, type PublishOptions, RateLimiter, type RawClients, type ReadTx, type RefreshTokenInsert, type RefreshTokenRepository, type RefreshTokenRow, type RefundInput, type RefundResult, type RefundService, type RegisterAllRoutesDeps, type RegisterHandlersDeps, type RegisterInput, type Relay, type Repositories, type ReservationInsert, type ReserveStockResult, type ReviewInsert, type ReviewRepository, type RouteSchema, type SearchService, type SeedCategory, type SeedDeps, type SeedProduct, type SeedResult, type ServiceRegistry, type Settlement, type SlotCapabilities, type SqliteClient, type StockAdjustmentInsert, type StockAdjustmentRepository, type StoreRepository, type SweeperHandle, type Tx, type VariantInsert, type VariantRepository, type VariantUpdate, type WarmDocumentStoreDeps, type WarmResult, buildAdapters, buildRepositories, buildSecurityHeaders, buildServices, createApp, createAuthService, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createDocumentStore, createEventBuilder, createEventBus, createEventLogRepository, createEventPublisher, createInventoryReservationRepository, createInventoryService, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAiAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createStockAdjustmentRepository, createVariantRepository, orderPayment, rawClients, refreshRefunded, registerAdminStaticRoute, registerAllRoutes, registerHandlers, routeSchemas, runMigrations, runSeed, seedCategories, seedProducts, settlementOf, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, warmDocumentStore, withIdempotency };