@nymbalhq/types 0.0.0-canary-20261019164512

package/dist/index.d.ts

@@ -0,0 +1,1030 @@
+type ErrorContext = Record<string, unknown>;
+declare class NymbalError extends Error {
+    readonly code: string;
+    readonly context: ErrorContext;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        context: ErrorContext;
+    };
+}
+declare class ConfigError extends NymbalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+        code?: `config.${string}`;
+    });
+}
+declare class ValidationError extends NymbalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+declare class NotFoundError extends NymbalError {
+    constructor(resource: string, identifier: unknown, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+declare class AdapterError extends NymbalError {
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+declare class HttpError extends NymbalError {
+    readonly status: number;
+    constructor(status: number, message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+        code?: string;
+    });
+}
+declare class AuthError extends HttpError {
+    constructor(code: 'unauthorized' | 'forbidden' | 'invalid_credentials' | 'token_expired' | 'token_invalid', message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+declare class PaymentError extends NymbalError {
+    constructor(code: 'intent_failed' | 'capture_failed' | 'refund_rejected' | 'refund_unknown' | 'cancel_refused' | 'webhook_invalid' | 'not_configured', message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+/** A command the order's money does not allow (confirm unpaid, cancel paid, refund beyond the capture). */
+declare class OrderConflictError extends NymbalError {
+    constructor(code: 'order.unpaid' | 'order.paid' | 'order.stock_unavailable' | 'order.payment_in_progress' | 'refund.not_captured' | 'refund.exceeds_captured' | 'refund.request_reused', message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+declare class CheckoutError extends NymbalError {
+    constructor(code: 'cart_empty' | 'in_progress' | 'payment_in_progress' | 'variant_missing' | 'out_of_stock' | 'reservation_failed' | 'finalize_failed', message: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+declare class StatusTransitionError extends NymbalError {
+    constructor(entity: string, fromStatus: string, toStatus: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
+
+interface Money {
+    amount: number;
+    currency: string;
+}
+declare function money(amount: number, currency: string): Money;
+declare function assertMinorUnits(amount: number): void;
+declare function add(a: Money, b: Money): Money;
+declare function sub(a: Money, b: Money): Money;
+declare function mulBy(m: Money, scalar: number): Money;
+declare function sumMoney(values: Money[], currency: string): Money;
+declare function allocate(m: Money, weights: number[]): Money[];
+
+type ProductStatus = 'draft' | 'active' | 'archived';
+type ProductType = 'simple' | 'variable';
+type VariantStatus = 'active' | 'inactive';
+interface ProductMedia {
+    url: string;
+    altText: string;
+    position: number;
+}
+interface VariantOption {
+    name: string;
+    value: string;
+}
+interface VariantDimensions {
+    lengthMm?: number;
+    widthMm?: number;
+    heightMm?: number;
+}
+interface Variant {
+    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: string;
+    updatedAt: string;
+}
+interface Product {
+    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: string;
+    updatedAt: string;
+}
+/** The orders a product listing can be requested in; ties break by slug, ascending. */
+declare const PRODUCT_SORT_KEYS: readonly ["newest", "price-asc", "price-desc", "name-asc", "name-desc"];
+type ProductSortKey = (typeof PRODUCT_SORT_KEYS)[number];
+declare const DEFAULT_PRODUCT_SORT: ProductSortKey;
+
+interface Category {
+    id: string;
+    parentId: string | null;
+    name: string;
+    slug: string;
+    description: string;
+    position: number;
+    createdAt: string;
+}
+
+interface CartItem {
+    variantId: string;
+    productId: string;
+    productName: string;
+    variantName: string;
+    priceMinor: number;
+    qty: number;
+    imageUrl: string;
+}
+interface Cart {
+    token: string;
+    customerId: string | null;
+    items: CartItem[];
+    subtotalMinor: number;
+    currency: string;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+type OrderStatus = 'pending' | 'confirmed' | 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'refunded' | 'partially_refunded';
+declare const ORDER_STATUS_TRANSITIONS: Record<OrderStatus, readonly OrderStatus[]>;
+declare function canTransitionOrder(from: OrderStatus, to: OrderStatus): boolean;
+declare function assertOrderTransition(from: OrderStatus, to: OrderStatus): void;
+interface Address {
+    firstName: string;
+    lastName: string;
+    company?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    region: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+}
+interface OrderLineItem {
+    variantId: string;
+    productId: string;
+    productName: string;
+    variantName: string;
+    sku: string;
+    qty: number;
+    unitPriceMinor: number;
+    lineSubtotalMinor: number;
+    lineTaxMinor: number;
+    lineTotalMinor: number;
+    imageUrl: string;
+}
+interface Order {
+    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;
+    /** Money taken for the order, in minor units of its currency; 0 while nothing is captured. */
+    capturedMinor: number;
+    capturedAt: string | null;
+    /** Σ of the order's succeeded refunds (or, for an import or a pre-refund-table order, what was refunded then). */
+    refundedMinor: number;
+    captureMethod: CaptureMethod | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Who took the money: the payments provider, the merchant recording an offline payment, or an imported history. */
+type CaptureMethod = 'provider' | 'manual' | 'import';
+type OrderRefundStatus = 'pending' | 'succeeded' | 'failed';
+/** One refund of an order. `pending` until the provider's answer settles it, and counted against what is refundable. */
+interface OrderRefund {
+    id: string;
+    orderId: string;
+    amountMinor: number;
+    currency: string;
+    providerRefundId: string | null;
+    status: OrderRefundStatus;
+    reason: string | null;
+    actor: string;
+    createdAt: string;
+}
+type PaymentState = 'unpaid' | 'paid' | 'partially_refunded' | 'refunded';
+/** What the admin shows about an order's money: derived from the stored amounts and refunds alone. */
+interface OrderPayment {
+    state: PaymentState;
+    capturedMinor: number;
+    refundedMinor: number;
+    refundableMinor: number;
+    currency: string;
+    refunds: OrderRefund[];
+}
+declare function paymentState(order: Pick<Order, 'capturedMinor' | 'refundedMinor'>): PaymentState;
+/** What can still be refunded: the capture less what was refunded and what is still pending with the provider. */
+declare function refundableMinor(order: Pick<Order, 'capturedMinor' | 'refundedMinor'>, refunds: ReadonlyArray<Pick<OrderRefund, 'amountMinor' | 'status'>>): number;
+interface OrderHistoryEntry {
+    id: string;
+    orderId: string;
+    fromStatus: OrderStatus | null;
+    toStatus: OrderStatus;
+    actor: string;
+    note: string;
+    timestamp: string;
+}
+
+interface CustomerAddress extends Address {
+    id: string;
+    isDefaultBilling: boolean;
+    isDefaultShipping: boolean;
+}
+interface Customer {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    phone: string;
+    addresses: CustomerAddress[];
+    orderCount: number;
+    totalSpentMinor: number;
+    metadata: Record<string, unknown>;
+    /** What an access token grants. Written by seed and admin code only, never taken from `metadata`. */
+    roles: Role[];
+    requiresPasswordReset: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CustomerProfile {
+    customerId: string;
+    orderCount: number;
+    totalSpentMinor: number;
+    segment: string;
+    createdAt: string;
+}
+type Role = 'admin' | 'customer' | 'guest';
+
+type StockAdjustmentReason = 'sale' | 'return' | 'manual' | 'import' | 'reservation-commit' | 'reservation-release';
+interface InventoryReservation {
+    reservationId: string;
+    variantId: string;
+    qty: number;
+    orderRef: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+interface StockAdjustment {
+    id: string;
+    variantId: string;
+    adjustment: number;
+    reason: StockAdjustmentReason;
+    actor: string;
+    previousQty: number;
+    newQty: number;
+    timestamp: string;
+}
+type StockStatus = 'in_stock' | 'low_stock' | 'out_of_stock';
+
+type ReviewModerationStatus = 'pending' | 'approved' | 'rejected';
+interface Review {
+    id: string;
+    productId: string;
+    customerId: string | null;
+    orderId: string | null;
+    rating: number;
+    title: string;
+    body: string;
+    moderationStatus: ReviewModerationStatus;
+    submittedAt: string;
+    moderatedAt: string | null;
+    moderatedBy: string | null;
+}
+interface AggregateRating {
+    productId: string;
+    average: number;
+    count: number;
+    histogram: Record<'1' | '2' | '3' | '4' | '5', number>;
+}
+
+type PaymentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'succeeded' | 'cancelled' | 'failed';
+interface PaymentIntentParams {
+    amountMinor: number;
+    currency: string;
+    orderRef?: string;
+    customerId?: string;
+    /** Where the provider sends its receipt (Stripe's `receipt_email`). */
+    receiptEmail?: string;
+    metadata?: Record<string, string>;
+}
+interface PaymentIntent {
+    id: string;
+    clientSecret: string;
+    amountMinor: number;
+    currency: string;
+    status: PaymentStatus;
+    providerPayload?: Record<string, unknown>;
+}
+/**
+ * What a checkout tells the shopper about their payment: `succeeded` once the order is confirmed, `requires_action`
+ * while the provider waits on the shopper (a Stripe confirmation), `failed` with the reason when it will not complete.
+ */
+interface CheckoutPayment {
+    status: 'succeeded' | 'requires_action' | 'failed';
+    reason?: string;
+}
+interface PaymentCapture {
+    paymentId: string;
+    capturedAmountMinor: number;
+    currency: string;
+    status: PaymentStatus;
+}
+interface Refund {
+    refundId: string;
+    paymentId: string;
+    amountMinor: number;
+    currency: string;
+    reason: string | null;
+    status: 'pending' | 'succeeded' | 'failed';
+}
+interface WebhookResult {
+    verified: boolean;
+    eventId: string;
+    kind: 'payment.captured' | 'payment.failed' | 'payment.refunded' | 'ignored';
+    paymentIntentId?: string;
+    amountMinor?: number;
+    currency?: string;
+    reason?: string;
+    raw?: Record<string, unknown>;
+}
+
+declare const EVT_PRODUCT_CREATED = "product.created.v1";
+declare const EVT_PRODUCT_UPDATED = "product.updated.v1";
+declare const EVT_PRODUCT_DELETED = "product.deleted.v1";
+declare const EVT_PRODUCT_PUBLISHED = "product.published.v1";
+declare const EVT_PRODUCT_UNPUBLISHED = "product.unpublished.v1";
+declare const EVT_CATEGORY_CREATED = "category.created.v1";
+declare const EVT_CATEGORY_UPDATED = "category.updated.v1";
+declare const EVT_CATEGORY_DELETED = "category.deleted.v1";
+declare const EVT_ORDER_PLACED = "order.placed.v1";
+declare const EVT_ORDER_PAID = "order.paid.v1";
+declare const EVT_ORDER_FULFILLED = "order.fulfilled.v1";
+declare const EVT_ORDER_SHIPPED = "order.shipped.v1";
+declare const EVT_ORDER_DELIVERED = "order.delivered.v1";
+declare const EVT_ORDER_CANCELLED = "order.cancelled.v1";
+declare const EVT_ORDER_REFUNDED = "order.refunded.v1";
+declare const EVT_ORDER_PARTIALLY_REFUNDED = "order.partially_refunded.v1";
+declare const EVT_INVENTORY_CHANGED = "inventory.changed.v1";
+declare const EVT_INVENTORY_RESERVED = "inventory.reserved.v1";
+declare const EVT_INVENTORY_RELEASED = "inventory.released.v1";
+declare const EVT_INVENTORY_LOW_STOCK = "inventory.low_stock.v1";
+declare const EVT_INVENTORY_OUT_OF_STOCK = "inventory.out_of_stock.v1";
+declare const EVT_CUSTOMER_CREATED = "customer.created.v1";
+declare const EVT_CUSTOMER_UPDATED = "customer.updated.v1";
+declare const EVT_CUSTOMER_DELETED = "customer.deleted.v1";
+declare const EVT_CUSTOMER_REGISTERED = "customer.created.v1";
+declare const EVT_CART_CREATED = "cart.created.v1";
+declare const EVT_CART_ITEM_ADDED = "cart.item_added.v1";
+declare const EVT_CART_ITEM_REMOVED = "cart.item_removed.v1";
+declare const EVT_CART_UPDATED = "cart.updated.v1";
+declare const EVT_CART_ABANDONED = "cart.abandoned.v1";
+declare const EVT_CART_CONVERTED = "cart.converted.v1";
+declare const EVT_PAYMENT_CAPTURED = "payment.captured.v1";
+declare const EVT_PAYMENT_FAILED = "payment.failed.v1";
+declare const EVT_PAYMENT_REFUNDED = "payment.refunded.v1";
+declare const EVT_ADAPTER_ERROR = "adapter.error.v1";
+declare const STANDARD_EVENT_TYPES: readonly ["product.created.v1", "product.updated.v1", "product.deleted.v1", "product.published.v1", "product.unpublished.v1", "category.created.v1", "category.updated.v1", "category.deleted.v1", "order.placed.v1", "order.paid.v1", "order.fulfilled.v1", "order.shipped.v1", "order.delivered.v1", "order.cancelled.v1", "order.refunded.v1", "order.partially_refunded.v1", "inventory.changed.v1", "inventory.reserved.v1", "inventory.released.v1", "inventory.low_stock.v1", "inventory.out_of_stock.v1", "customer.created.v1", "customer.updated.v1", "customer.deleted.v1", "cart.created.v1", "cart.item_added.v1", "cart.item_removed.v1", "cart.updated.v1", "cart.abandoned.v1", "cart.converted.v1", "payment.captured.v1", "payment.failed.v1", "payment.refunded.v1", "adapter.error.v1"];
+
+interface ProductSnapshot extends Product {
+    variants: Variant[];
+    categoryIds: string[];
+}
+interface ProductCreatedV1Payload {
+    product: ProductSnapshot;
+}
+interface ProductUpdatedV1Payload {
+    product: ProductSnapshot;
+}
+interface ProductDeletedV1Payload {
+    productId: string;
+    slug: string;
+}
+interface ProductPublishedV1Payload {
+    productId: string;
+    slug: string;
+}
+interface ProductUnpublishedV1Payload {
+    productId: string;
+    slug: string;
+}
+interface CategoryCreatedV1Payload {
+    category: Category;
+}
+interface CategoryUpdatedV1Payload {
+    category: Category;
+}
+interface CategoryDeletedV1Payload {
+    categoryId: string;
+    slug: string;
+}
+interface OrderPlacedV1Payload {
+    order: Order;
+}
+interface OrderPaidV1Payload {
+    orderId: string;
+    paymentIntentId: string;
+    amountMinor: number;
+    currency: string;
+}
+interface OrderFulfilledV1Payload {
+    orderId: string;
+}
+interface OrderShippedV1Payload {
+    orderId: string;
+    trackingNumber: string;
+    carrier: string;
+}
+interface OrderDeliveredV1Payload {
+    orderId: string;
+}
+interface OrderCancelledV1Payload {
+    orderId: string;
+    reason: string;
+}
+interface OrderRefundedV1Payload {
+    orderId: string;
+    refundId: string;
+    amountMinor: number;
+    currency: string;
+    reason: string;
+}
+interface OrderPartiallyRefundedV1Payload {
+    orderId: string;
+    refundId: string;
+    amountMinor: number;
+    currency: string;
+    reason: string;
+}
+interface InventoryChangedV1Payload {
+    variantId: string;
+    previousQty: number;
+    newQty: number;
+    reason: StockAdjustmentReason;
+}
+interface InventoryReservedV1Payload {
+    variantId: string;
+    qty: number;
+    reservationId: string;
+    expiresAt: string;
+}
+interface InventoryReleasedV1Payload {
+    variantId: string;
+    qty: number;
+    reservationId: string;
+    reason: 'expired' | 'cancelled' | 'abandoned' | 'committed';
+}
+interface InventoryLowStockV1Payload {
+    variantId: string;
+    currentQty: number;
+    threshold: number;
+}
+interface InventoryOutOfStockV1Payload {
+    variantId: string;
+}
+interface CustomerCreatedV1Payload {
+    customerId: string;
+    email: string;
+}
+interface CustomerUpdatedV1Payload {
+    customerId: string;
+}
+interface CustomerDeletedV1Payload {
+    customerId: string;
+}
+interface CartCreatedV1Payload {
+    cartId: string;
+    token: string;
+}
+interface CartItemAddedV1Payload {
+    cartId: string;
+    variantId: string;
+    qty: number;
+}
+interface CartItemRemovedV1Payload {
+    cartId: string;
+    variantId: string;
+}
+interface CartUpdatedV1Payload {
+    cartId: string;
+    itemCount: number;
+    totalMinor: number;
+}
+interface CartAbandonedV1Payload {
+    cartId: string;
+    lastActivityAt: string;
+}
+interface CartConvertedV1Payload {
+    cartId: string;
+    orderId: string;
+}
+interface PaymentCapturedV1Payload {
+    paymentId: string;
+    orderId: string;
+    amountMinor: number;
+    currency: string;
+}
+interface PaymentFailedV1Payload {
+    paymentId: string;
+    orderId: string;
+    reason: string;
+}
+interface PaymentRefundedV1Payload {
+    paymentId: string;
+    orderId: string;
+    refundId: string;
+    amountMinor: number;
+    currency: string;
+}
+interface AdapterErrorV1Payload {
+    adapterType: string;
+    adapterName: string;
+    error: {
+        code: string;
+        message: string;
+    };
+    context: Record<string, unknown>;
+}
+
+interface NymbalEventMap {
+    [EVT_PRODUCT_CREATED]: ProductCreatedV1Payload;
+    [EVT_PRODUCT_UPDATED]: ProductUpdatedV1Payload;
+    [EVT_PRODUCT_DELETED]: ProductDeletedV1Payload;
+    [EVT_PRODUCT_PUBLISHED]: ProductPublishedV1Payload;
+    [EVT_PRODUCT_UNPUBLISHED]: ProductUnpublishedV1Payload;
+    [EVT_CATEGORY_CREATED]: CategoryCreatedV1Payload;
+    [EVT_CATEGORY_UPDATED]: CategoryUpdatedV1Payload;
+    [EVT_CATEGORY_DELETED]: CategoryDeletedV1Payload;
+    [EVT_ORDER_PLACED]: OrderPlacedV1Payload;
+    [EVT_ORDER_PAID]: OrderPaidV1Payload;
+    [EVT_ORDER_FULFILLED]: OrderFulfilledV1Payload;
+    [EVT_ORDER_SHIPPED]: OrderShippedV1Payload;
+    [EVT_ORDER_DELIVERED]: OrderDeliveredV1Payload;
+    [EVT_ORDER_CANCELLED]: OrderCancelledV1Payload;
+    [EVT_ORDER_REFUNDED]: OrderRefundedV1Payload;
+    [EVT_ORDER_PARTIALLY_REFUNDED]: OrderPartiallyRefundedV1Payload;
+    [EVT_INVENTORY_CHANGED]: InventoryChangedV1Payload;
+    [EVT_INVENTORY_RESERVED]: InventoryReservedV1Payload;
+    [EVT_INVENTORY_RELEASED]: InventoryReleasedV1Payload;
+    [EVT_INVENTORY_LOW_STOCK]: InventoryLowStockV1Payload;
+    [EVT_INVENTORY_OUT_OF_STOCK]: InventoryOutOfStockV1Payload;
+    [EVT_CUSTOMER_CREATED]: CustomerCreatedV1Payload;
+    [EVT_CUSTOMER_UPDATED]: CustomerUpdatedV1Payload;
+    [EVT_CUSTOMER_DELETED]: CustomerDeletedV1Payload;
+    [EVT_CART_CREATED]: CartCreatedV1Payload;
+    [EVT_CART_ITEM_ADDED]: CartItemAddedV1Payload;
+    [EVT_CART_ITEM_REMOVED]: CartItemRemovedV1Payload;
+    [EVT_CART_UPDATED]: CartUpdatedV1Payload;
+    [EVT_CART_ABANDONED]: CartAbandonedV1Payload;
+    [EVT_CART_CONVERTED]: CartConvertedV1Payload;
+    [EVT_PAYMENT_CAPTURED]: PaymentCapturedV1Payload;
+    [EVT_PAYMENT_FAILED]: PaymentFailedV1Payload;
+    [EVT_PAYMENT_REFUNDED]: PaymentRefundedV1Payload;
+    [EVT_ADAPTER_ERROR]: AdapterErrorV1Payload;
+}
+type NymbalEventType = keyof NymbalEventMap;
+type PayloadOf<E extends NymbalEventType> = NymbalEventMap[E];
+
+type NymbalEnvironment = 'production' | 'staging' | 'development';
+interface EventMetadata {
+    storeId: string;
+    environment: NymbalEnvironment;
+    version: string;
+}
+interface NymbalEvent<T = unknown> {
+    id: string;
+    type: string;
+    timestamp: string;
+    source: string;
+    correlationId: string;
+    payload: T;
+    metadata: EventMetadata;
+}
+type EventHandler<T = unknown> = (event: NymbalEvent<T>) => Promise<void> | void;
+
+type HealthStatus = 'healthy' | 'degraded' | 'down';
+interface HealthReport {
+    status: HealthStatus;
+    detail?: string;
+}
+interface AdapterBase {
+    readonly capabilities: readonly string[];
+    readonly producesEvents: readonly string[];
+    readonly consumesEvents: readonly string[];
+    initialize(config: unknown): Promise<void>;
+    healthCheck(): Promise<HealthReport>;
+}
+
+interface PutOptions {
+    ttl?: number;
+    conditionKey?: string;
+    conditionValue?: unknown;
+}
+interface QueryParams {
+    /** A `value` of `'*'` matches every document in the collection (a full scan). */
+    partitionKey: {
+        field: string;
+        value: unknown;
+    };
+    sortKey?: {
+        field: string;
+        operator: 'eq' | 'gt' | 'lt' | 'between';
+        value: unknown;
+    };
+    /**
+     * Orders the results without filtering them; `field` may be a dotted path (`priceRange.minMinor`). Ties break by
+     * document key, ascending, so the order is total. A cursor issued under one `orderBy` is refused under another.
+     */
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+        nulls?: 'last';
+    };
+    limit?: number;
+    cursor?: string;
+    ascending?: boolean;
+}
+interface QueryResult<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+interface DocumentStoreAdapter {
+    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>;
+}
+
+interface RetryPolicy {
+    maxAttempts: number;
+    backoff: 'exponential' | 'linear' | 'fixed';
+    initialDelayMs?: number;
+}
+interface SubscriptionConfig {
+    retryPolicy?: RetryPolicy;
+    deadLetterQueue?: string;
+    batchSize?: number;
+    name?: string;
+    /** The subscriber only maintains derived state (a projection, a search index): it also receives `replay`. */
+    derived?: boolean;
+}
+interface Subscription {
+    id: string;
+    patterns: string[];
+    unsubscribe(): Promise<void>;
+}
+interface EventBusAdapter {
+    publish<T>(event: NymbalEvent<T>): Promise<void>;
+    publishBatch(events: NymbalEvent<unknown>[]): Promise<void>;
+    /** Delivers to `derived` subscriptions only, so rebuilding derived state never triggers side effects. */
+    replay(events: NymbalEvent<unknown>[]): Promise<void>;
+    subscribe(eventPattern: string | string[], handler: EventHandler, config?: SubscriptionConfig): Promise<Subscription>;
+    unsubscribe(subscription: Subscription): Promise<void>;
+    close(): Promise<void>;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+interface RequestAuth {
+    userId?: string;
+    roles?: string[];
+    token?: string;
+}
+interface Logger {
+    trace(obj: unknown, msg?: string): void;
+    debug(obj: unknown, msg?: string): void;
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+interface RequestContext<TBody = unknown, TQuery = Record<string, string | string[] | undefined>, TParams = Record<string, string>> {
+    method: HttpMethod;
+    path: string;
+    url: string;
+    params: TParams;
+    query: TQuery;
+    body: TBody;
+    rawBody?: Buffer;
+    headers: Record<string, string | string[] | undefined>;
+    cookies: Record<string, string>;
+    auth?: RequestAuth;
+    requestId: string;
+    correlationId: string;
+    logger: Logger;
+    ip: string;
+}
+interface ResponseCookie {
+    name: string;
+    value: string;
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+}
+interface ResponseEnvelope<T = unknown> {
+    status: number;
+    headers?: Record<string, string>;
+    body?: T;
+    cookies?: ResponseCookie[];
+}
+type RouteHandler<TBody = unknown, TQuery = Record<string, string | string[] | undefined>, TParams = Record<string, string>, TResponse = unknown> = (ctx: RequestContext<TBody, TQuery, TParams>) => Promise<ResponseEnvelope<TResponse>> | ResponseEnvelope<TResponse>;
+interface RouteOptions {
+    name?: string;
+    csrf?: boolean;
+    rateLimit?: string;
+    rawBody?: boolean;
+}
+type MiddlewareHandler = (ctx: RequestContext) => Promise<ResponseEnvelope | void> | ResponseEnvelope | void;
+interface SseEvent {
+    id?: string;
+    event?: string;
+    data: unknown;
+}
+interface StreamContext {
+    send(event: SseEvent): void;
+    close(): void;
+    onClose(callback: () => void): void;
+}
+type StreamHandler = (ctx: RequestContext, stream: StreamContext) => Promise<void> | void;
+interface HttpAdapter {
+    registerRoute(method: HttpMethod, path: string, handler: RouteHandler, options?: RouteOptions): void;
+    registerStreamRoute(method: 'GET', path: string, handler: StreamHandler, options?: RouteOptions): void;
+    registerMiddleware(middleware: MiddlewareHandler): void;
+    setDefaultHeaders(headers: Record<string, string>): void;
+    start(port: number, host?: string): Promise<void>;
+    stop(): Promise<void>;
+}
+
+type RateLimitAction = 'block' | 'challenge' | 'throttle';
+interface RateLimitRule {
+    requests: number;
+    window: string;
+    action: RateLimitAction;
+}
+interface RateLimitDecision {
+    allowed: boolean;
+    retryAfterSeconds?: number;
+    action: RateLimitAction;
+}
+interface SecurityConfigLike {
+    rateLimit: Record<string, RateLimitRule>;
+    csrf: boolean;
+    headers: {
+        hsts: boolean;
+        contentSecurityPolicy: string;
+        referrerPolicy: string;
+        xFrameOptions: string;
+    };
+    [key: string]: unknown;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: Array<{
+        code: string;
+        message: string;
+        path?: string;
+    }>;
+}
+interface DriftReport {
+    drift: boolean;
+    differences: Array<{
+        path: string;
+        configured: unknown;
+        actual: unknown;
+    }>;
+}
+interface SecurityState {
+    rulesApplied: string[];
+    lastValidatedAt: string;
+}
+interface SecurityAdapter extends AdapterBase {
+    applyMiddleware(app: HttpAdapter, config: SecurityConfigLike): Promise<void>;
+    validate(config: SecurityConfigLike): Promise<ValidationResult>;
+    drift?(config: SecurityConfigLike): Promise<DriftReport>;
+    inspect?(): Promise<SecurityState>;
+}
+
+interface CommerceAdapter extends AdapterBase {
+    readonly providerName: string;
+}
+interface RefundOptions {
+    /** The same key on a retry makes the provider refund at most once. */
+    idempotencyKey?: string;
+    /** The order's currency: what a provider that no longer holds the payment answers in. */
+    currency?: string;
+}
+interface PaymentsAdapter extends CommerceAdapter {
+    readonly kind: 'payments';
+    createPaymentIntent(params: PaymentIntentParams): Promise<PaymentIntent>;
+    capturePayment(intentId: string, amountMinor?: number): Promise<PaymentCapture>;
+    /** Throws `PaymentError('refund_rejected')` when no money moved, `PaymentError('refund_unknown')` when it may have. */
+    refund(paymentId: string, amountMinor?: number, reason?: string, opts?: RefundOptions): Promise<Refund>;
+    getPaymentStatus(intentId: string): Promise<PaymentStatus>;
+    /** The intent as the provider holds it now, client secret included: what a shopper needs to pay it again. */
+    getPaymentIntent(intentId: string): Promise<PaymentIntent>;
+    /** Cancels an intent that has not been paid; throws `PaymentError('cancel_refused')` when the provider will not
+     *  (the intent is processing or already captured). */
+    cancelPaymentIntent(intentId: string): Promise<void>;
+    parseWebhook(rawBody: Buffer | string, signature: string): Promise<WebhookResult>;
+}
+interface TransactionalEmail {
+    template: string;
+    to: string;
+    vars: Record<string, unknown>;
+    locale?: string;
+}
+interface EmailSendResult {
+    messageId: string | null;
+    accepted: boolean;
+}
+interface EmailAdapter extends CommerceAdapter {
+    readonly kind: 'email';
+    sendTransactional(params: TransactionalEmail): Promise<EmailSendResult>;
+    syncCustomerToList(customer: CustomerProfile): Promise<void>;
+    removeCustomerFromList(customerId: string): Promise<void>;
+}
+interface PaginationParams {
+    limit?: number;
+    cursor?: string;
+}
+interface ReviewsResult {
+    items: Review[];
+    nextCursor: string | null;
+}
+interface ReviewSubmission {
+    productId: string;
+    customerId: string | null;
+    orderId: string | null;
+    rating: number;
+    title: string;
+    body: string;
+}
+interface ReviewResult {
+    review: Review;
+}
+interface ReviewsAdapter extends CommerceAdapter {
+    readonly kind: 'reviews';
+    getProductReviews(productId: string, params?: PaginationParams & {
+        status?: ReviewModerationStatus;
+    }): Promise<ReviewsResult>;
+    getAggregateRating(productId: string): Promise<AggregateRating>;
+    submitReview(review: ReviewSubmission): Promise<ReviewResult>;
+    requestReview(orderId: string): Promise<void>;
+}
+interface SearchDocument {
+    id: string;
+    type: string;
+    fields: Record<string, unknown>;
+}
+interface IndexResult {
+    indexed: number;
+}
+interface SearchParams {
+    limit?: number;
+    cursor?: string;
+    filters?: Record<string, unknown>;
+    sort?: Array<{
+        field: string;
+        direction: 'asc' | 'desc';
+    }>;
+}
+interface SearchResult {
+    items: SearchDocument[];
+    total: number;
+    nextCursor: string | null;
+}
+interface FacetParams {
+    limit?: number;
+    filters?: Record<string, unknown>;
+}
+interface Facet {
+    field: string;
+    label: string;
+    values: Array<{
+        value: string;
+        label?: string;
+        count?: number;
+    }>;
+}
+interface SearchAdapter extends CommerceAdapter {
+    readonly kind: 'search';
+    index(documents: SearchDocument[]): Promise<IndexResult>;
+    remove(documentIds: string[]): Promise<void>;
+    search(query: string, params?: SearchParams): Promise<SearchResult>;
+    facet(field: string, params?: FacetParams): Promise<Facet>;
+}
+interface AnalyticsAdapter extends CommerceAdapter {
+    readonly kind: 'analytics';
+    track(event: string, properties: Record<string, unknown>): Promise<void>;
+    identify(userId: string, traits: Record<string, unknown>): Promise<void>;
+}
+interface ShippingRateParams {
+    fromPostalCode: string;
+    toPostalCode: string;
+    toCountry: string;
+    weightGrams: number;
+    currency: string;
+}
+interface ShippingRate {
+    carrier: string;
+    service: string;
+    amountMinor: number;
+    currency: string;
+    estimatedDays: number;
+}
+interface ShippingLabelParams {
+    orderId: string;
+    carrier: string;
+    service: string;
+}
+interface ShippingLabel {
+    labelUrl: string;
+    trackingNumber: string;
+    carrier: string;
+}
+interface ShippingTracking {
+    status: string;
+    lastUpdateAt: string;
+}
+interface ShippingAdapter extends CommerceAdapter {
+    readonly kind: 'shipping';
+    rate(params: ShippingRateParams): Promise<ShippingRate[]>;
+    createLabel(params: ShippingLabelParams): Promise<ShippingLabel>;
+    track(trackingNumber: string): Promise<ShippingTracking>;
+}
+interface TaxLine {
+    amountMinor: number;
+    qty: number;
+}
+interface TaxCalculationParams {
+    currency: string;
+    shippingCountry: string;
+    shippingRegion: string;
+    lines: TaxLine[];
+}
+interface TaxCalculationResult {
+    totalTaxMinor: number;
+    ratePerLine: Array<{
+        taxMinor: number;
+    }>;
+}
+interface TaxAdapter extends CommerceAdapter {
+    readonly kind: 'tax';
+    calculate(params: TaxCalculationParams): Promise<TaxCalculationResult>;
+}
+interface AiAdapter extends CommerceAdapter {
+    readonly kind: 'ai';
+    embed(texts: string[]): Promise<number[][]>;
+    complete(prompt: string, opts?: {
+        maxTokens?: number;
+    }): Promise<string>;
+}
+
+export { type AdapterBase, AdapterError, type AdapterErrorV1Payload, type Address, type AggregateRating, type AiAdapter, type AnalyticsAdapter, AuthError, type CaptureMethod, type Cart, type CartAbandonedV1Payload, type CartConvertedV1Payload, type CartCreatedV1Payload, type CartItem, type CartItemAddedV1Payload, type CartItemRemovedV1Payload, type CartUpdatedV1Payload, type Category, type CategoryCreatedV1Payload, type CategoryDeletedV1Payload, type CategoryUpdatedV1Payload, CheckoutError, type CheckoutPayment, type CommerceAdapter, ConfigError, type Customer, type CustomerAddress, type CustomerCreatedV1Payload, type CustomerDeletedV1Payload, type CustomerProfile, type CustomerUpdatedV1Payload, DEFAULT_PRODUCT_SORT, type DocumentStoreAdapter, type DriftReport, EVT_ADAPTER_ERROR, EVT_CART_ABANDONED, EVT_CART_CONVERTED, EVT_CART_CREATED, EVT_CART_ITEM_ADDED, EVT_CART_ITEM_REMOVED, EVT_CART_UPDATED, EVT_CATEGORY_CREATED, EVT_CATEGORY_DELETED, EVT_CATEGORY_UPDATED, EVT_CUSTOMER_CREATED, EVT_CUSTOMER_DELETED, EVT_CUSTOMER_REGISTERED, EVT_CUSTOMER_UPDATED, EVT_INVENTORY_CHANGED, EVT_INVENTORY_LOW_STOCK, EVT_INVENTORY_OUT_OF_STOCK, EVT_INVENTORY_RELEASED, EVT_INVENTORY_RESERVED, EVT_ORDER_CANCELLED, EVT_ORDER_DELIVERED, EVT_ORDER_FULFILLED, EVT_ORDER_PAID, EVT_ORDER_PARTIALLY_REFUNDED, EVT_ORDER_PLACED, EVT_ORDER_REFUNDED, EVT_ORDER_SHIPPED, EVT_PAYMENT_CAPTURED, EVT_PAYMENT_FAILED, EVT_PAYMENT_REFUNDED, EVT_PRODUCT_CREATED, EVT_PRODUCT_DELETED, EVT_PRODUCT_PUBLISHED, EVT_PRODUCT_UNPUBLISHED, EVT_PRODUCT_UPDATED, type EmailAdapter, type EmailSendResult, type ErrorContext, type EventBusAdapter, type EventHandler, type EventMetadata, type Facet, type FacetParams, type HealthReport, type HealthStatus, type HttpAdapter, HttpError, type HttpMethod, type IndexResult, type InventoryChangedV1Payload, type InventoryLowStockV1Payload, type InventoryOutOfStockV1Payload, type InventoryReleasedV1Payload, type InventoryReservation, type InventoryReservedV1Payload, type Logger, type MiddlewareHandler, type Money, NotFoundError, type NymbalEnvironment, NymbalError, type NymbalEvent, type NymbalEventMap, type NymbalEventType, ORDER_STATUS_TRANSITIONS, type Order, type OrderCancelledV1Payload, OrderConflictError, type OrderDeliveredV1Payload, type OrderFulfilledV1Payload, type OrderHistoryEntry, type OrderLineItem, type OrderPaidV1Payload, type OrderPartiallyRefundedV1Payload, type OrderPayment, type OrderPlacedV1Payload, type OrderRefund, type OrderRefundStatus, type OrderRefundedV1Payload, type OrderShippedV1Payload, type OrderStatus, PRODUCT_SORT_KEYS, type PaginationParams, type PayloadOf, type PaymentCapture, type PaymentCapturedV1Payload, PaymentError, type PaymentFailedV1Payload, type PaymentIntent, type PaymentIntentParams, type PaymentRefundedV1Payload, type PaymentState, type PaymentStatus, type PaymentsAdapter, type Product, type ProductCreatedV1Payload, type ProductDeletedV1Payload, type ProductMedia, type ProductPublishedV1Payload, type ProductSnapshot, type ProductSortKey, type ProductStatus, type ProductType, type ProductUnpublishedV1Payload, type ProductUpdatedV1Payload, type PutOptions, type QueryParams, type QueryResult, type RateLimitAction, type RateLimitDecision, type RateLimitRule, type Refund, type RefundOptions, type RequestAuth, type RequestContext, type ResponseCookie, type ResponseEnvelope, type RetryPolicy, type Review, type ReviewModerationStatus, type ReviewResult, type ReviewSubmission, type ReviewsAdapter, type ReviewsResult, type Role, type RouteHandler, type RouteOptions, STANDARD_EVENT_TYPES, type SearchAdapter, type SearchDocument, type SearchParams, type SearchResult, type SecurityAdapter, type SecurityConfigLike, type SecurityState, type ShippingAdapter, type ShippingLabel, type ShippingLabelParams, type ShippingRate, type ShippingRateParams, type ShippingTracking, type SseEvent, StatusTransitionError, type StockAdjustment, type StockAdjustmentReason, type StockStatus, type StreamContext, type StreamHandler, type Subscription, type SubscriptionConfig, type TaxAdapter, type TaxCalculationParams, type TaxCalculationResult, type TaxLine, type TransactionalEmail, ValidationError, type ValidationResult, type Variant, type VariantDimensions, type VariantOption, type VariantStatus, type WebhookResult, add, allocate, assertMinorUnits, assertOrderTransition, canTransitionOrder, money, mulBy, paymentState, refundableMinor, sub, sumMoney };