@aglyn/aglyn 1.0.0-beta.231 → 1.0.0-beta.233

package/src/lib/plugin-manager/plugin-channel-orders.d.ts

@@ -0,0 +1,262 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Orders a store took somewhere else (AGL-3638): a marketplace, a social
+ * shop, any outside channel that sells the store's goods and is paid there.
+ *
+ * Such an order must become a REAL order of the store — numbered with the
+ * rest, shown in the same list, shipped from the same dialog, announced to
+ * the same subscribers — and its units must leave the same shelf every other
+ * channel sells from, in the same write, or two channels sell the last unit
+ * twice. The plugin that brings the order in must not write the seller's
+ * orders or products itself, so the seller registers
+ * {@link PluginChannelOrders} and records each order under its own rules: the
+ * order number, the stock decrement and its ledger row, the oversell alert,
+ * the order events.
+ *
+ * ## Once per outside order
+ *
+ * An import is keyed by `channel.id` and `externalOrderId`. The same pair a
+ * second time — a retried run, a page read twice — answers `already` with
+ * the record the first import made, and nothing moves.
+ *
+ * ## The channel was paid, not the store
+ *
+ * The buyer paid the channel, and the channel pays the merchant out. No
+ * money moves through the seller for the order; its refunds and returns
+ * happen on the channel. What the channel charged the merchant for the sale
+ * (`fees`) is RECORDED on the order for the merchant's books and never
+ * charged or collected by anyone here.
+ *
+ * Money is integer minor units (cents for USD) in `currency`. A seller may
+ * refuse an order in a currency its store does not sell in.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-channel-orders`); it is not in the
+ * barrel.
+ */
+/** One line of an outside order. */
+export interface PluginChannelOrderLine {
+    /** The channel's id for the line, which a shipment back to it names. */
+    externalLineId: string;
+    /** The seller SKU the channel sold it under; `null` when it gave none. */
+    sku: string | null;
+    /**
+     * The product and configuration, when the importer already knows them
+     * (it listed them from `core.product-catalog`). Otherwise the seller
+     * matches `sku`.
+     */
+    productId?: string | null;
+    variantId?: string | null;
+    /** The channel's name for the item, kept on the order. */
+    name: string;
+    quantity: number;
+    /** Per unit, before tax. */
+    unitPriceCents: number;
+}
+/** The address the order ships to. */
+export interface PluginChannelOrderAddress {
+    name?: string | null;
+    line1?: string | null;
+    line2?: string | null;
+    city?: string | null;
+    state?: string | null;
+    postalCode?: string | null;
+    /** ISO 3166-1 alpha-2, upper case. */
+    country?: string | null;
+    phone?: string | null;
+}
+/** A channel's charge on a sale, recorded for the merchant and never collected here. */
+export interface PluginChannelOrderFee {
+    label: string;
+    amountCents: number;
+}
+export interface PluginChannelOrder {
+    hostId: string;
+    /** Stable id and display name, as the importer names its channel. */
+    channel: {
+        id: string;
+        label: string;
+    };
+    externalOrderId: string;
+    /** What the merchant sees on the channel. */
+    externalRef: string;
+    placedAtMs: number;
+    /** ISO 4217. */
+    currency: string;
+    lines: PluginChannelOrderLine[];
+    shippingCents: number;
+    /** Tax the channel collected; the channel, not the store, remits it. */
+    taxCents: number;
+    discountCents: number;
+    /** What the buyer paid the channel in all. */
+    totalCents: number;
+    /** The channel's charges on the sale; `null` while the channel has not said. */
+    fees: PluginChannelOrderFee[] | null;
+    customerName: string | null;
+    shippingAddress: PluginChannelOrderAddress | null;
+    /** Placed in the channel's sandbox: recorded, but never counted as revenue. */
+    testMode: boolean;
+    /**
+     * How the goods leave the store (AGL-3644): `ship`, the default, by a
+     * carrier to `shippingAddress`; `courier`, handed over the counter to the
+     * channel's own courier (a delivery app), so nothing is shipped from here
+     * and the seller says so to the merchant.
+     */
+    handoff?: 'ship' | 'courier';
+}
+/** A line the store's stock could not cover in full: the channel sold more than the shelf held. */
+export interface PluginChannelOrderShortfall {
+    lineIndex: number;
+    sku: string | null;
+    /** Units sold beyond what the shelf held. */
+    short: number;
+}
+export type PluginChannelOrderOutcome = {
+    outcome: 'created';
+    recordId: string;
+    /** What a person calls it: `#1042`. */
+    displayRef: string;
+    /** Which order line each channel line became. */
+    lines: Array<{
+        lineIndex: number;
+        externalLineId: string;
+    }>;
+    /** Lines whose units the shelf could not cover. The order is recorded all the same. */
+    shortfalls: PluginChannelOrderShortfall[];
+    /** Lines matching no product, recorded by name with no stock moved. */
+    unmatched: number[];
+} | {
+    outcome: 'already';
+    recordId: string;
+    displayRef: string;
+    lines: Array<{
+        lineIndex: number;
+        externalLineId: string;
+    }>;
+}
+/** The seller would not record it; `reason` says why, for the merchant. */
+ | {
+    outcome: 'refused';
+    reason: string;
+};
+export interface PluginChannelOrderCancel {
+    hostId: string;
+    recordId: string;
+    /** Shown on the order's timeline. */
+    reason: string;
+}
+export type PluginChannelOrderCancelOutcome = 
+/** Cancelled, with this many units back on the shelf. */
+{
+    outcome: 'cancelled';
+    restockedUnits: number;
+} | {
+    outcome: 'already';
+}
+/** The seller's rules refused (it has shipped, say); `status` is the seller's word for where it stands. */
+ | {
+    outcome: 'not_cancellable';
+    status: string;
+} | {
+    outcome: 'no_such_record';
+};
+/** The channel's courier took the whole order (AGL-3644): it is fulfilled, with nothing shipped from here. */
+export interface PluginChannelOrderHandoff {
+    hostId: string;
+    recordId: string;
+    /** Shown on the order's timeline, e.g. `Picked up by the DoorDash courier`. */
+    note: string;
+}
+export type PluginChannelOrderHandoffOutcome = {
+    outcome: 'completed';
+} | {
+    outcome: 'already';
+}
+/** The seller's rules refused (it was cancelled, say); `status` is the seller's word for where it stands. */
+ | {
+    outcome: 'not_completable';
+    status: string;
+} | {
+    outcome: 'no_such_record';
+};
+/**
+ * Money the channel gave back to the buyer of an order it sent (AGL-3644):
+ * a refund, or the channel's adjustment of the order — an item removed, a
+ * quantity lowered. No money moves here: the channel refunded its buyer and
+ * takes it from the merchant's payout, so the seller RECORDS it on the order.
+ *
+ * `restock` names the units that never left the store (an item taken off the
+ * order before it was handed over); the seller puts back at most what the
+ * order's own sale took. Empty for a refund of goods already gone.
+ */
+export interface PluginChannelOrderRefund {
+    hostId: string;
+    recordId: string;
+    /** The channel's id for this refund or adjustment: the same id a second time records nothing. */
+    refundId: string;
+    /** Minor units in the order's currency; `0` for an adjustment that only moves stock. */
+    amountCents: number;
+    /** Shown on the order's timeline. */
+    reason: string;
+    restock: Array<{
+        lineIndex: number;
+        quantity: number;
+    }>;
+}
+export type PluginChannelOrderRefundOutcome = 
+/** Recorded: `refundedCents` is the order's refunded total now, `restockedUnits` what went back on the shelf. */
+{
+    outcome: 'recorded';
+    refundedCents: number;
+    restockedUnits: number;
+} | {
+    outcome: 'already';
+}
+/** The seller would not record it; `reason` says why, for the merchant. */
+ | {
+    outcome: 'refused';
+    reason: string;
+} | {
+    outcome: 'no_such_record';
+};
+export interface PluginChannelOrders {
+    /** Records an outside order once, with its units off the shelf in the same write. */
+    importOrder(order: PluginChannelOrder): Promise<PluginChannelOrderOutcome>;
+    /** The channel canceled an order it had sent: cancel it here and put its units back. */
+    cancelOrder(request: PluginChannelOrderCancel): Promise<PluginChannelOrderCancelOutcome>;
+    /** The channel's charges on a sale, once it says what they were. */
+    recordFees(request: {
+        hostId: string;
+        recordId: string;
+        fees: PluginChannelOrderFee[];
+    }): Promise<'recorded' | 'no_such_record'>;
+    /**
+     * The channel's courier took the order (AGL-3644). Optional: a seller that
+     * cannot record a hand-off leaves it out, and the importer leaves the order
+     * for the merchant to fulfill.
+     */
+    completeOrder?(request: PluginChannelOrderHandoff): Promise<PluginChannelOrderHandoffOutcome>;
+    /** The channel refunded or adjusted an order it sent (AGL-3644). Optional, as `completeOrder`. */
+    recordRefund?(request: PluginChannelOrderRefund): Promise<PluginChannelOrderRefundOutcome>;
+}
+/** Registers the seller. A second plugin is refused naming both. */
+export declare function registerPluginChannelOrders(orders: PluginChannelOrders, options?: {
+    pluginId?: string;
+}): void;
+/** The seller, or `null` when no plugin registered one. */
+export declare function pluginChannelOrders(): PluginChannelOrders | null;

package/src/lib/plugin-manager/plugin-channel-orders.js

@@ -0,0 +1,32 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+const PLUGIN_CHANNEL_ORDERS = definePluginServiceContract('core.channel-orders', {
+    multiple: false
+});
+/** Registers the seller. A second plugin is refused naming both. */ export function registerPluginChannelOrders(orders, options) {
+    registerPluginService(PLUGIN_CHANNEL_ORDERS, orders, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The seller, or `null` when no plugin registered one. */ export function pluginChannelOrders() {
+    var _ref;
+    var _resolvePluginServices_;
+    return (_ref = (_resolvePluginServices_ = resolvePluginServices(PLUGIN_CHANNEL_ORDERS)[0]) == null ? void 0 : _resolvePluginServices_.impl) != null ? _ref : null;
+}
+
+//# sourceMappingURL=plugin-channel-orders.js.map

package/src/lib/plugin-manager/plugin-channel-orders.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-channel-orders.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * Orders a store took somewhere else (AGL-3638): a marketplace, a social\n * shop, any outside channel that sells the store's goods and is paid there.\n *\n * Such an order must become a REAL order of the store — numbered with the\n * rest, shown in the same list, shipped from the same dialog, announced to\n * the same subscribers — and its units must leave the same shelf every other\n * channel sells from, in the same write, or two channels sell the last unit\n * twice. The plugin that brings the order in must not write the seller's\n * orders or products itself, so the seller registers\n * {@link PluginChannelOrders} and records each order under its own rules: the\n * order number, the stock decrement and its ledger row, the oversell alert,\n * the order events.\n *\n * ## Once per outside order\n *\n * An import is keyed by `channel.id` and `externalOrderId`. The same pair a\n * second time — a retried run, a page read twice — answers `already` with\n * the record the first import made, and nothing moves.\n *\n * ## The channel was paid, not the store\n *\n * The buyer paid the channel, and the channel pays the merchant out. No\n * money moves through the seller for the order; its refunds and returns\n * happen on the channel. What the channel charged the merchant for the sale\n * (`fees`) is RECORDED on the order for the merchant's books and never\n * charged or collected by anyone here.\n *\n * Money is integer minor units (cents for USD) in `currency`. A seller may\n * refuse an order in a currency its store does not sell in.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-channel-orders`); it is not in the\n * barrel.\n */\n\n/** One line of an outside order. */\nexport interface PluginChannelOrderLine {\n  /** The channel's id for the line, which a shipment back to it names. */\n  externalLineId: string\n  /** The seller SKU the channel sold it under; `null` when it gave none. */\n  sku: string | null\n  /**\n   * The product and configuration, when the importer already knows them\n   * (it listed them from `core.product-catalog`). Otherwise the seller\n   * matches `sku`.\n   */\n  productId?: string | null\n  variantId?: string | null\n  /** The channel's name for the item, kept on the order. */\n  name: string\n  quantity: number\n  /** Per unit, before tax. */\n  unitPriceCents: number\n}\n\n/** The address the order ships to. */\nexport interface PluginChannelOrderAddress {\n  name?: string | null\n  line1?: string | null\n  line2?: string | null\n  city?: string | null\n  state?: string | null\n  postalCode?: string | null\n  /** ISO 3166-1 alpha-2, upper case. */\n  country?: string | null\n  phone?: string | null\n}\n\n/** A channel's charge on a sale, recorded for the merchant and never collected here. */\nexport interface PluginChannelOrderFee {\n  label: string\n  amountCents: number\n}\n\nexport interface PluginChannelOrder {\n  hostId: string\n  /** Stable id and display name, as the importer names its channel. */\n  channel: { id: string; label: string }\n  externalOrderId: string\n  /** What the merchant sees on the channel. */\n  externalRef: string\n  placedAtMs: number\n  /** ISO 4217. */\n  currency: string\n  lines: PluginChannelOrderLine[]\n  shippingCents: number\n  /** Tax the channel collected; the channel, not the store, remits it. */\n  taxCents: number\n  discountCents: number\n  /** What the buyer paid the channel in all. */\n  totalCents: number\n  /** The channel's charges on the sale; `null` while the channel has not said. */\n  fees: PluginChannelOrderFee[] | null\n  customerName: string | null\n  shippingAddress: PluginChannelOrderAddress | null\n  /** Placed in the channel's sandbox: recorded, but never counted as revenue. */\n  testMode: boolean\n  /**\n   * How the goods leave the store (AGL-3644): `ship`, the default, by a\n   * carrier to `shippingAddress`; `courier`, handed over the counter to the\n   * channel's own courier (a delivery app), so nothing is shipped from here\n   * and the seller says so to the merchant.\n   */\n  handoff?: 'ship' | 'courier'\n}\n\n/** A line the store's stock could not cover in full: the channel sold more than the shelf held. */\nexport interface PluginChannelOrderShortfall {\n  lineIndex: number\n  sku: string | null\n  /** Units sold beyond what the shelf held. */\n  short: number\n}\n\nexport type PluginChannelOrderOutcome =\n  | {\n      outcome: 'created'\n      recordId: string\n      /** What a person calls it: `#1042`. */\n      displayRef: string\n      /** Which order line each channel line became. */\n      lines: Array<{ lineIndex: number; externalLineId: string }>\n      /** Lines whose units the shelf could not cover. The order is recorded all the same. */\n      shortfalls: PluginChannelOrderShortfall[]\n      /** Lines matching no product, recorded by name with no stock moved. */\n      unmatched: number[]\n    }\n  | {\n      outcome: 'already'\n      recordId: string\n      displayRef: string\n      lines: Array<{ lineIndex: number; externalLineId: string }>\n    }\n  /** The seller would not record it; `reason` says why, for the merchant. */\n  | { outcome: 'refused'; reason: string }\n\nexport interface PluginChannelOrderCancel {\n  hostId: string\n  recordId: string\n  /** Shown on the order's timeline. */\n  reason: string\n}\n\nexport type PluginChannelOrderCancelOutcome =\n  /** Cancelled, with this many units back on the shelf. */\n  | { outcome: 'cancelled'; restockedUnits: number }\n  | { outcome: 'already' }\n  /** The seller's rules refused (it has shipped, say); `status` is the seller's word for where it stands. */\n  | { outcome: 'not_cancellable'; status: string }\n  | { outcome: 'no_such_record' }\n\n/** The channel's courier took the whole order (AGL-3644): it is fulfilled, with nothing shipped from here. */\nexport interface PluginChannelOrderHandoff {\n  hostId: string\n  recordId: string\n  /** Shown on the order's timeline, e.g. `Picked up by the DoorDash courier`. */\n  note: string\n}\n\nexport type PluginChannelOrderHandoffOutcome =\n  | { outcome: 'completed' }\n  | { outcome: 'already' }\n  /** The seller's rules refused (it was cancelled, say); `status` is the seller's word for where it stands. */\n  | { outcome: 'not_completable'; status: string }\n  | { outcome: 'no_such_record' }\n\n/**\n * Money the channel gave back to the buyer of an order it sent (AGL-3644):\n * a refund, or the channel's adjustment of the order — an item removed, a\n * quantity lowered. No money moves here: the channel refunded its buyer and\n * takes it from the merchant's payout, so the seller RECORDS it on the order.\n *\n * `restock` names the units that never left the store (an item taken off the\n * order before it was handed over); the seller puts back at most what the\n * order's own sale took. Empty for a refund of goods already gone.\n */\nexport interface PluginChannelOrderRefund {\n  hostId: string\n  recordId: string\n  /** The channel's id for this refund or adjustment: the same id a second time records nothing. */\n  refundId: string\n  /** Minor units in the order's currency; `0` for an adjustment that only moves stock. */\n  amountCents: number\n  /** Shown on the order's timeline. */\n  reason: string\n  restock: Array<{ lineIndex: number; quantity: number }>\n}\n\nexport type PluginChannelOrderRefundOutcome =\n  /** Recorded: `refundedCents` is the order's refunded total now, `restockedUnits` what went back on the shelf. */\n  | { outcome: 'recorded'; refundedCents: number; restockedUnits: number }\n  | { outcome: 'already' }\n  /** The seller would not record it; `reason` says why, for the merchant. */\n  | { outcome: 'refused'; reason: string }\n  | { outcome: 'no_such_record' }\n\nexport interface PluginChannelOrders {\n  /** Records an outside order once, with its units off the shelf in the same write. */\n  importOrder(order: PluginChannelOrder): Promise<PluginChannelOrderOutcome>\n  /** The channel canceled an order it had sent: cancel it here and put its units back. */\n  cancelOrder(request: PluginChannelOrderCancel): Promise<PluginChannelOrderCancelOutcome>\n  /** The channel's charges on a sale, once it says what they were. */\n  recordFees(request: {\n    hostId: string\n    recordId: string\n    fees: PluginChannelOrderFee[]\n  }): Promise<'recorded' | 'no_such_record'>\n  /**\n   * The channel's courier took the order (AGL-3644). Optional: a seller that\n   * cannot record a hand-off leaves it out, and the importer leaves the order\n   * for the merchant to fulfill.\n   */\n  completeOrder?(request: PluginChannelOrderHandoff): Promise<PluginChannelOrderHandoffOutcome>\n  /** The channel refunded or adjusted an order it sent (AGL-3644). Optional, as `completeOrder`. */\n  recordRefund?(request: PluginChannelOrderRefund): Promise<PluginChannelOrderRefundOutcome>\n}\n\nconst PLUGIN_CHANNEL_ORDERS = definePluginServiceContract<PluginChannelOrders>('core.channel-orders', {\n  multiple: false,\n})\n\n/** Registers the seller. A second plugin is refused naming both. */\nexport function registerPluginChannelOrders(orders: PluginChannelOrders, options?: { pluginId?: string }): void {\n  registerPluginService(PLUGIN_CHANNEL_ORDERS, orders, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The seller, or `null` when no plugin registered one. */\nexport function pluginChannelOrders(): PluginChannelOrders | null {\n  return resolvePluginServices(PLUGIN_CHANNEL_ORDERS)[0]?.impl ?? null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_CHANNEL_ORDERS","multiple","registerPluginChannelOrders","orders","options","pluginId","pluginChannelOrders","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA4N1B,MAAMC,wBAAwBH,4BAAiD,uBAAuB;IACpGI,UAAU;AACZ;AAEA,kEAAkE,GAClE,OAAO,SAASC,4BAA4BC,MAA2B,EAAEC,OAA+B;IACtGN,sBAAsBE,uBAAuBG,QAAQ,aAC/CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yDAAyD,GACzD,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,sBAAsB,CAAC,EAAE,qBAA/CD,wBAAiDQ,IAAI,mBAAI;AAClE"}

package/src/lib/plugin-manager/plugin-checkout-credits.d.ts

@@ -0,0 +1,288 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Money another plugin honors at checkout and at the register (AGL-3640).
+ *
+ * A rewards balance, store credit and a friend's referral credit are all the
+ * same thing to a seller: a code the buyer brings that pays part of the sale
+ * from an account the SELLER does not keep. The plugin that keeps the account
+ * registers a provider here; the seller asks it, by code, how much the account
+ * can give, reserves that much while an online buyer pays, and takes it in the
+ * same transaction that writes the sale. The seller never reads the provider's
+ * documents and the provider never reads the seller's: the sale records which
+ * provider paid what, under the provider's own opaque `reference`, and the
+ * seller's order events carry that onward.
+ *
+ * ## Money
+ *
+ * Integer cents in the sale's currency, always. A provider answers what it
+ * CAN give and the seller never takes more than that.
+ *
+ *   - Online, the seller {@link PluginCheckoutCreditProvider.hold | holds}
+ *     before the payment processor is asked, so a shortfall is a refusal and
+ *     not an apology. The hold is keyed by the checkout attempt, so a retry
+ *     re-places the same hold rather than a second one, and it lapses on its
+ *     own if the checkout is abandoned and nobody releases it.
+ *   - When the sale is written, the seller {@link PluginCheckoutCreditProvider.stage | stages}
+ *     the account INSIDE its own transaction: the provider reads (and only
+ *     reads) what it needs, and the stage's `debit` writes the redemption in
+ *     the same commit as the sale. A sale that is not written takes nothing;
+ *     a redemption is never written without its sale.
+ *   - A refund gives back through {@link PluginCheckoutCreditProvider.restore | restore},
+ *     idempotent per key, so a retried refund restores once.
+ *
+ * ## Nobody home
+ *
+ * With no provider registered, or none offered on a site, the seller shows no
+ * field and sells exactly as it did before. Every reader here that a seller
+ * calls on a sale path is safe to call with nothing registered.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-checkout-credits`); it is not in the
+ * barrel.
+ */
+/** Where the sale happens. */
+export type CheckoutCreditChannel = 'online' | 'pos';
+/**
+ * A server transaction as a provider uses it: the Admin SDK's shape, typed
+ * structurally so the platform names no database SDK. Every `get` happens
+ * before any write, as the database requires.
+ */
+export interface CheckoutCreditTransaction {
+    get(ref: any): Promise<any>;
+    set(ref: any, data: any, options?: any): unknown;
+    update(ref: any, data: any): unknown;
+    create(ref: any, data: any): unknown;
+}
+/** A provider's refusal, in words the buyer or the cashier can read. */
+export interface CheckoutCreditRefusal {
+    ok: false;
+    /** 400 for a bad code, 404 for an unknown one, 409 for an empty or busy one. */
+    status: number;
+    error: string;
+}
+/** The account a code names. */
+export interface CheckoutCreditAccount {
+    ok: true;
+    /**
+     * The provider's own handle on the account, stored on the sale and handed
+     * back to it later. Never shown to a buyer and never a bearer secret.
+     * {@link CHECKOUT_CREDIT_REFERENCE} holds its shape.
+     */
+    reference: string;
+    /** What the buyer and the receipt call it: `Rewards`, `Referral credit`. */
+    label: string;
+    /** The last characters of the code, for the register and the receipt. */
+    last4: string;
+    /** What the account could give right now, integer cents. */
+    availableCents: number;
+    /** One line for the cashier: `1,250 points and $5.00 store credit`. */
+    detail?: string;
+}
+/**
+ * The account as the seller's transaction read it. The provider builds it in
+ * {@link PluginCheckoutCreditProvider.stage}, which reads; its methods only
+ * WRITE, through the same transaction, so the redemption commits with the sale
+ * or not at all.
+ */
+export interface CheckoutCreditStage {
+    /**
+     * What the account may give now, honoring every live hold except the one
+     * the stage was opened for (that one is this sale's own).
+     */
+    availableCents: number;
+    /**
+     * Takes up to `cents` and returns what was taken: never more than
+     * `availableCents` plus this sale's own hold. `key` names this redemption
+     * (the attempt, or the register payment) and is what a void reverses.
+     */
+    debit(input: {
+        cents: number;
+        key: string;
+        orderId: string;
+        channel: CheckoutCreditChannel;
+    }): number;
+    /** Gives back exactly what the redemption named by `key` took: a voided register payment. */
+    reverse(input: {
+        key: string;
+        orderId: string;
+    }): number;
+}
+export interface CheckoutCreditHoldRequest {
+    hostId: string;
+    reference: string;
+    /** The checkout attempt: the same key re-places the same hold. */
+    holdKey: string;
+    /** The most the sale can take: what is left to pay on the goods. */
+    maxCents: number;
+    /** ISO-4217, lower case. */
+    currency: string;
+    customerEmail: string | null;
+    nowMs: number;
+}
+export interface PluginCheckoutCreditProvider {
+    /** Stable within the plugin: lower-case words and dashes. */
+    key: string;
+    /** What the field and the register's tender button say: `Rewards`. */
+    label: string;
+    /** Whether a code is one this provider issues. Syntax only: no reads. */
+    recognizes(code: string): boolean;
+    /** Whether the site offers it at all: plugin on, program on, plan carries it. */
+    offered(input: {
+        hostId: string;
+        channel: CheckoutCreditChannel;
+    }): Promise<boolean>;
+    /**
+     * A buyer's code — or, at the register only, a `reference` a staff
+     * {@link lookup} returned — to the account it names. `staff` is true only
+     * when the seller has authenticated a staff member for this site; a
+     * provider honors a bare `reference` only then.
+     */
+    resolve(input: {
+        hostId: string;
+        code?: string;
+        reference?: string;
+        channel: CheckoutCreditChannel;
+        customerEmail: string | null;
+        staff: boolean;
+    }): Promise<CheckoutCreditAccount | CheckoutCreditRefusal>;
+    /** Reserves up to `maxCents` for one online checkout attempt. */
+    hold(input: CheckoutCreditHoldRequest): Promise<{
+        ok: true;
+        cents: number;
+    } | CheckoutCreditRefusal>;
+    /** Lets a hold go: an abandoned or refused checkout. Never throws. */
+    release(input: {
+        hostId: string;
+        reference: string;
+        holdKey: string;
+    }): Promise<void>;
+    /**
+     * Reads the account inside the seller's transaction. `null` when it no
+     * longer exists. `holdKey` is this sale's own online hold, when it has one.
+     */
+    stage(input: {
+        transaction: CheckoutCreditTransaction;
+        hostId: string;
+        reference: string;
+        orderId: string;
+        nowMs: number;
+        holdKey?: string;
+    }): Promise<CheckoutCreditStage | null>;
+    /**
+     * Gives back up to `cents` of what the sale took from the account, for a
+     * refund. Idempotent per `key`; returns the cents given back (0 for a key
+     * already restored, or an account that is gone).
+     */
+    restore(input: {
+        hostId: string;
+        reference: string;
+        orderId: string;
+        cents: number;
+        key: string;
+    }): Promise<number>;
+    /** Staff search at the register by email or code. Optional. */
+    lookup?(input: {
+        hostId: string;
+        query: string;
+    }): Promise<CheckoutCreditAccount[]>;
+}
+/** A provider as the seller resolves it. */
+export interface ResolvedCheckoutCreditProvider {
+    /** `{pluginId}.{key}`: what a sale records. */
+    providerId: string;
+    pluginId: string;
+    provider: PluginCheckoutCreditProvider;
+}
+/**
+ * What a sale records of one redemption, on the sale and in the events the
+ * seller raises about it, so the provider learns what was taken from the
+ * seller's own facts. `appliedAs` says how the seller counted it: online it
+ * comes off the goods like a discount, at the register it is one of the
+ * sale's payments.
+ */
+export interface PluginCheckoutCreditSold {
+    providerId: string;
+    pluginId: string;
+    key: string;
+    reference: string;
+    label: string;
+    last4: string;
+    amountCents: number;
+    appliedAs: 'discount' | 'tender';
+}
+/** The shape of a provider's `reference`: short, and safe in a document path segment. */
+export declare const CHECKOUT_CREDIT_REFERENCE: RegExp;
+/** Joins the providers. A plugin re-registering a key replaces its own. */
+export declare function registerPluginCheckoutCredit(provider: PluginCheckoutCreditProvider, options?: {
+    pluginId?: string;
+}): void;
+/** Whether any plugin registered a provider: a seller with none skips the field. */
+export declare function hasPluginCheckoutCredits(): boolean;
+/**
+ * A code as typed — any case, spaces and dashes — in the one form providers
+ * see: upper case, letters, digits and single dashes, at most 40 characters.
+ * Empty when nothing usable was typed.
+ */
+export declare function normalizeCheckoutCreditCode(value: unknown): string;
+/** The provider that issues a code, or `null`. The first to recognize it answers. */
+export declare function checkoutCreditProviderForCode(code: string): ResolvedCheckoutCreditProvider | null;
+/** One provider by the id a sale recorded, or `null` when it is gone. */
+export declare function checkoutCreditProvider(providerId: string): ResolvedCheckoutCreditProvider | null;
+/**
+ * The providers a site offers on a channel, for the cart's field and the
+ * register's tender. Never throws: a provider that fails is not offered.
+ */
+export declare function offeredCheckoutCredits(input: {
+    hostId: string;
+    channel: CheckoutCreditChannel;
+}): Promise<Array<{
+    providerId: string;
+    label: string;
+    lookup: boolean;
+}>>;
+/** An account answer held to the contract, or a refusal in its place. */
+export declare function normalizeCheckoutCreditAccount(answer: CheckoutCreditAccount | CheckoutCreditRefusal | null | undefined): CheckoutCreditAccount | CheckoutCreditRefusal;
+/** Cents a provider says it held or took, as whole non-negative cents no larger than `ceiling`. */
+export declare function boundedCreditCents(value: unknown, ceiling: number): number;
+/** The metadata key an online redemption rides under on the payment processor. */
+export declare const CHECKOUT_CREDIT_METADATA_KEY = "credit0";
+/** What an online checkout carries to its webhook: the hold to settle. */
+export interface CheckoutCreditHeld {
+    providerId: string;
+    reference: string;
+    holdKey: string;
+    amountCents: number;
+    label: string;
+    last4: string;
+}
+/**
+ * The hold an online checkout placed, packed for a payment processor's
+ * metadata: one key holding `[providerId, reference, holdKey, cents, label, last4]`
+ * as JSON, inside a 500-character value. Never the code itself: metadata is
+ * readable on the merchant's dashboard, and a code is a bearer secret.
+ */
+export declare function encodeCheckoutCreditMetadata(held: CheckoutCreditHeld): Record<string, string>;
+/** Reads {@link encodeCheckoutCreditMetadata} back. Anything unreadable is `null`, never guessed. */
+export declare function decodeCheckoutCreditMetadata(metadata: Record<string, unknown> | null | undefined): CheckoutCreditHeld | null;
+/** The plugin id and key of a provider id. */
+export declare function splitCheckoutCreditProviderId(providerId: string): {
+    pluginId: string;
+    key: string;
+} | null;
+/** A recorded redemption, as a seller stores it and its events carry it. */
+export declare function checkoutCreditSold(input: Omit<PluginCheckoutCreditSold, 'pluginId' | 'key'>): PluginCheckoutCreditSold | null;