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

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

@@ -0,0 +1,209 @@
+/**
+ * @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.
+ */
+/**
+ * A site's sellable catalog, read whole and in pages by a plugin that does
+ * not own it (AGL-3637).
+ *
+ * A product feed, a marketplace listing sync and an ad catalog all need the
+ * same thing: every offer a store sells, with the facts a shopping channel
+ * asks for — price in the store's currency, stock, photos, identifiers,
+ * shipping. The plugin that keeps the products answers it here, so a reader
+ * never learns where products are stored, how variants are modeled or what a
+ * deleted product looks like.
+ *
+ * ## One OFFER per sellable configuration
+ *
+ * A product with one configuration is one offer whose `id` is the product's
+ * own id. A product with several (sizes, colors) is one offer per
+ * configuration, each with its own `id` and the product's id as `groupId`,
+ * which is what every shopping channel calls the variant group.
+ *
+ * ## Money is integer minor units in the store's currency
+ *
+ * `priceMinor` and every other amount are integers (cents for USD) in
+ * {@link CatalogStore.currency}. A reader formats them; it never assumes a
+ * currency.
+ *
+ * ## Pages, not a list
+ *
+ * A store may hold far more products than one read should load, so the
+ * catalog is walked in pages: `page()` answers up to about `limit` offers and
+ * a `nextCursor` to continue from, `null` on the last page. A cursor is the
+ * owner's own opaque string; a reader passes it back untouched.
+ *
+ * ## One owner
+ *
+ * A slot, like the tax profile: a site has one catalog, so a second plugin's
+ * registration is refused and the incumbent keeps serving. No owner
+ * registered is an ordinary answer — {@link pluginProductCatalog} returns
+ * `undefined` and a reader serves nothing.
+ */
+/** The store an offer belongs to, as a channel needs it. */
+export interface CatalogStore {
+    hostId: string;
+    /** The store's name, as its site calls itself. */
+    name: string;
+    /**
+     * The origin the store's pages are served on (`https://shop.example.com`),
+     * or `null` when the site has no address yet.
+     */
+    origin: string | null;
+    /** ISO 4217, upper case. Every amount in the catalog is in it. */
+    currency: string;
+    /**
+     * Whether `/products/{slug}` pages are served. When `false`, every offer's
+     * `path` answers 404, and a channel will refuse the offers.
+     */
+    productPagesServed: boolean;
+    /**
+     * Countries the store's checkout prices shipping to by a live carrier
+     * quote rather than its own table (ISO 3166-1 alpha-2, upper case). An
+     * offer carries no {@link CatalogShippingPrice} for them, because the price
+     * depends on the address; a channel that calculates carrier rates itself
+     * prices them from the offer's weight and dimensions.
+     */
+    carrierPricedCountries: string[];
+}
+export type CatalogAvailability = 'in_stock' | 'out_of_stock' | 'backorder';
+export type CatalogCondition = 'new' | 'refurbished' | 'used';
+export type CatalogProductKind = 'physical' | 'digital' | 'service';
+/** What one offer costs to ship to one country, cheapest rate first chosen. */
+export interface CatalogShippingPrice {
+    /** ISO 3166-1 alpha-2, upper case. */
+    country: string;
+    /** The rate's name as the shopper sees it at checkout. */
+    service: string;
+    priceMinor: number;
+}
+/** One sellable configuration of a product. */
+export interface CatalogOffer {
+    /** Stable, unique within the store: the product id, or product and variant. */
+    id: string;
+    /** The product's id: the variant group every configuration shares. */
+    groupId: string;
+    /** Whether the product has more than one configuration. */
+    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`. */
+    title: string;
+    /** Plain text: no markup. May be empty. */
+    description: string;
+    /** Site-relative path of the product page, e.g. `/products/tee`. */
+    path: string;
+    /** Absolute URL of the photo shown for this configuration. */
+    imageUrl?: string;
+    /** Absolute URLs of the product's other photos, in order. */
+    additionalImageUrls: string[];
+    /** What the shopper pays, before any sale: the regular price. */
+    priceMinor: number;
+    /** A lower price the offer is on sale for now; absent when not on sale. */
+    salePriceMinor?: number;
+    availability: CatalogAvailability;
+    /** Units in stock, or `null` when stock is not tracked. */
+    quantity: number | null;
+    kind: CatalogProductKind;
+    /** Whether the product is sold only as a recurring subscription. */
+    subscriptionOnly: boolean;
+    /** What the merchant entered for shopping channels; absent when they did not. */
+    condition?: CatalogCondition;
+    brand?: string;
+    /** GTIN (UPC, EAN, ISBN, JAN, ITF-14) as entered, digits only. */
+    gtin?: string;
+    mpn?: string;
+    /** A Google product taxonomy id or full path, as entered. */
+    googleProductCategory?: string;
+    /** The store's own category path, e.g. `Apparel > Shirts`. */
+    productType?: string;
+    /** The configuration's choices, by option name. */
+    options: Readonly<Record<string, string>>;
+    /** The choice of an option named like a color, when there is one. */
+    color?: string;
+    /** The choice of an option named like a size, when there is one. */
+    size?: string;
+    weightGrams?: number;
+    /** One unit's packed size, in centimeters, when the merchant entered it. */
+    dimensionsCm?: {
+        length: number;
+        width: number;
+        height: number;
+    };
+    /** What it costs to ship one unit, per country the store ships to. */
+    shipping: CatalogShippingPrice[];
+    /** When the product last changed, epoch ms; absent when unknown. */
+    updatedAtMs?: number;
+}
+export interface CatalogPage {
+    offers: CatalogOffer[];
+    /** Where the next page starts, or `null` when this is the last one. */
+    nextCursor: string | null;
+}
+export interface PluginProductCatalog {
+    /** The store, or `null` for a site that does not sell. */
+    store(hostId: string): Promise<CatalogStore | null>;
+    /**
+     * One page of the store's live, listed offers: never a draft, archived or
+     * deleted product. About `limit` offers — a product's configurations are
+     * never split across pages, so a page may run over by one product's worth.
+     */
+    page(request: {
+        hostId: string;
+        cursor?: string | null;
+        limit: number;
+    }): Promise<CatalogPage>;
+}
+export declare const PLUGIN_PRODUCT_CATALOG: import("./plugin-services").PluginServiceContract<PluginProductCatalog>;
+/** Registers the store catalog. A second plugin's is refused, naming both. */
+export declare function registerPluginProductCatalog(catalog: PluginProductCatalog, options?: {
+    pluginId?: string;
+}): void;
+/** The registered catalog, or `undefined` when no plugin sells. */
+export declare function pluginProductCatalog(): PluginProductCatalog | undefined;
+/**
+ * The plugin that publishes the catalog to shopping channels, as the
+ * catalog's owner hands it an address of its own (AGL-3637).
+ *
+ * Before any plugin published feeds, the plugin that keeps the products
+ * served one feed itself, and merchants pasted that address into their
+ * channel. The address stays the owner's — a request for it reaches the
+ * owner's routes — but the feed is written by whoever publishes the catalog
+ * now, so the owner answers it from here. Nobody registered is an ordinary
+ * answer: {@link pluginCatalogFeed} returns `undefined` and the owner
+ * answers 404.
+ */
+export interface PluginCatalogFeed {
+    /**
+     * Answers a request for the owner's pre-existing feed address for the site
+     * `hostId`: the feed, a 404 when the site's publisher has retired the
+     * address or does not publish, or a 503 to try later.
+     */
+    serveLegacyFeed(request: Request, hostId: string): Promise<Response>;
+}
+export declare const PLUGIN_CATALOG_FEED: import("./plugin-services").PluginServiceContract<PluginCatalogFeed>;
+/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */
+export declare function registerPluginCatalogFeed(feed: PluginCatalogFeed, options?: {
+    pluginId?: string;
+}): void;
+/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */
+export declare function pluginCatalogFeed(): PluginCatalogFeed | undefined;

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

@@ -0,0 +1,43 @@
+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_CATALOG = definePluginServiceContract('core.product-catalog', {
+    multiple: false
+});
+/** Registers the store catalog. A second plugin's is refused, naming both. */ export function registerPluginProductCatalog(catalog, options) {
+    registerPluginService(PLUGIN_PRODUCT_CATALOG, catalog, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered catalog, or `undefined` when no plugin sells. */ export function pluginProductCatalog() {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(PLUGIN_PRODUCT_CATALOG)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+export const PLUGIN_CATALOG_FEED = definePluginServiceContract('core.catalog-feed', {
+    multiple: false
+});
+/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */ export function registerPluginCatalogFeed(feed, options) {
+    registerPluginService(PLUGIN_CATALOG_FEED, feed, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */ export function pluginCatalogFeed() {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(PLUGIN_CATALOG_FEED)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+
+//# sourceMappingURL=plugin-product-catalog.js.map

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

@@ -0,0 +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  /**\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"}