@nymbalhq/types 1.4.0 → 1.6.0

package/dist/index.d.ts

@@ -24,6 +24,7 @@ declare class ValidationError extends NymbalError {
     constructor(message: string, options?: {
         cause?: unknown;
         context?: ErrorContext;
+        code?: string;
     });
 }
 declare class NotFoundError extends NymbalError {
@@ -71,6 +72,19 @@ declare class CheckoutError extends NymbalError {
         context?: ErrorContext;
     });
 }
+/** A cart command that would take a line above `max`; `onCart` is what the line held before it. */
+declare class CartLimitError extends NymbalError {
+    constructor(variantId: string, max: number, onCart: number);
+}
+/** Why a review was not taken. `not_a_buyer` is reserved: any signed-in customer may review. */
+type ReviewRefusal = 'submit_unsupported' | 'already_reviewed' | 'not_a_buyer' | 'rejected';
+declare class ReviewRefusedError extends NymbalError {
+    readonly refusal: ReviewRefusal;
+    constructor(refusal: ReviewRefusal, message?: string, options?: {
+        cause?: unknown;
+        context?: ErrorContext;
+    });
+}
 declare class StatusTransitionError extends NymbalError {
     constructor(entity: string, fromStatus: string, toStatus: string, options?: {
         cause?: unknown;
@@ -155,26 +169,6 @@ interface Category {
     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;
@@ -204,6 +198,10 @@ interface OrderLineItem {
     lineTotalMinor: number;
     imageUrl: string;
 }
+/** Where an order came from: the storefront, an import, or the shopping agent that opened its cart. */
+type OrderSource = 'storefront' | 'import' | `agent:${string}`;
+/** The source a cart or order opened by the named agent carries. */
+declare function agentSource(name: string): `agent:${string}`;
 interface Order {
     id: string;
     orderNumber: string;
@@ -229,6 +227,7 @@ interface Order {
     /** Σ 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;
+    source: OrderSource;
     createdAt: string;
     updatedAt: string;
 }
@@ -237,6 +236,13 @@ interface Order {
  * the key stays out of access logs that record request URLs.
  */
 declare const ORDER_KEY_HEADER = "x-nymbal-order-key";
+/** The request header that carries the order's email beside an expired order key. Never a query parameter either. */
+declare const ORDER_EMAIL_HEADER = "x-nymbal-order-email";
+/**
+ * The API's attestation of a shopper's address on a page request it forwards to the storefront. The storefront server
+ * echoes it on the API calls it makes for that shopper, so they count against the shopper's address, not its own.
+ */
+declare const SHOPPER_ATTESTATION_HEADER = "x-nymbal-shopper";
 /** 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';
@@ -275,6 +281,33 @@ interface OrderHistoryEntry {
     timestamp: string;
 }
 
+/** The most of one variant a cart line holds. */
+declare const CART_LINE_MAX_QTY = 99;
+interface CartItem {
+    variantId: string;
+    productId: string;
+    /** The product page's slug; lines stored before lines carried one have none. */
+    productSlug?: string;
+    productName: string;
+    variantName: string;
+    priceMinor: number;
+    qty: number;
+    imageUrl: string;
+}
+/** Who opened a cart: the storefront or a shopping agent. An import opens none. */
+type CartSource = Exclude<OrderSource, 'import'>;
+interface Cart {
+    token: string;
+    customerId: string | null;
+    items: CartItem[];
+    subtotalMinor: number;
+    currency: string;
+    source: CartSource;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
 /** The lifecycle events an order's timeline shows, each one from an `order_history` row. */
 declare const ORDER_TIMELINE_KINDS: readonly ["placed", "paid", "shipped", "delivered", "cancelled", "partially_refunded", "refunded"];
 type OrderTimelineKind = (typeof ORDER_TIMELINE_KINDS)[number];
@@ -283,8 +316,17 @@ interface OrderTimelineEntry {
     /** ISO 8601, UTC. */
     at: string;
 }
-/** An order as a storefront reads it; `timeline` is optional so an adapter that returns a plain `Order` still fits. */
-interface ShopperOrder extends Order {
+/** A shipping address as an order's key holder reads it: no phone, no company. */
+type ShopperAddress = Omit<Address, 'phone' | 'company'>;
+/** What only the order's signed-in owner reads, or the store's own records, beside what its key holder reads. */
+type OwnerOrStoreField = 'id' | 'email' | 'billingAddress' | 'customerId' | 'sequence' | 'capturedMinor' | 'capturedAt' | 'refundedMinor' | 'captureMethod' | 'notes' | 'metadata' | 'paymentIntentId' | 'source' | 'updatedAt';
+/**
+ * An order as a storefront reads it. A key holder reads the confirmation page's fields; its owner's session adds the
+ * email, both full addresses and the order's id. Every other field is optional, so an adapter that returns a plain
+ * `Order` still fits.
+ */
+interface ShopperOrder extends Omit<Order, OwnerOrStoreField | 'shippingAddress'>, Partial<Pick<Order, OwnerOrStoreField>> {
+    shippingAddress: ShopperAddress;
     timeline?: OrderTimelineEntry[];
 }
 
@@ -353,6 +395,25 @@ interface Review {
     moderatedAt: string | null;
     moderatedBy: string | null;
 }
+/** A review as the public list publishes it: no customer or order id, only whether a purchase verified it. */
+interface PublicReview {
+    id: string;
+    productId: string;
+    rating: number;
+    title: string;
+    body: string;
+    verified: boolean;
+    submittedAt: string;
+}
+interface PublicReviewsResult {
+    items: PublicReview[];
+    nextCursor: string | null;
+}
+/** A product's rating as the product routes serve it: the average to one decimal and the approved review count. */
+interface ProductRating {
+    average: number;
+    count: number;
+}
 interface AggregateRating {
     productId: string;
     average: number;
@@ -369,6 +430,11 @@ interface PaymentIntentParams {
     /** Where the provider sends its receipt (Stripe's `receipt_email`). */
     receiptEmail?: string;
     metadata?: Record<string, string>;
+    /**
+     * A payment credential an agent was granted for this charge (a Stripe Shared Payment Token): the intent is confirmed
+     * with it at creation. Only an adapter with the `delegated` capability takes one.
+     */
+    delegatedToken?: string;
 }
 interface PaymentIntent {
     id: string;
@@ -434,6 +500,8 @@ declare const EVT_ORDER_REFUNDED = "order.refunded.v1";
 declare const EVT_ORDER_PARTIALLY_REFUNDED = "order.partially_refunded.v1";
 declare const EVT_ORDER_STATUS_CHANGED = "order.status_changed.v1";
 declare const EVT_ORDER_CONFIRMATION_RESEND_REQUESTED = "order.confirmation_resend_requested.v1";
+/** An imported order taken back out of the store, with every row it owned. */
+declare const EVT_ORDER_DELETED = "order.deleted.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";
@@ -455,12 +523,23 @@ 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_ALERT_REQUESTED = "alert.requested.v1";
+/** A subscribe for an alert already active: the subscription stands and nothing is sent. */
+declare const EVT_ALERT_REPEATED = "alert.repeated.v1";
 declare const EVT_ALERT_CONFIRMED = "alert.confirmed.v1";
 declare const EVT_ALERT_UNSUBSCRIBED = "alert.unsubscribed.v1";
 declare const EVT_ALERT_SENT = "alert.sent.v1";
+/** A pending subscription's confirmation was sent; another goes only once the confirmation interval has passed. */
+declare const EVT_ALERT_CONFIRMATION_SENT = "alert.confirmation_sent.v1";
+/** A review the reviews adapter took for the store; the kernel resolved its reviewer and the order it is verified by. */
+declare const EVT_REVIEW_SUBMITTED = "review.submitted.v1";
+declare const EVT_PROPOSAL_CREATED = "proposal.created.v1";
+declare const EVT_PROPOSAL_APPROVED = "proposal.approved.v1";
+declare const EVT_PROPOSAL_REJECTED = "proposal.rejected.v1";
+declare const EVT_PROPOSAL_APPLIED = "proposal.applied.v1";
+declare const EVT_PROPOSAL_FAILED = "proposal.failed.v1";
 declare const EVT_ADAPTER_ERROR = "adapter.error.v1";
 declare const EVT_SETTINGS_CHANGED = "settings.changed.v1";
-declare const STANDARD_EVENT_TYPES: readonly ["product.created.v1", "product.updated.v1", "product.deleted.v1", "product.published.v1", "product.unpublished.v1", "product.viewed.v1", "product.restocked.v1", "product.variant_price_changed.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", "order.status_changed.v1", "order.confirmation_resend_requested.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", "visitor.merged.v1", "cart.created.v1", "cart.item_added.v1", "cart.item_removed.v1", "cart.updated.v1", "cart.abandoned.v1", "cart.converted.v1", "payment.intent_created.v1", "payment.captured.v1", "payment.failed.v1", "payment.refunded.v1", "alert.requested.v1", "alert.confirmed.v1", "alert.unsubscribed.v1", "alert.sent.v1", "adapter.error.v1", "settings.changed.v1"];
+declare const STANDARD_EVENT_TYPES: readonly ["product.created.v1", "product.updated.v1", "product.deleted.v1", "product.published.v1", "product.unpublished.v1", "product.viewed.v1", "product.restocked.v1", "product.variant_price_changed.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", "order.status_changed.v1", "order.confirmation_resend_requested.v1", "order.deleted.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", "visitor.merged.v1", "cart.created.v1", "cart.item_added.v1", "cart.item_removed.v1", "cart.updated.v1", "cart.abandoned.v1", "cart.converted.v1", "payment.intent_created.v1", "payment.captured.v1", "payment.failed.v1", "payment.refunded.v1", "alert.requested.v1", "alert.repeated.v1", "alert.confirmed.v1", "alert.unsubscribed.v1", "alert.sent.v1", "alert.confirmation_sent.v1", "review.submitted.v1", "proposal.created.v1", "proposal.approved.v1", "proposal.rejected.v1", "proposal.applied.v1", "proposal.failed.v1", "adapter.error.v1", "settings.changed.v1"];
 
 /** What a shopper asks to be told about a variant: that it is back in stock, or that its price dropped. */
 type AlertKind = 'back_in_stock' | 'price_drop';
@@ -470,6 +549,114 @@ type AlertKind = 'back_in_stock' | 'price_drop';
  */
 type AlertStatus = 'pending' | 'active' | 'fired' | 'unsubscribed';
 
+/** Where an agent's write stands: waiting, decided, then run. */
+type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'applied' | 'failed';
+/** Who decided a proposal: an admin, or a policy the store's config sets. */
+type ProposalDecider = {
+    kind: 'admin';
+    id: string;
+} | {
+    kind: 'policy';
+    rule: 'agents.mcp.writes' | 'agents.autoApprove';
+};
+/** One proposal as the admin reads it. A handle's value (a cart id) is never served: only its argument's name. */
+interface ProposalView {
+    id: string;
+    tool: string;
+    title: string;
+    command: string;
+    /** The arguments the agent sent, less its idempotency key and its handles. */
+    args: Record<string, unknown>;
+    handles: string[];
+    idempotencyKey: string | null;
+    status: ProposalStatus;
+    proposer: {
+        userId: string | null;
+        agent: {
+            name: string;
+            version?: string;
+        };
+    };
+    correlationId: string;
+    createdAt: string;
+    decision?: {
+        by: ProposalDecider;
+        at: string;
+        reason?: string;
+    };
+    /** What the route answered when the proposal ran. */
+    outcome?: {
+        status: number;
+        code?: string;
+        message?: string;
+    };
+    /** What a pending write would change, read from the store when the proposal is read on its own. */
+    preview?: ProposalPreview;
+}
+/** The commands whose pending proposal, read on its own, carries a preview. */
+declare const PREVIEWED_COMMANDS: readonly string[];
+/** One value a pending write changes, as it is now beside what the write would make it. */
+interface ProposalChange {
+    /** What changes, as the admin reads it: "Name", "Price of Large", "Stock", "Refunded", "Status", "Media". */
+    label: string;
+    /** `money`: minor units of `ProposalPreview.currency`; `collection`: item or key counts, with `changed`. */
+    kind: 'value' | 'money' | 'collection';
+    current: string | number | null;
+    proposed: string | number | null;
+    changed?: boolean;
+}
+/** What a pending write acts on and what it changes there. */
+interface ProposalPreview {
+    /** What the write acts on, read from the store now; null when the id names nothing. */
+    target: {
+        kind: 'product' | 'variant' | 'order';
+        id: string;
+        label: string;
+    } | null;
+    changes: ProposalChange[];
+    currency: string;
+}
+interface ProposalPage {
+    items: ProposalView[];
+    nextCursor: string | null;
+    /** Every proposal still waiting for a decision, whatever the page holds. */
+    pending: number;
+}
+
+/** Where a Settings field's value comes from: the config block, its declared env, a saved value, or nowhere. */
+type SettingSourceName = 'config' | 'env' | 'settings';
+/** One declared field as `GET /api/admin/settings` lists it; a secret never carries its value. */
+interface SettingFieldView {
+    path: string;
+    label: string;
+    secret: boolean;
+    state: 'unset' | 'set';
+    source: SettingSourceName | null;
+    updatedAt: string | null;
+    /** Non-secret fields only. */
+    value?: unknown;
+}
+/** A slot whose provider declares settings, with its fields. */
+interface SettingsSlotView {
+    slot: string;
+    provider: string;
+    fields: SettingFieldView[];
+}
+interface SettingsListing {
+    slots: SettingsSlotView[];
+}
+/**
+ * What a `PUT` or `DELETE` of a field answers: the change applies at the next start. `source` is where the field
+ * comes from afterwards: a `DELETE` of a row the config or environment shadows leaves that source.
+ */
+interface SettingWriteResult {
+    slot: string;
+    path: string;
+    state: 'unset' | 'set';
+    source: SettingSourceName | null;
+    restartRequired: true;
+}
+
 interface ProductSnapshot extends Product {
     variants: Variant[];
     categoryIds: string[];
@@ -575,6 +762,13 @@ interface OrderStatusChangedV1Payload {
 interface OrderConfirmationResendRequestedV1Payload {
     orderId: string;
 }
+/** An imported order taken back out. It carries what the order's documents are keyed by, as its row is gone. */
+interface OrderDeletedV1Payload {
+    orderId: string;
+    orderNumber: string;
+    customerId: string | null;
+    createdAt: string;
+}
 interface InventoryChangedV1Payload {
     variantId: string;
     previousQty: number;
@@ -615,6 +809,8 @@ interface CustomerCreatedV1Payload {
     customerId: string;
     email: string;
     customer?: CustomerSnapshot;
+    /** `'import'` for a customer an import brought over, who is not welcomed; absent for one who registered. */
+    origin?: 'import';
 }
 interface CustomerUpdatedV1Payload {
     customerId: string;
@@ -683,6 +879,7 @@ interface AlertRequestedV1Payload {
     variantId: string;
     productId: string;
 }
+type AlertRepeatedV1Payload = AlertRequestedV1Payload;
 interface AlertConfirmedV1Payload {
     subscriptionId: string;
 }
@@ -698,6 +895,45 @@ interface AlertSentV1Payload {
      */
     triggerEventId: string;
 }
+interface AlertConfirmationSentV1Payload {
+    subscriptionId: string;
+    kind: AlertKind;
+    /** The alert.requested.v1 the confirmation answered. */
+    requestEventId: string;
+}
+interface ReviewSubmittedV1Payload {
+    reviewId: string;
+    productId: string;
+    customerId: string;
+    /** The reviewer's paid order holding the product, which makes the review verified; null when there is none. */
+    orderId: string | null;
+    rating: number;
+}
+interface ProposalCreatedV1Payload {
+    proposalId: string;
+    tool: string;
+    command: string;
+    proposerId: string | null;
+    agentName: string;
+}
+interface ProposalApprovedV1Payload extends ProposalCreatedV1Payload {
+    decidedBy: ProposalDecider;
+}
+interface ProposalRejectedV1Payload extends ProposalApprovedV1Payload {
+    reason: string | null;
+}
+interface ProposalAppliedV1Payload extends ProposalCreatedV1Payload {
+    outcome: {
+        status: number;
+    };
+}
+interface ProposalFailedV1Payload extends ProposalCreatedV1Payload {
+    outcome: {
+        status: number;
+        code?: string;
+        message?: string;
+    };
+}
 interface AdapterErrorV1Payload {
     adapterType: string;
     adapterName: string;
@@ -711,7 +947,7 @@ interface AdapterErrorV1Payload {
 interface SettingsChangedV1Payload {
     slot: string;
     path: string;
-    source: 'settings' | null;
+    source: SettingSourceName | null;
 }
 
 interface NymbalEventMap {
@@ -736,6 +972,7 @@ interface NymbalEventMap {
     [EVT_ORDER_PARTIALLY_REFUNDED]: OrderPartiallyRefundedV1Payload;
     [EVT_ORDER_STATUS_CHANGED]: OrderStatusChangedV1Payload;
     [EVT_ORDER_CONFIRMATION_RESEND_REQUESTED]: OrderConfirmationResendRequestedV1Payload;
+    [EVT_ORDER_DELETED]: OrderDeletedV1Payload;
     [EVT_INVENTORY_CHANGED]: InventoryChangedV1Payload;
     [EVT_INVENTORY_RESERVED]: InventoryReservedV1Payload;
     [EVT_INVENTORY_RELEASED]: InventoryReleasedV1Payload;
@@ -756,9 +993,17 @@ interface NymbalEventMap {
     [EVT_PAYMENT_FAILED]: PaymentFailedV1Payload;
     [EVT_PAYMENT_REFUNDED]: PaymentRefundedV1Payload;
     [EVT_ALERT_REQUESTED]: AlertRequestedV1Payload;
+    [EVT_ALERT_REPEATED]: AlertRepeatedV1Payload;
     [EVT_ALERT_CONFIRMED]: AlertConfirmedV1Payload;
     [EVT_ALERT_UNSUBSCRIBED]: AlertUnsubscribedV1Payload;
     [EVT_ALERT_SENT]: AlertSentV1Payload;
+    [EVT_ALERT_CONFIRMATION_SENT]: AlertConfirmationSentV1Payload;
+    [EVT_REVIEW_SUBMITTED]: ReviewSubmittedV1Payload;
+    [EVT_PROPOSAL_CREATED]: ProposalCreatedV1Payload;
+    [EVT_PROPOSAL_APPROVED]: ProposalApprovedV1Payload;
+    [EVT_PROPOSAL_REJECTED]: ProposalRejectedV1Payload;
+    [EVT_PROPOSAL_APPLIED]: ProposalAppliedV1Payload;
+    [EVT_PROPOSAL_FAILED]: ProposalFailedV1Payload;
     [EVT_ADAPTER_ERROR]: AdapterErrorV1Payload;
     [EVT_SETTINGS_CHANGED]: SettingsChangedV1Payload;
 }
@@ -819,6 +1064,10 @@ interface RequestContext<TBody = unknown, TQuery = Record<string, string | strin
     correlationId: string;
     logger: Logger;
     ip: string;
+    /** The agent a tool call is made for. Only the tool invoker sets it; no HTTP adapter does, so no header can claim it. */
+    agent?: {
+        name: string;
+    };
 }
 interface ResponseCookie {
     name: string;
@@ -863,6 +1112,60 @@ interface HttpAdapter {
     start(port: number, host?: string): Promise<void>;
     stop(): Promise<void>;
 }
+/** A JSON Schema whose root is an object, as an MCP tool's `inputSchema` must be. */
+interface JsonSchemaObject {
+    type: 'object';
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [keyword: string]: unknown;
+}
+/** Who a tool runs for: the verified bearer's user (none for an anonymous agent) and the agent's client info. */
+interface Caller {
+    auth?: RequestAuth;
+    agent: {
+        name: string;
+        version?: string;
+    };
+    /** The address the agent's request came from, for the route's rate rule. */
+    ip?: string;
+}
+/**
+ * One route of the API as an agent tool. `scope` is the least caller the route's gate admits; `kind` is `read` for a
+ * GET, `session` for a write that changes nothing audited (the cart), `command` for an audited command.
+ */
+interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    scope: 'public' | 'customer' | 'admin';
+    kind: 'read' | 'session' | 'command';
+    route: {
+        method: HttpMethod;
+        path: string;
+        command: string | null | undefined;
+    };
+}
+interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** What a caller of the tool surface may ask of one call beside its arguments. */
+interface ToolCallOptions {
+    /** The correlation id the call's request, its proposal and its audit entries carry; a fresh one when absent. */
+    correlationId?: string;
+    /** Keep a command as a pending proposal whatever the policy says (`agents.autoApprove`, `agents.mcp.writes`). */
+    proposeWrites?: boolean;
+}
+/** The tools a store serves to agents; the transports (HTTP, stdio) bind it. */
+interface ToolSurface {
+    list(caller: Caller): ToolDefinition[];
+    call(name: string, args: unknown, caller: Caller, options?: ToolCallOptions): Promise<ToolResult>;
+}
 
 type HealthStatus = 'healthy' | 'degraded' | 'down';
 interface HealthReport {
@@ -919,8 +1222,9 @@ type CommerceSlot = 'payments' | 'email' | 'reviews' | 'search' | 'analytics' |
 type Slot = CommerceSlot | 'documentStore' | 'eventBus' | 'media' | 'security';
 /**
  * What the kernel hands an adapter package's `createAdapter`. A package that serves more than one slot switches on
- * `slot`; `config` is a commerce slot's `config` block from nymbal.config.ts, a primitive's connection block, or for
- * `security` the block named after the adapter (`security.cloudflare`).
+ * `slot`; `config` is a commerce slot's `config` block from nymbal.config.ts, a primitive's connection block (or a
+ * third-party primitive's `config`), or for `security` the block named after the adapter (`security.cloudflare`) or a
+ * third-party adapter's `security.config`.
  */
 interface AdapterContext {
     slot: Slot;
@@ -946,11 +1250,25 @@ interface AdapterSetting {
      */
     optional?: boolean;
 }
-/** What a provider package exports: `createAdapter`, and the fields it lets Settings fill. */
+/**
+ * What a provider package exports: `createAdapter`, the slot and provider it serves (checked when it is loaded), and
+ * the fields it lets Settings fill.
+ */
 interface ProviderPackageModule {
     createAdapter(ctx: AdapterContext): unknown;
+    slot: Slot;
+    provider: string;
     settings?: readonly AdapterSetting[];
 }
+/**
+ * How `nymbal.config.ts` names an infrastructure slot's adapter (`documentStore`, `eventBus`, `media`): the provider,
+ * the npm package it comes from when not `@nymbalhq/<slot>-<provider>`, and a third-party adapter's `ctx.config`.
+ */
+interface InfrastructureBlock {
+    provider: string;
+    package?: string;
+    config?: Record<string, unknown>;
+}
 
 interface PutOptions {
     ttl?: number;
@@ -1098,6 +1416,67 @@ interface MediaStorage {
     healthCheck?(): Promise<HealthReport>;
 }
 
+/** The origins a surface builds its absolute URLs from: never the request's `Host`. */
+interface AgentSurfaceUrls {
+    /** The API's origin: the profile, the MCP endpoint and the handoff link live there. */
+    api: string;
+    /** The storefront's origin, when one is known; product and category links are made on it. */
+    storefront: string | undefined;
+}
+/** What an agent can do through a surface; part of the operator's view of it. */
+interface AgentSurfaceCapabilities {
+    search: boolean;
+    lookup: boolean;
+    /** `handoff`: the agent opens a checkout and the buyer pays on the store's page; `agentic`: the agent pays. */
+    checkout: 'handoff' | 'agentic' | 'none';
+}
+/** What a surface's REST route is handed: the request as its transport received it. */
+interface AgentRouteRequest {
+    params: Record<string, string>;
+    query: Record<string, string | string[] | undefined>;
+    /** Lower-cased names. */
+    headers: Record<string, string | string[] | undefined>;
+    body: unknown;
+    ip: string;
+    requestId: string;
+}
+/** A REST route of an agent surface, served server to server under the surface's own credential (no CSRF). */
+interface AgentRoute {
+    method: 'GET' | 'POST';
+    path: string;
+    handle(request: AgentRouteRequest): Promise<ResponseEnvelope>;
+}
+/**
+ * One agent protocol a store serves (UCP, ACP): a discovery document, a tool endpoint and REST routes, each optional.
+ */
+interface AgentSurfaceAdapter {
+    name: string;
+    capabilities: AgentSurfaceCapabilities;
+    wellKnown?: {
+        path: string;
+        document(urls: AgentSurfaceUrls): Record<string, unknown>;
+    };
+    endpoint?: {
+        path: string;
+        tools: ToolSurface;
+    };
+    routes?: AgentRoute[];
+}
+/** The agent surfaces a store serves and the crawl files beside them; built by `attachHttp`. */
+interface AgentSurfaces {
+    surfaces: AgentSurfaceAdapter[];
+    /** Where the surfaces' tools take their origins from; the mount that serves them sets it. */
+    useUrls(urls: () => AgentSurfaceUrls): void;
+    /** `robots.txt`, or null when it is off. */
+    robots(urls: AgentSurfaceUrls): string | null;
+    /** `llms.txt`, or null when it is off. */
+    llms(urls: AgentSurfaceUrls): Promise<string | null>;
+    /** One page of the product feed, or null when it is off. */
+    feed(urls: AgentSurfaceUrls, cursor?: string): Promise<Record<string, unknown> | null>;
+    /** Whether `token` names a live cart a browser may be handed. */
+    handoff(token: string): Promise<boolean>;
+}
+
 type RateLimitAction = 'block' | 'challenge' | 'throttle';
 interface RateLimitRule {
     requests: number;
@@ -1140,11 +1519,58 @@ interface SecurityState {
     rulesApplied: string[];
     lastValidatedAt: string;
 }
+/**
+ * What a security adapter tells the HTTP layer about the network in front of the store. Each value counts only when the
+ * store sets neither its variable nor its config key.
+ */
+interface SecurityNetwork {
+    /** The proxies whose `X-Forwarded-For` (and client-address header) the API believes: presets, addresses or CIDRs. */
+    trustedProxies?: string[];
+    /** One header a listed proxy sets to the client's address, such as `CF-Connecting-IP`. */
+    clientIpHeader?: string;
+    /** Whether `clientIpHeader` may be honoured only on a request the origin lock admitted. */
+    clientIpRequiresLock?: boolean;
+}
+/** Where a resolved network value came from: the variable, the config key, the adapter's name, or `default`. */
+interface NetworkSource {
+    kind: 'env' | 'config' | 'adapter' | 'default';
+    name: string;
+}
+/** The network block the HTTP server is built from, resolved once at boot. */
+interface ResolvedNetwork {
+    trustedProxies: string[];
+    trustedProxiesSource: NetworkSource;
+    clientIpHeader?: string;
+    clientIpHeaderSource?: NetworkSource;
+    clientIpRequiresLock: boolean;
+    /** Present when `NYMBAL_ORIGIN_SECRET` is set: the header the CDN proves itself in, and the secrets it may send. */
+    originLock?: ResolvedOriginLock;
+}
+/** The origin lock, resolved once at boot: every entry is accepted, so a secret can be rotated without downtime. */
+interface ResolvedOriginLock {
+    header: string;
+    secrets: readonly string[];
+}
+/**
+ * Whether the CDN sends the origin secret: `missing` when it has no enabled rule; `present` with the header the rule
+ * sets and `entry`, the 0-based index of the secret it sends, or null when it sends none of them.
+ */
+type OriginLockRule = {
+    state: 'missing';
+} | {
+    state: 'present';
+    header: string;
+    entry: number | null;
+};
 interface SecurityAdapter extends AdapterBase {
     applyMiddleware(app: HttpAdapter, config: SecurityConfigLike): Promise<void>;
     validate(config: SecurityConfigLike): Promise<ValidationResult>;
     drift?(config: SecurityConfigLike): Promise<DriftReport>;
     inspect?(): Promise<SecurityState>;
+    /** The adapter's network settings, offered at boot; synchronous and without I/O. */
+    network?(): SecurityNetwork;
+    /** Whether the CDN in front sends one of the lock's secrets, read from the CDN itself. */
+    originLockRule?(lock: ResolvedOriginLock): Promise<OriginLockRule>;
 }
 /** The response headers every security adapter sets in process, from the config's `headers` block. */
 declare function buildSecurityHeaders(security: SecurityConfigLike): Record<string, string>;
@@ -1228,10 +1654,21 @@ interface ReviewsResult {
     items: Review[];
     nextCursor: string | null;
 }
+/** What a reviews adapter can do; `capabilities()` of a reviews adapter answers a subset. */
+type ReviewsCapability = 'submit' | 'moderate' | 'aggregate' | 'invite' | 'widget';
+/**
+ * The kernel resolves `customerId`, `author` and `orderId` (the reviewer's paid order holding the product) before the
+ * adapter sees a submission; an adapter never looks up customers or orders. An adapter without `submit` refuses it
+ * with `ReviewRefusedError('submit_unsupported')`.
+ */
 interface ReviewSubmission {
     productId: string;
     customerId: string | null;
     orderId: string | null;
+    author: {
+        name: string;
+        email: string;
+    } | null;
     rating: number;
     title: string;
     body: string;
@@ -1302,39 +1739,68 @@ interface AnalyticsAdapter extends CommerceAdapter {
     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;
+/** What a shipping adapter does; each word is declared exactly when the method it names is present. */
+declare const SHIPPING_CAPABILITIES: readonly ["rates", "labels", "tracking"];
+/** `rates` has `rate`, `labels` has `createLabel` (and needs `rates`), `tracking` has `startTracking` and `receiveWebhook`. */
+type ShippingCapability = (typeof SHIPPING_CAPABILITIES)[number];
+/** A parcel has all three dimensions or none. Grams and millimetres, each positive. */
+type Parcel = {
     weightGrams: number;
-    currency: string;
+    lengthMm?: never;
+    widthMm?: never;
+    heightMm?: never;
+} | {
+    weightGrams: number;
+    lengthMm: number;
+    widthMm: number;
+    heightMm: number;
+};
+interface ShippingRateParams {
+    from: Address;
+    to: Address;
+    parcel: Parcel;
 }
 interface ShippingRate {
+    /** Opaque to the kernel: handed back unchanged as `ShippingLabelParams.rateId`. */
+    id: string;
     carrier: string;
     service: string;
     amountMinor: number;
     currency: string;
-    estimatedDays: number;
+    estimatedDays: number | null;
 }
 interface ShippingLabelParams {
-    orderId: string;
-    carrier: string;
-    service: string;
+    rateId: string;
 }
 interface ShippingLabel {
     labelUrl: string;
     trackingNumber: string;
     carrier: string;
+    service: string;
+    amountMinor: number;
+    currency: string;
 }
-interface ShippingTracking {
-    status: string;
-    lastUpdateAt: string;
+interface StartTrackingParams {
+    trackingNumber: string;
+    /** As the merchant typed it; null leaves the carrier to the provider. */
+    carrier: string | null;
 }
+/**
+ * `tracking`: the provider holds the number, now or from before. `refused`: it never will (an invalid number, an
+ * unknown carrier, a refused key). An outage rejects instead, so the caller may try again.
+ */
+type StartTrackingResult = {
+    status: 'tracking';
+} | {
+    status: 'refused';
+    reason: string;
+};
 interface ShippingAdapter extends CommerceAdapter {
     readonly kind: 'shipping';
-    rate(params: ShippingRateParams): Promise<ShippingRate[]>;
-    createLabel(params: ShippingLabelParams): Promise<ShippingLabel>;
-    track(trackingNumber: string): Promise<ShippingTracking>;
+    capabilities(): readonly ShippingCapability[];
+    rate?(params: ShippingRateParams): Promise<ShippingRate[]>;
+    createLabel?(params: ShippingLabelParams): Promise<ShippingLabel>;
+    startTracking?(params: StartTrackingParams): Promise<StartTrackingResult>;
 }
 interface TaxLine {
     amountMinor: number;
@@ -1356,12 +1822,89 @@ interface TaxAdapter extends CommerceAdapter {
     readonly kind: 'tax';
     calculate(params: TaxCalculationParams): Promise<TaxCalculationResult>;
 }
+/** A tool the model may call. Its name matches `^[A-Za-z0-9_-]{1,64}$` and is unique among the tools of one request. */
+interface ChatTool {
+    name: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+}
+/** A call the model asked for, its arguments a JSON object. */
+interface ChatToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+/**
+ * One turn of a conversation. The first turn is the user's. An assistant turn's `content` may be empty only when it
+ * has calls; each call is answered by one `tool` turn before the next user or assistant turn.
+ */
+type ChatMessage = {
+    role: 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string;
+    toolCalls?: readonly ChatToolCall[];
+} | {
+    role: 'tool';
+    toolCallId: string;
+    content: string;
+    isError?: boolean;
+};
+interface ChatOptions {
+    /** Instructions for the whole conversation, sent in the provider's own system field. */
+    system?: string;
+    /** The most tokens the answer may take; 1024 when omitted. */
+    maxTokens?: number;
+    tools?: readonly ChatTool[];
+    /** Aborting it closes the request and rejects `adapter.cancelled`. */
+    signal?: AbortSignal;
+}
+/** Why the answer ended: complete, cut at `maxTokens`, waiting on its tool calls, or anything else reported. */
+type ChatStopReason = 'end' | 'max_tokens' | 'tool_use' | 'other';
+interface ChatResult {
+    /** '' when the answer is calls only. */
+    text: string;
+    stopReason: ChatStopReason;
+    /** 0 where the provider reports none. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** The model as the provider reports it. */
+    model: string;
+    /** The calls the model asked for, in its order; [] when none. */
+    toolCalls: ChatToolCall[];
+}
+/** What `chatStream` yields: text as it arrives, each call once its arguments are complete, and one `done` last. */
+type ChatStreamEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'tool_call';
+    call: ChatToolCall;
+} | {
+    type: 'done';
+    result: ChatResult;
+};
 interface AiAdapter extends CommerceAdapter {
     readonly kind: 'ai';
     embed(texts: string[]): Promise<number[][]>;
+    /** The text `chat` answers to a single user turn. */
     complete(prompt: string, opts?: {
         maxTokens?: number;
     }): Promise<string>;
+    /**
+     * One request to the provider. Refused input, a provider failure and a timeout reject with an `AdapterError` whose
+     * context is `{ provider, status? }` and which never carries the key.
+     */
+    chat(messages: readonly ChatMessage[], opts?: ChatOptions): Promise<ChatResult>;
+    /**
+     * `chat` as it is generated: the text deltas concatenate to the `done` result's text and the `tool_call` events are
+     * its calls in order. A stream broken after it started rejects `adapter.unavailable`; the whole stream is bounded as
+     * one `chat`.
+     */
+    chatStream?(messages: readonly ChatMessage[], opts?: ChatOptions): AsyncIterable<ChatStreamEvent>;
 }
 /** The adapter interface each commerce slot takes: what a project injects for a slot whose provider is `custom`. */
 interface CommerceSlotAdapters {
@@ -1387,6 +1930,58 @@ interface WebhookDeliveryProblem {
  */
 declare function webhookDeliveryProblem(providerName: string, producesEvents: readonly string[], delivery: WebhookDelivery): WebhookDeliveryProblem | null;
 
+/**
+ * `<providerName>.bounced.v1`: a message to `recipient` bounced. `hard` is the provider's permanent failure, `soft`
+ * its transient one; a classification the adapter cannot map is `soft`, so a doubtful bounce never suppresses.
+ */
+interface EmailBouncedV1Payload {
+    recipient: string;
+    bounce: 'hard' | 'soft';
+    /** The `EmailSendResult.messageId` the bounce answers, when the provider gives one. */
+    messageId: string | null;
+    /** ISO 8601. */
+    occurredAt: string;
+}
+/** `<providerName>.complained.v1`: `recipient` marked a message as spam. */
+interface EmailComplainedV1Payload {
+    recipient: string;
+    messageId: string | null;
+    /** ISO 8601. */
+    occurredAt: string;
+}
+type EmailFeedbackKind = 'bounced' | 'complained';
+/** The event type an email adapter publishes a bounce or a complaint under. */
+declare function emailFeedbackType(providerName: string, what: EmailFeedbackKind): string;
+/**
+ * The first bounce or complaint in a verified delivery from the email adapter `providerName` that the kernel cannot
+ * act on, or null when there is none. The route refuses such a delivery whole, before claiming it, so the provider's
+ * retry after the adapter is fixed is still received; the email feedback contract suite certifies the same rule.
+ */
+declare function emailFeedbackProblem(providerName: string, delivery: WebhookDelivery): WebhookDeliveryProblem | null;
+
+/** The statuses a shipping adapter maps its carrier's onto; one it cannot map is `unknown`. */
+declare const SHIPPING_TRACKING_STATUSES: readonly ["pre_transit", "in_transit", "out_for_delivery", "delivered", "exception", "returned", "unknown"];
+type ShippingTrackingStatus = (typeof SHIPPING_TRACKING_STATUSES)[number];
+/** `<providerName>.tracking.v1`: the carrier reported `status` for the parcel `trackingNumber`. */
+interface ShippingTrackingV1Payload {
+    trackingNumber: string;
+    /** The carrier's code as the adapter's provider gives it, which need not match the merchant's own. */
+    carrier: string | null;
+    status: ShippingTrackingStatus;
+    /** ISO 8601. */
+    occurredAt: string;
+}
+/** The event type a shipping adapter publishes a tracking update under. */
+declare function shippingTrackingType(providerName: string): string;
+/** A tracking number as stored and looked up: no whitespace, upper case, so a carrier's spelling finds the merchant's. */
+declare function normaliseTrackingNumber(value: string): string;
+/**
+ * The first tracking update in a verified delivery from the shipping adapter `providerName` that the kernel cannot act
+ * on, or null when there is none. The route refuses such a delivery whole, before claiming it, so the provider's retry
+ * after the adapter is fixed is still received; the shipping tracking contract suite certifies the same rule.
+ */
+declare function shippingTrackingProblem(providerName: string, delivery: WebhookDelivery): WebhookDeliveryProblem | null;
+
 interface RenderedEmail {
     subject: string;
     text: string;
@@ -1415,6 +2010,14 @@ interface StoreCapabilities {
     email: {
         delivers: boolean;
     };
+    /** What the reviews adapter can do: without `submit` the store takes no review on its own site. */
+    reviews: {
+        capabilities: string[];
+    };
+    /** What the shipping adapter can do (`rates`, `labels`, `tracking`); none on a store that only ships by hand. */
+    shipping: {
+        capabilities: string[];
+    };
 }
 
 /**
@@ -1435,7 +2038,7 @@ interface Recipe {
     summary: string;
     /** npm packages to install, SDKs included; empty when the service is built in. */
     install: string[];
-    /** Config paths and the values they take, e.g. `infrastructure.documentStore` = `'redis'`. */
+    /** Config paths and the values they take, e.g. `infrastructure.documentStore.provider` = `'redis'`. */
     set: Array<{
         path: string;
         value: RecipeValue;
@@ -1456,37 +2059,6 @@ type StockLevel = 'out' | 'low' | 'in';
 declare function stockLevel(stock: number): StockLevel;
 declare const STOCK_LABELS: Record<StockLevel, string>;
 
-/** Where a Settings field's value comes from: the config block, its declared env, a saved value, or nowhere. */
-type SettingSourceName = 'config' | 'env' | 'settings';
-/** One declared field as `GET /api/admin/settings` lists it; a secret never carries its value. */
-interface SettingFieldView {
-    path: string;
-    label: string;
-    secret: boolean;
-    state: 'unset' | 'set';
-    source: SettingSourceName | null;
-    updatedAt: string | null;
-    /** Non-secret fields only. */
-    value?: unknown;
-}
-/** A slot whose provider declares settings, with its fields. */
-interface SettingsSlotView {
-    slot: string;
-    provider: string;
-    fields: SettingFieldView[];
-}
-interface SettingsListing {
-    slots: SettingsSlotView[];
-}
-/** What a `PUT` or `DELETE` of a field answers: the change applies at the next start. */
-interface SettingWriteResult {
-    slot: string;
-    path: string;
-    state: 'unset' | 'set';
-    source: 'settings' | null;
-    restartRequired: true;
-}
-
 /** Who a command ran for. A guest is `guest:anonymous`: a cart's token is a bearer credential and is never an id. */
 interface AuditActor {
     kind: 'admin' | 'customer' | 'guest' | 'system' | 'import';
@@ -1555,5 +2127,47 @@ interface AsOfRead<T = Record<string, unknown>> {
     record: T;
 }
 
-export { AdapterError, AuthError, CORRELATION_ID_HEADER, CheckoutError, ConfigError, DEFAULT_PRODUCT_SORT, DEFAULT_QUERY_LIMIT, EVT_ADAPTER_ERROR, EVT_ALERT_CONFIRMED, EVT_ALERT_REQUESTED, EVT_ALERT_SENT, EVT_ALERT_UNSUBSCRIBED, 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_CONFIRMATION_RESEND_REQUESTED, EVT_ORDER_DELIVERED, EVT_ORDER_FULFILLED, EVT_ORDER_PAID, EVT_ORDER_PARTIALLY_REFUNDED, EVT_ORDER_PLACED, EVT_ORDER_REFUNDED, EVT_ORDER_SHIPPED, EVT_ORDER_STATUS_CHANGED, EVT_PAYMENT_CAPTURED, EVT_PAYMENT_FAILED, EVT_PAYMENT_INTENT_CREATED, EVT_PAYMENT_REFUNDED, EVT_PRODUCT_CREATED, EVT_PRODUCT_DELETED, EVT_PRODUCT_PUBLISHED, EVT_PRODUCT_RESTOCKED, EVT_PRODUCT_UNPUBLISHED, EVT_PRODUCT_UPDATED, EVT_PRODUCT_VARIANT_PRICE_CHANGED, EVT_PRODUCT_VIEWED, EVT_SETTINGS_CHANGED, EVT_VISITOR_MERGED, HEALTH_CHECK_TIMEOUT_MS, HttpError, IDEMPOTENCY_KEY_HEADER, IDEMPOTENT_REPLAYED_HEADER, NotFoundError, NymbalError, ORDER_KEY_HEADER, ORDER_STATUS_TRANSITIONS, ORDER_TIMELINE_KINDS, OrderConflictError, PRODUCT_SORT_KEYS, PRODUCT_SORT_LABELS, PaymentError, SECRET_MIN_LENGTH, STANDARD_EVENT_TYPES, STOCK_LABELS, StatusTransitionError, ValidationError, add, allocate, assertMinorUnits, assertOrderTransition, boundedHealthCheck, buildSecurityHeaders, canTransitionOrder, compareDocumentValues, connectionSecrets, displayUrl, documentValueAt, errorText, handlerFailedError, isValidCorrelationId, isValidIdempotencyKey, matchesSortKey, money, mulBy, paymentState, queryDocuments, refundableMinor, renderEmailTemplate, stockLevel, sub, sumMoney, webhookDeliveryProblem };
-export type { AdapterBase, AdapterContext, AdapterErrorV1Payload, AdapterSetting, Address, AggregateRating, AiAdapter, AlertConfirmedV1Payload, AlertKind, AlertRequestedV1Payload, AlertSentV1Payload, AlertStatus, AlertUnsubscribedV1Payload, AnalyticsAdapter, AsOfRead, AuditActor, AuditEntry, AuditOutcome, AuditSubject, BoundedHealthCheckOptions, CaptureMethod, Cart, CartAbandonedV1Payload, CartConvertedV1Payload, CartCreatedV1Payload, CartItem, CartItemAddedV1Payload, CartItemRemovedV1Payload, CartUpdatedV1Payload, Category, CategoryCreatedV1Payload, CategoryDeletedV1Payload, CategoryUpdatedV1Payload, CheckoutPayment, CommerceAdapter, CommerceSlot, CommerceSlotAdapters, Customer, CustomerAddress, CustomerCreatedV1Payload, CustomerDeletedV1Payload, CustomerProfile, CustomerSnapshot, CustomerUpdatedV1Payload, DocumentStoreAdapter, DriftReport, EmailAdapter, EmailSendResult, ErrorContext, EventBusAdapter, EventHandler, EventMetadata, Facet, FacetParams, HandlerFailure, HealthReport, HealthStatus, HistoryChange, HistoryEntry, HistoryKind, HistoryPage, HttpAdapter, HttpMethod, IndexResult, InventoryChangedV1Payload, InventoryLowStockV1Payload, InventoryOutOfStockV1Payload, InventoryReleasedV1Payload, InventoryReservation, InventoryReservedV1Payload, Logger, MediaStorage, MiddlewareHandler, Money, NymbalEnvironment, NymbalEvent, NymbalEventMap, NymbalEventType, Order, OrderCancelledV1Payload, OrderConfirmationResendRequestedV1Payload, OrderDeliveredV1Payload, OrderFulfilledV1Payload, OrderHistoryEntry, OrderLineItem, OrderPaidV1Payload, OrderPartiallyRefundedV1Payload, OrderPayment, OrderPlacedV1Payload, OrderRefund, OrderRefundStatus, OrderRefundedV1Payload, OrderShippedV1Payload, OrderStatus, OrderStatusChangedV1Payload, OrderTimelineEntry, OrderTimelineKind, PaginationParams, PayloadOf, PaymentCapture, PaymentCapturedV1Payload, PaymentClient, PaymentFailedV1Payload, PaymentIntent, PaymentIntentCreatedV1Payload, PaymentIntentParams, PaymentRefundedV1Payload, PaymentState, PaymentStatus, PaymentsAdapter, Product, ProductCreatedV1Payload, ProductDeletedV1Payload, ProductMedia, ProductPublishedV1Payload, ProductRestockedV1Payload, ProductSnapshot, ProductSortKey, ProductStatus, ProductType, ProductUnpublishedV1Payload, ProductUpdatedV1Payload, ProductVariantPriceChangedV1Payload, ProductViewedV1Payload, ProviderPackageModule, PutOptions, QueryParams, QueryResult, RateLimitAction, RateLimitDecision, RateLimitRule, RecentViewer, Recipe, RecipeValue, Refund, RefundOptions, RenderedEmail, RequestAuth, RequestContext, ResponseCookie, ResponseEnvelope, RetryPolicy, Review, ReviewModerationStatus, ReviewResult, ReviewSubmission, ReviewsAdapter, ReviewsResult, Role, RouteHandler, RouteOptions, SearchAdapter, SearchDocument, SearchParams, SearchResult, SecurityAdapter, SecurityConfigLike, SecurityState, SettingFieldView, SettingSourceName, SettingWriteResult, SettingsChangedV1Payload, SettingsListing, SettingsSlotView, ShippingAdapter, ShippingLabel, ShippingLabelParams, ShippingRate, ShippingRateParams, ShippingTracking, ShopperOrder, Slot, SortKeyCondition, SseEvent, StockAdjustment, StockAdjustmentReason, StockLevel, StockStatus, StoreCapabilities, StreamContext, StreamHandler, Subscription, SubscriptionConfig, TaxAdapter, TaxCalculationParams, TaxCalculationResult, TaxLine, TransactionalEmail, ValidationResult, Variant, VariantDimensions, VariantOption, VariantStatus, VisitorMergedV1Payload, WebhookDelivery, WebhookDeliveryProblem, WebhookEventDraft, WebhookHeaders, WebhookResult };
+/**
+ * What the admin's assistant stream sends, frame by frame: the answer's text as it arrives, one `tool` frame per tool
+ * the model called (or one `proposal` frame for a write kept for a person to approve), then `done` or `error`.
+ */
+type AssistantFrame = {
+    event: 'text';
+    data: {
+        delta: string;
+    };
+} | {
+    event: 'tool';
+    data: {
+        name: string;
+        title: string;
+        ok: boolean;
+        code?: string;
+        applied?: true;
+    };
+} | {
+    event: 'proposal';
+    data: ProposalView;
+} | {
+    event: 'done';
+    data: {
+        text: string;
+        steps: number;
+        proposals: string[];
+    };
+} | {
+    event: 'error';
+    data: {
+        code: string;
+        message: string;
+    };
+};
+/** `POST /api/admin/assistant/turns`: the turn's id and the one-time ticket that opens its stream. */
+interface AssistantTurnIssued {
+    turnId: string;
+    ticket: string;
+    expiresIn: number;
+}
+
+export { AdapterError, AuthError, CART_LINE_MAX_QTY, CORRELATION_ID_HEADER, CartLimitError, CheckoutError, ConfigError, DEFAULT_PRODUCT_SORT, DEFAULT_QUERY_LIMIT, EVT_ADAPTER_ERROR, EVT_ALERT_CONFIRMATION_SENT, EVT_ALERT_CONFIRMED, EVT_ALERT_REPEATED, EVT_ALERT_REQUESTED, EVT_ALERT_SENT, EVT_ALERT_UNSUBSCRIBED, 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_CONFIRMATION_RESEND_REQUESTED, EVT_ORDER_DELETED, EVT_ORDER_DELIVERED, EVT_ORDER_FULFILLED, EVT_ORDER_PAID, EVT_ORDER_PARTIALLY_REFUNDED, EVT_ORDER_PLACED, EVT_ORDER_REFUNDED, EVT_ORDER_SHIPPED, EVT_ORDER_STATUS_CHANGED, EVT_PAYMENT_CAPTURED, EVT_PAYMENT_FAILED, EVT_PAYMENT_INTENT_CREATED, EVT_PAYMENT_REFUNDED, EVT_PRODUCT_CREATED, EVT_PRODUCT_DELETED, EVT_PRODUCT_PUBLISHED, EVT_PRODUCT_RESTOCKED, EVT_PRODUCT_UNPUBLISHED, EVT_PRODUCT_UPDATED, EVT_PRODUCT_VARIANT_PRICE_CHANGED, EVT_PRODUCT_VIEWED, EVT_PROPOSAL_APPLIED, EVT_PROPOSAL_APPROVED, EVT_PROPOSAL_CREATED, EVT_PROPOSAL_FAILED, EVT_PROPOSAL_REJECTED, EVT_REVIEW_SUBMITTED, EVT_SETTINGS_CHANGED, EVT_VISITOR_MERGED, HEALTH_CHECK_TIMEOUT_MS, HttpError, IDEMPOTENCY_KEY_HEADER, IDEMPOTENT_REPLAYED_HEADER, NotFoundError, NymbalError, ORDER_EMAIL_HEADER, ORDER_KEY_HEADER, ORDER_STATUS_TRANSITIONS, ORDER_TIMELINE_KINDS, OrderConflictError, PREVIEWED_COMMANDS, PRODUCT_SORT_KEYS, PRODUCT_SORT_LABELS, PaymentError, ReviewRefusedError, SECRET_MIN_LENGTH, SHIPPING_CAPABILITIES, SHIPPING_TRACKING_STATUSES, SHOPPER_ATTESTATION_HEADER, STANDARD_EVENT_TYPES, STOCK_LABELS, StatusTransitionError, ValidationError, add, agentSource, allocate, assertMinorUnits, assertOrderTransition, boundedHealthCheck, buildSecurityHeaders, canTransitionOrder, compareDocumentValues, connectionSecrets, displayUrl, documentValueAt, emailFeedbackProblem, emailFeedbackType, errorText, handlerFailedError, isValidCorrelationId, isValidIdempotencyKey, matchesSortKey, money, mulBy, normaliseTrackingNumber, paymentState, queryDocuments, refundableMinor, renderEmailTemplate, shippingTrackingProblem, shippingTrackingType, stockLevel, sub, sumMoney, webhookDeliveryProblem };
+export type { AdapterBase, AdapterContext, AdapterErrorV1Payload, AdapterSetting, Address, AgentRoute, AgentRouteRequest, AgentSurfaceAdapter, AgentSurfaceCapabilities, AgentSurfaceUrls, AgentSurfaces, AggregateRating, AiAdapter, AlertConfirmationSentV1Payload, AlertConfirmedV1Payload, AlertKind, AlertRepeatedV1Payload, AlertRequestedV1Payload, AlertSentV1Payload, AlertStatus, AlertUnsubscribedV1Payload, AnalyticsAdapter, AsOfRead, AssistantFrame, AssistantTurnIssued, AuditActor, AuditEntry, AuditOutcome, AuditSubject, BoundedHealthCheckOptions, Caller, CaptureMethod, Cart, CartAbandonedV1Payload, CartConvertedV1Payload, CartCreatedV1Payload, CartItem, CartItemAddedV1Payload, CartItemRemovedV1Payload, CartSource, CartUpdatedV1Payload, Category, CategoryCreatedV1Payload, CategoryDeletedV1Payload, CategoryUpdatedV1Payload, ChatMessage, ChatOptions, ChatResult, ChatStopReason, ChatStreamEvent, ChatTool, ChatToolCall, CheckoutPayment, CommerceAdapter, CommerceSlot, CommerceSlotAdapters, Customer, CustomerAddress, CustomerCreatedV1Payload, CustomerDeletedV1Payload, CustomerProfile, CustomerSnapshot, CustomerUpdatedV1Payload, DocumentStoreAdapter, DriftReport, EmailAdapter, EmailBouncedV1Payload, EmailComplainedV1Payload, EmailFeedbackKind, EmailSendResult, ErrorContext, EventBusAdapter, EventHandler, EventMetadata, Facet, FacetParams, HandlerFailure, HealthReport, HealthStatus, HistoryChange, HistoryEntry, HistoryKind, HistoryPage, HttpAdapter, HttpMethod, IndexResult, InfrastructureBlock, InventoryChangedV1Payload, InventoryLowStockV1Payload, InventoryOutOfStockV1Payload, InventoryReleasedV1Payload, InventoryReservation, InventoryReservedV1Payload, JsonSchemaObject, Logger, MediaStorage, MiddlewareHandler, Money, NetworkSource, NymbalEnvironment, NymbalEvent, NymbalEventMap, NymbalEventType, Order, OrderCancelledV1Payload, OrderConfirmationResendRequestedV1Payload, OrderDeletedV1Payload, OrderDeliveredV1Payload, OrderFulfilledV1Payload, OrderHistoryEntry, OrderLineItem, OrderPaidV1Payload, OrderPartiallyRefundedV1Payload, OrderPayment, OrderPlacedV1Payload, OrderRefund, OrderRefundStatus, OrderRefundedV1Payload, OrderShippedV1Payload, OrderSource, OrderStatus, OrderStatusChangedV1Payload, OrderTimelineEntry, OrderTimelineKind, OriginLockRule, PaginationParams, Parcel, PayloadOf, PaymentCapture, PaymentCapturedV1Payload, PaymentClient, PaymentFailedV1Payload, PaymentIntent, PaymentIntentCreatedV1Payload, PaymentIntentParams, PaymentRefundedV1Payload, PaymentState, PaymentStatus, PaymentsAdapter, Product, ProductCreatedV1Payload, ProductDeletedV1Payload, ProductMedia, ProductPublishedV1Payload, ProductRating, ProductRestockedV1Payload, ProductSnapshot, ProductSortKey, ProductStatus, ProductType, ProductUnpublishedV1Payload, ProductUpdatedV1Payload, ProductVariantPriceChangedV1Payload, ProductViewedV1Payload, ProposalAppliedV1Payload, ProposalApprovedV1Payload, ProposalChange, ProposalCreatedV1Payload, ProposalDecider, ProposalFailedV1Payload, ProposalPage, ProposalPreview, ProposalRejectedV1Payload, ProposalStatus, ProposalView, ProviderPackageModule, PublicReview, PublicReviewsResult, PutOptions, QueryParams, QueryResult, RateLimitAction, RateLimitDecision, RateLimitRule, RecentViewer, Recipe, RecipeValue, Refund, RefundOptions, RenderedEmail, RequestAuth, RequestContext, ResolvedNetwork, ResolvedOriginLock, ResponseCookie, ResponseEnvelope, RetryPolicy, Review, ReviewModerationStatus, ReviewRefusal, ReviewResult, ReviewSubmission, ReviewSubmittedV1Payload, ReviewsAdapter, ReviewsCapability, ReviewsResult, Role, RouteHandler, RouteOptions, SearchAdapter, SearchDocument, SearchParams, SearchResult, SecurityAdapter, SecurityConfigLike, SecurityNetwork, SecurityState, SettingFieldView, SettingSourceName, SettingWriteResult, SettingsChangedV1Payload, SettingsListing, SettingsSlotView, ShippingAdapter, ShippingCapability, ShippingLabel, ShippingLabelParams, ShippingRate, ShippingRateParams, ShippingTrackingStatus, ShippingTrackingV1Payload, ShopperAddress, ShopperOrder, Slot, SortKeyCondition, SseEvent, StartTrackingParams, StartTrackingResult, StockAdjustment, StockAdjustmentReason, StockLevel, StockStatus, StoreCapabilities, StreamContext, StreamHandler, Subscription, SubscriptionConfig, TaxAdapter, TaxCalculationParams, TaxCalculationResult, TaxLine, ToolCallOptions, ToolDefinition, ToolResult, ToolSurface, TransactionalEmail, ValidationResult, Variant, VariantDimensions, VariantOption, VariantStatus, VisitorMergedV1Payload, WebhookDelivery, WebhookDeliveryProblem, WebhookEventDraft, WebhookHeaders, WebhookResult };