@aglyn/aglyn 1.0.0-beta.230 → 1.0.0-beta.232

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-extras.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @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.
+ */
+/**
+ * Optional lines a buyer may add at checkout, offered by another plugin
+ * (AGL-3635).
+ *
+ * Package protection is the first: a plugin that insures parcels quotes a
+ * premium for the basket, the seller shows it as a box the buyer ticks, and
+ * the seller charges it as one more line. The seller never learns which
+ * insurer answered and the insurer never reads the seller's documents: the
+ * offer crosses here, and what was bought is recorded on the sale, which the
+ * seller's own events then carry.
+ *
+ * ## Money
+ *
+ * Every amount is integer cents in the request's currency. An offer is
+ * advisory until the sale: the seller asks again when the buyer pays and
+ * charges THAT answer, so a stale price in a drawer is never what is
+ * charged. An offer whose amount is not a positive integer, or whose
+ * currency differs from the request's, is dropped rather than rounded.
+ *
+ * ## Nobody home is an empty list
+ *
+ * A provider that is not configured, not switched on for the site, slow or
+ * failing answers nothing, and the seller sells exactly as it did before.
+ * {@link quotePluginCheckoutExtras} never throws.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-checkout-extras`); it is not in the
+ * barrel.
+ */
+/** One line of the basket, as a provider prices it. */
+export interface PluginCheckoutExtraLine {
+    /** The seller's id for the item, when it has one. */
+    itemId?: string;
+    name: string;
+    sku?: string;
+    quantity: number;
+    /** Per unit, integer cents, before discounts. */
+    unitCents: number;
+    /** Whether the line travels in a parcel. */
+    ships: boolean;
+}
+/** What a seller asks: the basket a buyer is about to pay for. */
+export interface PluginCheckoutExtraRequest {
+    hostId: string;
+    /** ISO-4217, lower case. */
+    currency: string;
+    /** The goods' value, integer cents, before discounts and shipping. */
+    itemsCents: number;
+    lines: PluginCheckoutExtraLine[];
+    /** Where the buyer said it goes, when they said. */
+    destination?: {
+        country?: string;
+        postalCode?: string;
+    };
+    /** Aborted when the seller stops waiting; a provider passes it to its fetches. */
+    signal?: AbortSignal;
+}
+/** What a provider offers for that basket. */
+export interface PluginCheckoutExtraOffer {
+    /** Stable within the provider: `package-protection`. Lower-case words and dashes. */
+    key: string;
+    /** What the buyer reads beside the box: `Package protection`. */
+    label: string;
+    /** One sentence under it. */
+    description?: string;
+    /** Integer cents, above zero. */
+    amountCents: number;
+    /** ISO-4217, lower case; must be the request's. */
+    currency: string;
+    /** Whether the box starts ticked. The merchant decides; default unticked. */
+    defaultSelected?: boolean;
+    /** The provider's id for this quote, carried onto the sale (64 characters at most). */
+    quoteRef?: string;
+    /** A page the buyer can read about it, `https:` only. */
+    termsUrl?: string;
+}
+export interface PluginCheckoutExtraProvider {
+    /** The offer for this basket, or `null`. Throwing reads as `null`. */
+    offer(request: PluginCheckoutExtraRequest): Promise<PluginCheckoutExtraOffer | null>;
+}
+/** An offer as the seller sees it: whose it is, and the id it is chosen by. */
+export interface QuotedPluginCheckoutExtra extends Required<Pick<PluginCheckoutExtraOffer, 'defaultSelected'>> {
+    /** `{pluginId}.{key}`: what a buyer's choice names. */
+    id: string;
+    pluginId: string;
+    key: string;
+    label: string;
+    description?: string;
+    amountCents: number;
+    currency: string;
+    quoteRef?: string;
+    termsUrl?: string;
+}
+/**
+ * What a sale recorded of one extra the buyer took. The seller stores this
+ * on the sale and puts it in the events it raises about the sale, so the
+ * provider learns what was bought from the seller's own facts.
+ */
+export interface PluginCheckoutExtraSold {
+    id: string;
+    pluginId: string;
+    key: string;
+    label: string;
+    amountCents: number;
+    quoteRef?: string;
+}
+/** The most extras one checkout carries. */
+export declare const MAX_CHECKOUT_EXTRAS = 3;
+/** Joins the providers. Re-registering under the same plugin replaces its own. */
+export declare function registerPluginCheckoutExtra(provider: PluginCheckoutExtraProvider, options?: {
+    pluginId?: string;
+}): void;
+/** Whether any plugin offers extras: a seller with none skips the question. */
+export declare function hasPluginCheckoutExtras(): boolean;
+/**
+ * An offer held to the contract, or `null`: a positive integer amount in the
+ * request's currency, a key and a label, and nothing else a page would render
+ * that it should not.
+ */
+export declare function normalizePluginCheckoutExtra(pluginId: string, offer: PluginCheckoutExtraOffer | null | undefined, currency: string): QuotedPluginCheckoutExtra | null;
+/**
+ * Asks every provider at once and keeps what answered within `timeoutMs`,
+ * each one held to the contract. Never throws; a provider that throws, is
+ * late or answers nonsense is simply absent. At most
+ * {@link MAX_CHECKOUT_EXTRAS}, in the providers' resolve order.
+ */
+export declare function quotePluginCheckoutExtras(request: Omit<PluginCheckoutExtraRequest, 'signal'>, options: {
+    timeoutMs: number;
+}): Promise<QuotedPluginCheckoutExtra[]>;
+/**
+ * The buyer's choice, read from a request body: the ids of offers they took,
+ * de-duplicated and bounded. Ids only; the amounts are always asked again.
+ */
+export declare function readChosenCheckoutExtras(value: unknown): string[];
+/** The metadata keys the extras ride under: `extra0`, `extra1`, `extra2`. */
+export declare const CHECKOUT_EXTRA_METADATA_PREFIX = "extra";
+/**
+ * The extras a sale carries, packed for a payment processor's metadata: one
+ * key per extra (`extra0` …), each `[id, cents, label, quoteRef?]` as JSON,
+ * well inside a 500-character value. One key each, so a long quote id can
+ * never truncate another extra out of the record.
+ */
+export declare function encodeCheckoutExtrasMetadata(extras: readonly QuotedPluginCheckoutExtra[]): Record<string, string>;
+/**
+ * Reads {@link encodeCheckoutExtrasMetadata} back off the metadata object.
+ * Anything unreadable is dropped, never guessed.
+ */
+export declare function decodeCheckoutExtrasMetadata(metadata: Record<string, unknown> | null | undefined): PluginCheckoutExtraSold[];
+/** The cents a sale's extras add up to. */
+export declare function checkoutExtrasCents(extras: ReadonlyArray<{
+    amountCents: number;
+}> | null | undefined): number;

package/src/lib/plugin-manager/plugin-checkout-extras.js

@@ -0,0 +1,172 @@
+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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+/** The most extras one checkout carries. */ export const MAX_CHECKOUT_EXTRAS = 3;
+const KEY = /^[a-z][a-z0-9-]{1,39}$/;
+const PLUGIN_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const PLUGIN_CHECKOUT_EXTRAS = definePluginServiceContract('core.checkout-extras', {
+    multiple: true
+});
+/** Joins the providers. Re-registering under the same plugin replaces its own. */ export function registerPluginCheckoutExtra(provider, options) {
+    var _getRegisteringPluginId;
+    const pluginId = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId;
+    registerPluginService(PLUGIN_CHECKOUT_EXTRAS, provider, _extends({}, pluginId ? {
+        pluginId
+    } : {}));
+}
+/** Whether any plugin offers extras: a seller with none skips the question. */ export function hasPluginCheckoutExtras() {
+    return resolvePluginServices(PLUGIN_CHECKOUT_EXTRAS).length > 0;
+}
+function cleanText(value, max) {
+    // Control characters become spaces: an offer's words are drawn on a page.
+    return Array.from(String(value != null ? value : ''), (char)=>char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127 ? ' ' : char).join('').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+/**
+ * An offer held to the contract, or `null`: a positive integer amount in the
+ * request's currency, a key and a label, and nothing else a page would render
+ * that it should not.
+ */ export function normalizePluginCheckoutExtra(pluginId, offer, currency) {
+    var _offer_key, _offer_currency, _offer_termsUrl;
+    if (!offer || !PLUGIN_ID.test(pluginId)) return null;
+    const key = String((_offer_key = offer.key) != null ? _offer_key : '');
+    const label = cleanText(offer.label, 60);
+    const amountCents = offer.amountCents;
+    if (!KEY.test(key) || !label) return null;
+    if (typeof amountCents !== 'number' || !Number.isSafeInteger(amountCents) || amountCents <= 0) return null;
+    if (String((_offer_currency = offer.currency) != null ? _offer_currency : '').toLowerCase() !== String(currency != null ? currency : '').toLowerCase()) return null;
+    const description = cleanText(offer.description, 240);
+    const quoteRef = cleanText(offer.quoteRef, 64);
+    const termsUrl = /^https:\/\/[^\s"'<>]+$/i.test(String((_offer_termsUrl = offer.termsUrl) != null ? _offer_termsUrl : '')) ? String(offer.termsUrl) : '';
+    return _extends({
+        id: `${pluginId}.${key}`,
+        pluginId,
+        key,
+        label
+    }, description ? {
+        description
+    } : {}, {
+        amountCents,
+        currency: currency.toLowerCase(),
+        defaultSelected: offer.defaultSelected === true
+    }, quoteRef ? {
+        quoteRef
+    } : {}, termsUrl ? {
+        termsUrl
+    } : {});
+}
+/**
+ * Asks every provider at once and keeps what answered within `timeoutMs`,
+ * each one held to the contract. Never throws; a provider that throws, is
+ * late or answers nonsense is simply absent. At most
+ * {@link MAX_CHECKOUT_EXTRAS}, in the providers' resolve order.
+ */ export async function quotePluginCheckoutExtras(request, options) {
+    const providers = resolvePluginServices(PLUGIN_CHECKOUT_EXTRAS);
+    if (!providers.length) return [];
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((resolve)=>{
+        timer = setTimeout(()=>{
+            controller.abort();
+            resolve('late');
+        }, Math.max(0, options.timeoutMs));
+    });
+    try {
+        const answers = await Promise.all(providers.map(async (entry)=>{
+            const answer = await Promise.race([
+                entry.impl.offer(_extends({}, request, {
+                    signal: controller.signal
+                })).catch((error)=>{
+                    console.error(`[checkout-extras] provider "${entry.pluginId}" failed for ${request.hostId}`, error);
+                    return null;
+                }),
+                deadline
+            ]);
+            return answer === 'late' ? null : normalizePluginCheckoutExtra(entry.pluginId, answer, request.currency);
+        }));
+        const seen = new Set();
+        return answers.filter((answer)=>Boolean(answer)).filter((answer)=>seen.has(answer.id) ? false : (seen.add(answer.id), true)).slice(0, MAX_CHECKOUT_EXTRAS);
+    } finally{
+        if (timer) clearTimeout(timer);
+    }
+}
+/**
+ * The buyer's choice, read from a request body: the ids of offers they took,
+ * de-duplicated and bounded. Ids only; the amounts are always asked again.
+ */ export function readChosenCheckoutExtras(value) {
+    if (!Array.isArray(value)) return [];
+    const ids = value.map((entry)=>String(entry != null ? entry : '').trim()).filter((entry)=>/^[a-z][a-z0-9-]{0,63}\.[a-z][a-z0-9-]{1,39}$/.test(entry));
+    return [
+        ...new Set(ids)
+    ].slice(0, MAX_CHECKOUT_EXTRAS);
+}
+/** The metadata keys the extras ride under: `extra0`, `extra1`, `extra2`. */ export const CHECKOUT_EXTRA_METADATA_PREFIX = 'extra';
+/**
+ * The extras a sale carries, packed for a payment processor's metadata: one
+ * key per extra (`extra0` …), each `[id, cents, label, quoteRef?]` as JSON,
+ * well inside a 500-character value. One key each, so a long quote id can
+ * never truncate another extra out of the record.
+ */ export function encodeCheckoutExtrasMetadata(extras) {
+    const packed = {};
+    extras.slice(0, MAX_CHECKOUT_EXTRAS).forEach((extra, index)=>{
+        const entry = [
+            extra.id,
+            extra.amountCents,
+            extra.label.slice(0, 60)
+        ];
+        if (extra.quoteRef) entry.push(extra.quoteRef.slice(0, 64));
+        packed[`${CHECKOUT_EXTRA_METADATA_PREFIX}${index}`] = JSON.stringify(entry);
+    });
+    return packed;
+}
+/**
+ * Reads {@link encodeCheckoutExtrasMetadata} back off the metadata object.
+ * Anything unreadable is dropped, never guessed.
+ */ export function decodeCheckoutExtrasMetadata(metadata) {
+    const sold = [];
+    for(let index = 0; index < MAX_CHECKOUT_EXTRAS; index += 1){
+        const raw = metadata == null ? void 0 : metadata[`${CHECKOUT_EXTRA_METADATA_PREFIX}${index}`];
+        if (raw === undefined || raw === null || raw === '') continue;
+        let entry;
+        try {
+            entry = JSON.parse(String(raw));
+        } catch (unused) {
+            continue;
+        }
+        if (!Array.isArray(entry)) continue;
+        const [id, cents, label, quoteRef] = entry;
+        const match = /^([a-z][a-z0-9-]{0,63})\.([a-z][a-z0-9-]{1,39})$/.exec(String(id != null ? id : ''));
+        if (!match || typeof cents !== 'number' || !Number.isSafeInteger(cents) || cents <= 0) continue;
+        if (sold.some((extra)=>extra.id === id)) continue;
+        const ref = cleanText(quoteRef, 64);
+        sold.push(_extends({
+            id: String(id),
+            pluginId: match[1],
+            key: match[2],
+            label: cleanText(label, 60) || 'Extra',
+            amountCents: cents
+        }, ref ? {
+            quoteRef: ref
+        } : {}));
+    }
+    return sold;
+}
+/** The cents a sale's extras add up to. */ export function checkoutExtrasCents(extras) {
+    return (extras != null ? extras : []).reduce((sum, extra)=>sum + (Number.isSafeInteger(extra == null ? void 0 : extra.amountCents) && extra.amountCents > 0 ? extra.amountCents : 0), 0);
+}
+
+//# sourceMappingURL=plugin-checkout-extras.js.map