@aglyn/aglyn 1.0.0-beta.231 → 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-product-catalog.d.ts

@@ -99,6 +99,11 @@ export interface CatalogOffer {
     hasVariants: boolean;
     productId: string;
     variantId: string;
+    /**
+     * The merchant's own SKU for this configuration, as entered; absent when
+     * they entered none. What a marketplace matches its listing by (AGL-3638).
+     */
+    sku?: string;
     /** The product's name. */
     productName: string;
     /** The product's name with this configuration's choices, e.g. `Tee — Red / M`. */

package/src/lib/plugin-manager/plugin-product-catalog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-product-catalog.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 * A site's sellable catalog, read whole and in pages by a plugin that does\n * not own it (AGL-3637).\n *\n * A product feed, a marketplace listing sync and an ad catalog all need the\n * same thing: every offer a store sells, with the facts a shopping channel\n * asks for — price in the store's currency, stock, photos, identifiers,\n * shipping. The plugin that keeps the products answers it here, so a reader\n * never learns where products are stored, how variants are modeled or what a\n * deleted product looks like.\n *\n * ## One OFFER per sellable configuration\n *\n * A product with one configuration is one offer whose `id` is the product's\n * own id. A product with several (sizes, colors) is one offer per\n * configuration, each with its own `id` and the product's id as `groupId`,\n * which is what every shopping channel calls the variant group.\n *\n * ## Money is integer minor units in the store's currency\n *\n * `priceMinor` and every other amount are integers (cents for USD) in\n * {@link CatalogStore.currency}. A reader formats them; it never assumes a\n * currency.\n *\n * ## Pages, not a list\n *\n * A store may hold far more products than one read should load, so the\n * catalog is walked in pages: `page()` answers up to about `limit` offers and\n * a `nextCursor` to continue from, `null` on the last page. A cursor is the\n * owner's own opaque string; a reader passes it back untouched.\n *\n * ## One owner\n *\n * A slot, like the tax profile: a site has one catalog, so a second plugin's\n * registration is refused and the incumbent keeps serving. No owner\n * registered is an ordinary answer — {@link pluginProductCatalog} returns\n * `undefined` and a reader serves nothing.\n */\n\n/** The store an offer belongs to, as a channel needs it. */\nexport interface CatalogStore {\n  hostId: string\n  /** The store's name, as its site calls itself. */\n  name: string\n  /**\n   * The origin the store's pages are served on (`https://shop.example.com`),\n   * or `null` when the site has no address yet.\n   */\n  origin: string | null\n  /** ISO 4217, upper case. Every amount in the catalog is in it. */\n  currency: string\n  /**\n   * Whether `/products/{slug}` pages are served. When `false`, every offer's\n   * `path` answers 404, and a channel will refuse the offers.\n   */\n  productPagesServed: boolean\n  /**\n   * Countries the store's checkout prices shipping to by a live carrier\n   * quote rather than its own table (ISO 3166-1 alpha-2, upper case). An\n   * offer carries no {@link CatalogShippingPrice} for them, because the price\n   * depends on the address; a channel that calculates carrier rates itself\n   * prices them from the offer's weight and dimensions.\n   */\n  carrierPricedCountries: string[]\n}\n\nexport type CatalogAvailability = 'in_stock' | 'out_of_stock' | 'backorder'\nexport type CatalogCondition = 'new' | 'refurbished' | 'used'\nexport type CatalogProductKind = 'physical' | 'digital' | 'service'\n\n/** What one offer costs to ship to one country, cheapest rate first chosen. */\nexport interface CatalogShippingPrice {\n  /** ISO 3166-1 alpha-2, upper case. */\n  country: string\n  /** The rate's name as the shopper sees it at checkout. */\n  service: string\n  priceMinor: number\n}\n\n/** One sellable configuration of a product. */\nexport interface CatalogOffer {\n  /** Stable, unique within the store: the product id, or product and variant. */\n  id: string\n  /** The product's id: the variant group every configuration shares. */\n  groupId: string\n  /** Whether the product has more than one configuration. */\n  hasVariants: boolean\n  productId: string\n  variantId: string\n  /** The product's name. */\n  productName: string\n  /** The product's name with this configuration's choices, e.g. `Tee — Red / M`. */\n  title: string\n  /** Plain text: no markup. May be empty. */\n  description: string\n  /** Site-relative path of the product page, e.g. `/products/tee`. */\n  path: string\n  /** Absolute URL of the photo shown for this configuration. */\n  imageUrl?: string\n  /** Absolute URLs of the product's other photos, in order. */\n  additionalImageUrls: string[]\n  /** What the shopper pays, before any sale: the regular price. */\n  priceMinor: number\n  /** A lower price the offer is on sale for now; absent when not on sale. */\n  salePriceMinor?: number\n  availability: CatalogAvailability\n  /** Units in stock, or `null` when stock is not tracked. */\n  quantity: number | null\n  kind: CatalogProductKind\n  /** Whether the product is sold only as a recurring subscription. */\n  subscriptionOnly: boolean\n  /** What the merchant entered for shopping channels; absent when they did not. */\n  condition?: CatalogCondition\n  brand?: string\n  /** GTIN (UPC, EAN, ISBN, JAN, ITF-14) as entered, digits only. */\n  gtin?: string\n  mpn?: string\n  /** A Google product taxonomy id or full path, as entered. */\n  googleProductCategory?: string\n  /** The store's own category path, e.g. `Apparel > Shirts`. */\n  productType?: string\n  /** The configuration's choices, by option name. */\n  options: Readonly<Record<string, string>>\n  /** The choice of an option named like a color, when there is one. */\n  color?: string\n  /** The choice of an option named like a size, when there is one. */\n  size?: string\n  weightGrams?: number\n  /** One unit's packed size, in centimeters, when the merchant entered it. */\n  dimensionsCm?: { length: number; width: number; height: number }\n  /** What it costs to ship one unit, per country the store ships to. */\n  shipping: CatalogShippingPrice[]\n  /** When the product last changed, epoch ms; absent when unknown. */\n  updatedAtMs?: number\n}\n\nexport interface CatalogPage {\n  offers: CatalogOffer[]\n  /** Where the next page starts, or `null` when this is the last one. */\n  nextCursor: string | null\n}\n\nexport interface PluginProductCatalog {\n  /** The store, or `null` for a site that does not sell. */\n  store(hostId: string): Promise<CatalogStore | null>\n  /**\n   * One page of the store's live, listed offers: never a draft, archived or\n   * deleted product. About `limit` offers — a product's configurations are\n   * never split across pages, so a page may run over by one product's worth.\n   */\n  page(request: { hostId: string; cursor?: string | null; limit: number }): Promise<CatalogPage>\n}\n\nexport const PLUGIN_PRODUCT_CATALOG = definePluginServiceContract<PluginProductCatalog>(\n  'core.product-catalog',\n  { multiple: false },\n)\n\n/** Registers the store catalog. A second plugin's is refused, naming both. */\nexport function registerPluginProductCatalog(\n  catalog: PluginProductCatalog,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PRODUCT_CATALOG, catalog, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered catalog, or `undefined` when no plugin sells. */\nexport function pluginProductCatalog(): PluginProductCatalog | undefined {\n  return resolvePluginServices(PLUGIN_PRODUCT_CATALOG)[0]?.impl\n}\n\n/**\n * The plugin that publishes the catalog to shopping channels, as the\n * catalog's owner hands it an address of its own (AGL-3637).\n *\n * Before any plugin published feeds, the plugin that keeps the products\n * served one feed itself, and merchants pasted that address into their\n * channel. The address stays the owner's — a request for it reaches the\n * owner's routes — but the feed is written by whoever publishes the catalog\n * now, so the owner answers it from here. Nobody registered is an ordinary\n * answer: {@link pluginCatalogFeed} returns `undefined` and the owner\n * answers 404.\n */\nexport interface PluginCatalogFeed {\n  /**\n   * Answers a request for the owner's pre-existing feed address for the site\n   * `hostId`: the feed, a 404 when the site's publisher has retired the\n   * address or does not publish, or a 503 to try later.\n   */\n  serveLegacyFeed(request: Request, hostId: string): Promise<Response>\n}\n\nexport const PLUGIN_CATALOG_FEED = definePluginServiceContract<PluginCatalogFeed>(\n  'core.catalog-feed',\n  { multiple: false },\n)\n\n/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */\nexport function registerPluginCatalogFeed(\n  feed: PluginCatalogFeed,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_CATALOG_FEED, feed, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */\nexport function pluginCatalogFeed(): PluginCatalogFeed | undefined {\n  return resolvePluginServices(PLUGIN_CATALOG_FEED)[0]?.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PRODUCT_CATALOG","multiple","registerPluginProductCatalog","catalog","options","pluginId","pluginProductCatalog","impl","PLUGIN_CATALOG_FEED","registerPluginCatalogFeed","feed","pluginCatalogFeed"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2J1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED,4EAA4E,GAC5E,OAAO,SAASC,6BACdC,OAA6B,EAC7BC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,SAAS,aACjDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,iEAAiE,GACjE,OAAO,SAASC;QACPP;IAAP,QAAOA,0BAAAA,sBAAsBC,uBAAuB,CAAC,EAAE,qBAAhDD,wBAAkDQ,IAAI;AAC/D;AAuBA,OAAO,MAAMC,sBAAsBX,4BACjC,qBACA;IAAEI,UAAU;AAAM,GACnB;AAED,uFAAuF,GACvF,OAAO,SAASQ,0BACdC,IAAuB,EACvBN,OAA+B;IAE/BN,sBAAsBU,qBAAqBE,MAAM,aAC3CN,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,kFAAkF,GAClF,OAAO,SAASM;QACPZ;IAAP,QAAOA,0BAAAA,sBAAsBS,oBAAoB,CAAC,EAAE,qBAA7CT,wBAA+CQ,IAAI;AAC5D"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-product-catalog.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 * A site's sellable catalog, read whole and in pages by a plugin that does\n * not own it (AGL-3637).\n *\n * A product feed, a marketplace listing sync and an ad catalog all need the\n * same thing: every offer a store sells, with the facts a shopping channel\n * asks for — price in the store's currency, stock, photos, identifiers,\n * shipping. The plugin that keeps the products answers it here, so a reader\n * never learns where products are stored, how variants are modeled or what a\n * deleted product looks like.\n *\n * ## One OFFER per sellable configuration\n *\n * A product with one configuration is one offer whose `id` is the product's\n * own id. A product with several (sizes, colors) is one offer per\n * configuration, each with its own `id` and the product's id as `groupId`,\n * which is what every shopping channel calls the variant group.\n *\n * ## Money is integer minor units in the store's currency\n *\n * `priceMinor` and every other amount are integers (cents for USD) in\n * {@link CatalogStore.currency}. A reader formats them; it never assumes a\n * currency.\n *\n * ## Pages, not a list\n *\n * A store may hold far more products than one read should load, so the\n * catalog is walked in pages: `page()` answers up to about `limit` offers and\n * a `nextCursor` to continue from, `null` on the last page. A cursor is the\n * owner's own opaque string; a reader passes it back untouched.\n *\n * ## One owner\n *\n * A slot, like the tax profile: a site has one catalog, so a second plugin's\n * registration is refused and the incumbent keeps serving. No owner\n * registered is an ordinary answer — {@link pluginProductCatalog} returns\n * `undefined` and a reader serves nothing.\n */\n\n/** The store an offer belongs to, as a channel needs it. */\nexport interface CatalogStore {\n  hostId: string\n  /** The store's name, as its site calls itself. */\n  name: string\n  /**\n   * The origin the store's pages are served on (`https://shop.example.com`),\n   * or `null` when the site has no address yet.\n   */\n  origin: string | null\n  /** ISO 4217, upper case. Every amount in the catalog is in it. */\n  currency: string\n  /**\n   * Whether `/products/{slug}` pages are served. When `false`, every offer's\n   * `path` answers 404, and a channel will refuse the offers.\n   */\n  productPagesServed: boolean\n  /**\n   * Countries the store's checkout prices shipping to by a live carrier\n   * quote rather than its own table (ISO 3166-1 alpha-2, upper case). An\n   * offer carries no {@link CatalogShippingPrice} for them, because the price\n   * depends on the address; a channel that calculates carrier rates itself\n   * prices them from the offer's weight and dimensions.\n   */\n  carrierPricedCountries: string[]\n}\n\nexport type CatalogAvailability = 'in_stock' | 'out_of_stock' | 'backorder'\nexport type CatalogCondition = 'new' | 'refurbished' | 'used'\nexport type CatalogProductKind = 'physical' | 'digital' | 'service'\n\n/** What one offer costs to ship to one country, cheapest rate first chosen. */\nexport interface CatalogShippingPrice {\n  /** ISO 3166-1 alpha-2, upper case. */\n  country: string\n  /** The rate's name as the shopper sees it at checkout. */\n  service: string\n  priceMinor: number\n}\n\n/** One sellable configuration of a product. */\nexport interface CatalogOffer {\n  /** Stable, unique within the store: the product id, or product and variant. */\n  id: string\n  /** The product's id: the variant group every configuration shares. */\n  groupId: string\n  /** Whether the product has more than one configuration. */\n  hasVariants: boolean\n  productId: string\n  variantId: string\n  /**\n   * The merchant's own SKU for this configuration, as entered; absent when\n   * they entered none. What a marketplace matches its listing by (AGL-3638).\n   */\n  sku?: string\n  /** The product's name. */\n  productName: string\n  /** The product's name with this configuration's choices, e.g. `Tee — Red / M`. */\n  title: string\n  /** Plain text: no markup. May be empty. */\n  description: string\n  /** Site-relative path of the product page, e.g. `/products/tee`. */\n  path: string\n  /** Absolute URL of the photo shown for this configuration. */\n  imageUrl?: string\n  /** Absolute URLs of the product's other photos, in order. */\n  additionalImageUrls: string[]\n  /** What the shopper pays, before any sale: the regular price. */\n  priceMinor: number\n  /** A lower price the offer is on sale for now; absent when not on sale. */\n  salePriceMinor?: number\n  availability: CatalogAvailability\n  /** Units in stock, or `null` when stock is not tracked. */\n  quantity: number | null\n  kind: CatalogProductKind\n  /** Whether the product is sold only as a recurring subscription. */\n  subscriptionOnly: boolean\n  /** What the merchant entered for shopping channels; absent when they did not. */\n  condition?: CatalogCondition\n  brand?: string\n  /** GTIN (UPC, EAN, ISBN, JAN, ITF-14) as entered, digits only. */\n  gtin?: string\n  mpn?: string\n  /** A Google product taxonomy id or full path, as entered. */\n  googleProductCategory?: string\n  /** The store's own category path, e.g. `Apparel > Shirts`. */\n  productType?: string\n  /** The configuration's choices, by option name. */\n  options: Readonly<Record<string, string>>\n  /** The choice of an option named like a color, when there is one. */\n  color?: string\n  /** The choice of an option named like a size, when there is one. */\n  size?: string\n  weightGrams?: number\n  /** One unit's packed size, in centimeters, when the merchant entered it. */\n  dimensionsCm?: { length: number; width: number; height: number }\n  /** What it costs to ship one unit, per country the store ships to. */\n  shipping: CatalogShippingPrice[]\n  /** When the product last changed, epoch ms; absent when unknown. */\n  updatedAtMs?: number\n}\n\nexport interface CatalogPage {\n  offers: CatalogOffer[]\n  /** Where the next page starts, or `null` when this is the last one. */\n  nextCursor: string | null\n}\n\nexport interface PluginProductCatalog {\n  /** The store, or `null` for a site that does not sell. */\n  store(hostId: string): Promise<CatalogStore | null>\n  /**\n   * One page of the store's live, listed offers: never a draft, archived or\n   * deleted product. About `limit` offers — a product's configurations are\n   * never split across pages, so a page may run over by one product's worth.\n   */\n  page(request: { hostId: string; cursor?: string | null; limit: number }): Promise<CatalogPage>\n}\n\nexport const PLUGIN_PRODUCT_CATALOG = definePluginServiceContract<PluginProductCatalog>(\n  'core.product-catalog',\n  { multiple: false },\n)\n\n/** Registers the store catalog. A second plugin's is refused, naming both. */\nexport function registerPluginProductCatalog(\n  catalog: PluginProductCatalog,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PRODUCT_CATALOG, catalog, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered catalog, or `undefined` when no plugin sells. */\nexport function pluginProductCatalog(): PluginProductCatalog | undefined {\n  return resolvePluginServices(PLUGIN_PRODUCT_CATALOG)[0]?.impl\n}\n\n/**\n * The plugin that publishes the catalog to shopping channels, as the\n * catalog's owner hands it an address of its own (AGL-3637).\n *\n * Before any plugin published feeds, the plugin that keeps the products\n * served one feed itself, and merchants pasted that address into their\n * channel. The address stays the owner's — a request for it reaches the\n * owner's routes — but the feed is written by whoever publishes the catalog\n * now, so the owner answers it from here. Nobody registered is an ordinary\n * answer: {@link pluginCatalogFeed} returns `undefined` and the owner\n * answers 404.\n */\nexport interface PluginCatalogFeed {\n  /**\n   * Answers a request for the owner's pre-existing feed address for the site\n   * `hostId`: the feed, a 404 when the site's publisher has retired the\n   * address or does not publish, or a 503 to try later.\n   */\n  serveLegacyFeed(request: Request, hostId: string): Promise<Response>\n}\n\nexport const PLUGIN_CATALOG_FEED = definePluginServiceContract<PluginCatalogFeed>(\n  'core.catalog-feed',\n  { multiple: false },\n)\n\n/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */\nexport function registerPluginCatalogFeed(\n  feed: PluginCatalogFeed,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_CATALOG_FEED, feed, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */\nexport function pluginCatalogFeed(): PluginCatalogFeed | undefined {\n  return resolvePluginServices(PLUGIN_CATALOG_FEED)[0]?.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PRODUCT_CATALOG","multiple","registerPluginProductCatalog","catalog","options","pluginId","pluginProductCatalog","impl","PLUGIN_CATALOG_FEED","registerPluginCatalogFeed","feed","pluginCatalogFeed"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAgK1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED,4EAA4E,GAC5E,OAAO,SAASC,6BACdC,OAA6B,EAC7BC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,SAAS,aACjDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,iEAAiE,GACjE,OAAO,SAASC;QACPP;IAAP,QAAOA,0BAAAA,sBAAsBC,uBAAuB,CAAC,EAAE,qBAAhDD,wBAAkDQ,IAAI;AAC/D;AAuBA,OAAO,MAAMC,sBAAsBX,4BACjC,qBACA;IAAEI,UAAU;AAAM,GACnB;AAED,uFAAuF,GACvF,OAAO,SAASQ,0BACdC,IAAuB,EACvBN,OAA+B;IAE/BN,sBAAsBU,qBAAqBE,MAAM,aAC3CN,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,kFAAkF,GAClF,OAAO,SAASM;QACPZ;IAAP,QAAOA,0BAAAA,sBAAsBS,oBAAoB,CAAC,EAAE,qBAA7CT,wBAA+CQ,IAAI;AAC5D"}

package/src/lib/plugin-manager/plugin-product-writer.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @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.
+ */
+/**
+ * Products that come from somewhere else, written by a plugin that does not
+ * keep the store's products (AGL-3641).
+ *
+ * A print-on-demand service, a dropshipping supplier and a fulfillment
+ * network each hold a catalog of their own, and a merchant who sells it wants
+ * those products in their store without typing them in again — then kept in
+ * step as the source changes what it offers. The plugin that keeps the
+ * products answers here, so the plugin that reads the source never learns
+ * how products are stored, how their addresses are chosen, how the plan's
+ * product allowance is counted or what the store's search keys are. Every
+ * write keeps the owner's own rules: a create counts against the allowance in
+ * the transaction that makes it, and an edit leaves an entry in the site's
+ * activity like any other.
+ *
+ * ## Variants by the caller's key
+ *
+ * The caller names every configuration by its own stable key — the source's
+ * variant id — and the owner answers with its own variant id for each, so an
+ * order line can later be traced back to what the source sells. On an
+ * update the caller passes back the variant ids it was given; a key with no
+ * id is a new configuration, and an existing variant whose id is not passed
+ * is one the source no longer offers, removed.
+ *
+ * ## Money is integer minor units in the store's currency
+ *
+ * `priceMinor` is an integer (cents for USD) in the currency the store sells
+ * in, the `currency` the store's catalog (`core.product-catalog`) names. The
+ * caller converts nothing: a source priced in another currency is the
+ * caller's to refuse.
+ *
+ * ## What an update leaves alone
+ *
+ * The merchant edits an imported product like any other. An update rewrites
+ * only what the caller names: prices when `prices` is set, the description
+ * and photos when `content` is set, and always the configurations and their
+ * availability, because those are what an order can be filled from.
+ *
+ * ## One owner
+ *
+ * A slot, like the catalog: a site's products have one keeper, so a second
+ * plugin's registration is refused and the incumbent keeps serving. No owner
+ * registered is an ordinary answer — {@link pluginProductWriter} returns
+ * `undefined` and a caller imports nothing.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-product-writer`); it is not in the
+ * barrel.
+ */
+/** One axis of variation, e.g. `{ name: 'Size', values: ['S', 'M', 'L'] }`. */
+export interface SourcedProductOption {
+    name: string;
+    values: string[];
+}
+/** One sellable configuration, as the source offers it. */
+export interface SourcedProductVariant {
+    /** The source's own stable id for it. */
+    key: string;
+    /** The owner's id, when an earlier write returned one. */
+    variantId?: string;
+    /** Choices by option name; `{}` for a product with one configuration. */
+    options: Record<string, string>;
+    sku?: string;
+    /** What the shopper pays, integer minor units in the store's currency. */
+    priceMinor: number;
+    weightGrams?: number;
+    /** A photo the owner already holds (a media-library URL) for this choice. */
+    imageUrl?: string;
+    /**
+     * Whether the source can make or ship it now. An unavailable variant is
+     * kept, sold out, so a product page does not lose a choice for a day's
+     * shortage; a variant the source dropped is not passed at all.
+     */
+    available: boolean;
+}
+/** A product as the source offers it. */
+export interface SourcedProduct {
+    /** The source's stable key for the product, e.g. `printful:123`. */
+    sourceKey: string;
+    name: string;
+    /** Plain text or simple HTML, as the source wrote it. */
+    description?: string;
+    /** Photos the owner already holds (media-library URLs), first is primary. */
+    mediaUrls: string[];
+    tags?: string[];
+    options: SourcedProductOption[];
+    variants: SourcedProductVariant[];
+}
+export interface SourcedProductWrite {
+    hostId: string;
+    product: SourcedProduct;
+    /** The owner's product id, when an earlier write returned one. */
+    productId?: string;
+    /** A new product is born a draft unless the caller says to list it. */
+    status?: 'draft' | 'active';
+    /** On an update: rewrite prices from the source. */
+    prices?: boolean;
+    /** On an update: rewrite the name, description and photos from the source. */
+    content?: boolean;
+    /**
+     * Whether a `productId` the store no longer has (the merchant deleted it)
+     * is made again. Default true; a background re-sync passes false and is
+     * answered `missing`, so a product the merchant deleted stays deleted.
+     */
+    recreate?: boolean;
+    /** The member the write is made for, for the site's activity. */
+    actorUid?: string;
+}
+export type SourcedProductWriteOutcome = {
+    outcome: 'created' | 'updated' | 'unchanged';
+    productId: string;
+    /** Every variant passed, with the owner's id for it. */
+    variants: Array<{
+        key: string;
+        variantId: string;
+    }>;
+}
+/** The plan's product allowance is used up; nothing was written. */
+ | {
+    outcome: 'plan_limit';
+    limit: number;
+}
+/** The owner's rules refused the product; nothing was written. */
+ | {
+    outcome: 'invalid';
+    message: string;
+}
+/** The site does not sell. */
+ | {
+    outcome: 'no_store';
+}
+/** `productId` is gone and `recreate` was false; nothing was written. */
+ | {
+    outcome: 'missing';
+};
+export interface PluginProductWriter {
+    /**
+     * Creates the product, or updates the one `productId` names. A `productId`
+     * the store no longer has (the merchant deleted it) creates a new one,
+     * unless `recreate` is false.
+     */
+    upsertSourced(write: SourcedProductWrite): Promise<SourcedProductWriteOutcome>;
+}
+export declare const PLUGIN_PRODUCT_WRITER: import("./plugin-services").PluginServiceContract<PluginProductWriter>;
+/** Registers the products' keeper. A second plugin's is refused, naming both. */
+export declare function registerPluginProductWriter(writer: PluginProductWriter, options?: {
+    pluginId?: string;
+}): void;
+/** The registered keeper, or `undefined` when no plugin keeps products. */
+export declare function pluginProductWriter(): PluginProductWriter | undefined;

package/src/lib/plugin-manager/plugin-product-writer.js

@@ -0,0 +1,31 @@
+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";
+export const PLUGIN_PRODUCT_WRITER = definePluginServiceContract('core.product-writer', {
+    multiple: false
+});
+/** Registers the products' keeper. A second plugin's is refused, naming both. */ export function registerPluginProductWriter(writer, options) {
+    registerPluginService(PLUGIN_PRODUCT_WRITER, writer, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered keeper, or `undefined` when no plugin keeps products. */ export function pluginProductWriter() {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(PLUGIN_PRODUCT_WRITER)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+
+//# sourceMappingURL=plugin-product-writer.js.map

package/src/lib/plugin-manager/plugin-product-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-product-writer.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 * Products that come from somewhere else, written by a plugin that does not\n * keep the store's products (AGL-3641).\n *\n * A print-on-demand service, a dropshipping supplier and a fulfillment\n * network each hold a catalog of their own, and a merchant who sells it wants\n * those products in their store without typing them in again — then kept in\n * step as the source changes what it offers. The plugin that keeps the\n * products answers here, so the plugin that reads the source never learns\n * how products are stored, how their addresses are chosen, how the plan's\n * product allowance is counted or what the store's search keys are. Every\n * write keeps the owner's own rules: a create counts against the allowance in\n * the transaction that makes it, and an edit leaves an entry in the site's\n * activity like any other.\n *\n * ## Variants by the caller's key\n *\n * The caller names every configuration by its own stable key — the source's\n * variant id — and the owner answers with its own variant id for each, so an\n * order line can later be traced back to what the source sells. On an\n * update the caller passes back the variant ids it was given; a key with no\n * id is a new configuration, and an existing variant whose id is not passed\n * is one the source no longer offers, removed.\n *\n * ## Money is integer minor units in the store's currency\n *\n * `priceMinor` is an integer (cents for USD) in the currency the store sells\n * in, the `currency` the store's catalog (`core.product-catalog`) names. The\n * caller converts nothing: a source priced in another currency is the\n * caller's to refuse.\n *\n * ## What an update leaves alone\n *\n * The merchant edits an imported product like any other. An update rewrites\n * only what the caller names: prices when `prices` is set, the description\n * and photos when `content` is set, and always the configurations and their\n * availability, because those are what an order can be filled from.\n *\n * ## One owner\n *\n * A slot, like the catalog: a site's products have one keeper, so a second\n * plugin's registration is refused and the incumbent keeps serving. No owner\n * registered is an ordinary answer — {@link pluginProductWriter} returns\n * `undefined` and a caller imports nothing.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-product-writer`); it is not in the\n * barrel.\n */\n\n/** One axis of variation, e.g. `{ name: 'Size', values: ['S', 'M', 'L'] }`. */\nexport interface SourcedProductOption {\n  name: string\n  values: string[]\n}\n\n/** One sellable configuration, as the source offers it. */\nexport interface SourcedProductVariant {\n  /** The source's own stable id for it. */\n  key: string\n  /** The owner's id, when an earlier write returned one. */\n  variantId?: string\n  /** Choices by option name; `{}` for a product with one configuration. */\n  options: Record<string, string>\n  sku?: string\n  /** What the shopper pays, integer minor units in the store's currency. */\n  priceMinor: number\n  weightGrams?: number\n  /** A photo the owner already holds (a media-library URL) for this choice. */\n  imageUrl?: string\n  /**\n   * Whether the source can make or ship it now. An unavailable variant is\n   * kept, sold out, so a product page does not lose a choice for a day's\n   * shortage; a variant the source dropped is not passed at all.\n   */\n  available: boolean\n}\n\n/** A product as the source offers it. */\nexport interface SourcedProduct {\n  /** The source's stable key for the product, e.g. `printful:123`. */\n  sourceKey: string\n  name: string\n  /** Plain text or simple HTML, as the source wrote it. */\n  description?: string\n  /** Photos the owner already holds (media-library URLs), first is primary. */\n  mediaUrls: string[]\n  tags?: string[]\n  options: SourcedProductOption[]\n  variants: SourcedProductVariant[]\n}\n\nexport interface SourcedProductWrite {\n  hostId: string\n  product: SourcedProduct\n  /** The owner's product id, when an earlier write returned one. */\n  productId?: string\n  /** A new product is born a draft unless the caller says to list it. */\n  status?: 'draft' | 'active'\n  /** On an update: rewrite prices from the source. */\n  prices?: boolean\n  /** On an update: rewrite the name, description and photos from the source. */\n  content?: boolean\n  /**\n   * Whether a `productId` the store no longer has (the merchant deleted it)\n   * is made again. Default true; a background re-sync passes false and is\n   * answered `missing`, so a product the merchant deleted stays deleted.\n   */\n  recreate?: boolean\n  /** The member the write is made for, for the site's activity. */\n  actorUid?: string\n}\n\nexport type SourcedProductWriteOutcome =\n  | {\n      outcome: 'created' | 'updated' | 'unchanged'\n      productId: string\n      /** Every variant passed, with the owner's id for it. */\n      variants: Array<{ key: string; variantId: string }>\n    }\n  /** The plan's product allowance is used up; nothing was written. */\n  | { outcome: 'plan_limit'; limit: number }\n  /** The owner's rules refused the product; nothing was written. */\n  | { outcome: 'invalid'; message: string }\n  /** The site does not sell. */\n  | { outcome: 'no_store' }\n  /** `productId` is gone and `recreate` was false; nothing was written. */\n  | { outcome: 'missing' }\n\nexport interface PluginProductWriter {\n  /**\n   * Creates the product, or updates the one `productId` names. A `productId`\n   * the store no longer has (the merchant deleted it) creates a new one,\n   * unless `recreate` is false.\n   */\n  upsertSourced(write: SourcedProductWrite): Promise<SourcedProductWriteOutcome>\n}\n\nexport const PLUGIN_PRODUCT_WRITER = definePluginServiceContract<PluginProductWriter>(\n  'core.product-writer',\n  { multiple: false },\n)\n\n/** Registers the products' keeper. A second plugin's is refused, naming both. */\nexport function registerPluginProductWriter(\n  writer: PluginProductWriter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PRODUCT_WRITER, writer, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered keeper, or `undefined` when no plugin keeps products. */\nexport function pluginProductWriter(): PluginProductWriter | undefined {\n  return resolvePluginServices(PLUGIN_PRODUCT_WRITER)[0]?.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PRODUCT_WRITER","multiple","registerPluginProductWriter","writer","options","pluginId","pluginProductWriter","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA4I1B,OAAO,MAAMC,wBAAwBH,4BACnC,uBACA;IAAEI,UAAU;AAAM,GACnB;AAED,+EAA+E,GAC/E,OAAO,SAASC,4BACdC,MAA2B,EAC3BC,OAA+B;IAE/BN,sBAAsBE,uBAAuBG,QAAQ,aAC/CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yEAAyE,GACzE,OAAO,SAASC;QACPP;IAAP,QAAOA,0BAAAA,sBAAsBC,sBAAsB,CAAC,EAAE,qBAA/CD,wBAAiDQ,IAAI;AAC9D"}

package/src/lib/plugin-manager/plugin-theme-presets.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 type { ConsoleThemePreset } from './feature-plugins';
+/**
+ * The built-in themes as the console's SERVER reads them (AGL-3660).
+ *
+ * The theme picker lists presets from the console extensions the theme page
+ * loads, which never run in an API process. A server job that starts a site
+ * from one of them — the AI site start picks a base theme and layers the
+ * site's own look over it as an override, exactly as a person's pick and
+ * edits are stored (`theme-library.ts`) — reads the same presets here, each
+ * plugin registering its list from its server declarations.
+ */
+export interface PluginThemePresets {
+    presets: readonly ConsoleThemePreset[];
+}
+export declare const PLUGIN_THEME_PRESETS: import("./plugin-services").PluginServiceContract<PluginThemePresets>;
+/** Registers a plugin's built-in themes for server readers. */
+export declare function registerPluginThemePresets(presets: readonly ConsoleThemePreset[], options: {
+    pluginId: string;
+}): void;
+/**
+ * Every built-in theme the server has registered, in registration order, the
+ * first preset under an id winning, as the picker lists them.
+ */
+export declare function listServerThemePresets(): ConsoleThemePreset[];