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

package/src/lib/plugin-manager/plugin-shipment-records.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @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 { PluginShippingAddress } from './plugin-shipping-rates';
+/**
+ * What was sold and shipped, kept by the plugin that sold it (AGL-3612).
+ *
+ * A plugin that buys a carrier label needs three things from the seller of
+ * the goods, and must not read the seller's documents for any of them: what
+ * a record holds that still has to ship (lines, weights, the address), a way
+ * to write a shipment back onto it once the label exists, and a way to tell
+ * it what the carrier says has happened since. The seller registers
+ * {@link PluginShipmentRecords}; the label buyer asks it. The seller's own
+ * transition rules, its timeline and the emails its customers get all stay
+ * inside the seller's write, so a label bought here and a parcel shipped by
+ * hand land the same way.
+ *
+ * The words are a seller's and a carrier's, never one catalog's: a record is
+ * anything with lines that ship — an order, a rental, a subscription box.
+ *
+ * ## Shipments announced
+ *
+ * A seller also announces each shipment it records, however it was recorded
+ * — a label bought here, or a carrier and number typed by hand — so a plugin
+ * that follows parcels can start following that one. Listeners run after the
+ * write; one that throws is logged and never undoes it.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-shipment-records`); it is not in the
+ * barrel.
+ */
+/** One line of a record, as a shipper needs it. */
+export interface PluginShipmentLine {
+    /** The line's position on the record: the id a write names it by. */
+    lineIndex: number;
+    name: string;
+    sku?: string;
+    quantity: number;
+    /** Units of the line not yet on any shipment. */
+    quantityUnshipped: number;
+    /** Per unit, in the record's currency. */
+    unitValueCents: number;
+    /** Per unit; absent when the seller does not know it. */
+    weightGrams?: number;
+    lengthCm?: number;
+    widthCm?: number;
+    heightCm?: number;
+    /** Harmonized System code, for customs. */
+    hsCode?: string;
+    /** ISO-3166 alpha-2 country the goods were made in, for customs. */
+    originCountry?: string;
+}
+/** A shipment already on the record. */
+export interface PluginRecordedShipment {
+    id: string;
+    carrier?: string;
+    trackingNumber?: string;
+    trackingUrl?: string;
+    /** The label it was shipped under, when a label buyer wrote it. */
+    labelRef?: string;
+    lineIndexes: number[];
+    atMs: number;
+}
+/** A record with lines that ship. */
+export interface PluginShippableRecord {
+    hostId: string;
+    recordId: string;
+    /** What a person calls it: `#1042`. */
+    displayRef: string;
+    /** The seller's own status word, shown as is. */
+    status: string;
+    /** Whether the seller would accept a shipment on it now. */
+    shippable: boolean;
+    /** ISO-4217, lower case. */
+    currency: string;
+    shipTo?: PluginShippingAddress;
+    customerEmail?: string;
+    lines: PluginShipmentLine[];
+    shipments: PluginRecordedShipment[];
+    /** The rate the customer chose at checkout, when it was a carrier's. */
+    chosenService?: {
+        serviceKey?: string;
+        label?: string;
+        amountCents?: number;
+    };
+    createdAtMs?: number;
+    /**
+     * Whether the record was paid in a payment provider's test mode (AGL-3634):
+     * no money moved, so nothing real may be sent for it. Absent when the
+     * seller does not know, which reads as live.
+     */
+    testMode?: boolean;
+}
+/** A shipment to write. */
+export interface PluginShipmentWrite {
+    hostId: string;
+    recordId: string;
+    /** What is in the parcel; absent means every unit not yet shipped. */
+    lines?: Array<{
+        lineIndex: number;
+        quantity: number;
+    }>;
+    carrier: string;
+    trackingNumber: string;
+    trackingUrl?: string;
+    /** The label's file, an https URL the seller may show beside the shipment. */
+    labelUrl?: string;
+    labelRef?: string;
+    /** The member who bought the label, for the record's timeline. */
+    actorUid?: string;
+}
+/**
+ * What a write did. `already` is a success: the same label was written
+ * before, so a retry cannot add a second shipment.
+ */
+export type PluginShipmentWriteOutcome = {
+    outcome: 'recorded';
+    shipmentId: string;
+} | {
+    outcome: 'already';
+    shipmentId?: string;
+} | {
+    outcome: 'no_such_record';
+}
+/** The seller's rules refused; `from` is the status that refused. */
+ | {
+    outcome: 'blocked';
+    from: string;
+    reason?: string;
+};
+/** Where a parcel is, in a carrier-neutral word. */
+export type PluginTrackingStatus = 'pre_transit' | 'in_transit' | 'out_for_delivery' | 'delivered' | 'exception' | 'returned';
+export declare const PLUGIN_TRACKING_STATUSES: readonly PluginTrackingStatus[];
+/** What a carrier says happened to one parcel. */
+export interface PluginTrackingUpdate {
+    hostId: string;
+    recordId: string;
+    trackingNumber: string;
+    status: PluginTrackingStatus;
+    /** The carrier's own words for the event. */
+    detail?: string;
+    atMs: number;
+}
+export type PluginTrackingOutcome = {
+    outcome: 'recorded';
+}
+/** The record already says this, so nothing was written. */
+ | {
+    outcome: 'unchanged';
+} | {
+    outcome: 'no_such_record';
+} | {
+    outcome: 'no_such_shipment';
+};
+/** A place a site ships from. */
+export interface PluginShipFromAddress {
+    id: string;
+    name: string;
+    address: PluginShippingAddress;
+}
+export interface PluginShipmentRecords {
+    /** One record, or `null` when the site has none by that id. */
+    read(hostId: string, recordId: string): Promise<PluginShippableRecord | null>;
+    /** Writes a shipment under the seller's own rules, once per label. */
+    recordShipment(write: PluginShipmentWrite): Promise<PluginShipmentWriteOutcome>;
+    /** Records what the carrier says; `delivered` moves the record on as the seller does. */
+    recordTracking(update: PluginTrackingUpdate): Promise<PluginTrackingOutcome>;
+    /** The addresses the site keeps for where it ships from. */
+    shipFromAddresses(hostId: string): Promise<PluginShipFromAddress[]>;
+}
+export declare const PLUGIN_SHIPMENT_RECORDS: import("./plugin-services").PluginServiceContract<PluginShipmentRecords>;
+/** Registers the seller. A second plugin is refused naming both. */
+export declare function registerPluginShipmentRecords(records: PluginShipmentRecords, options?: {
+    pluginId?: string;
+}): void;
+/** The seller, or `null` when no plugin registered one. */
+export declare function pluginShipmentRecords(): PluginShipmentRecords | null;
+/** A shipment a seller recorded, by any door. */
+export interface PluginShipmentAnnouncement {
+    hostId: string;
+    recordId: string;
+    shipmentId: string;
+    carrier?: string;
+    trackingNumber?: string;
+    /** Present when a label buyer wrote it; a listener that bought it already follows it. */
+    labelRef?: string;
+}
+export type PluginShipmentListener = (announcement: PluginShipmentAnnouncement) => void | Promise<void>;
+/** Joins the listeners. Re-registering under the same plugin replaces its own. */
+export declare function registerPluginShipmentListener(listener: PluginShipmentListener, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * Tells every listener about a shipment the seller recorded. Awaited, each
+ * isolated: a listener that throws is logged and the rest still hear it.
+ */
+export declare function announcePluginShipment(announcement: PluginShipmentAnnouncement): Promise<void>;

package/src/lib/plugin-manager/plugin-shipment-records.js

@@ -0,0 +1,63 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_TRACKING_STATUSES = [
+    'pre_transit',
+    'in_transit',
+    'out_for_delivery',
+    'delivered',
+    'exception',
+    'returned'
+];
+export const PLUGIN_SHIPMENT_RECORDS = definePluginServiceContract('core.shipment-records', {
+    multiple: false
+});
+/** Registers the seller. A second plugin is refused naming both. */ export function registerPluginShipmentRecords(records, options) {
+    registerPluginService(PLUGIN_SHIPMENT_RECORDS, records, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The seller, or `null` when no plugin registered one. */ export function pluginShipmentRecords() {
+    var _ref;
+    var _resolvePluginServices_;
+    return (_ref = (_resolvePluginServices_ = resolvePluginServices(PLUGIN_SHIPMENT_RECORDS)[0]) == null ? void 0 : _resolvePluginServices_.impl) != null ? _ref : null;
+}
+const PLUGIN_SHIPMENT_LISTENERS = definePluginServiceContract('core.shipment-listeners', {
+    multiple: true
+});
+/** Joins the listeners. Re-registering under the same plugin replaces its own. */ export function registerPluginShipmentListener(listener, options) {
+    var _getRegisteringPluginId;
+    const pluginId = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId;
+    registerPluginService(PLUGIN_SHIPMENT_LISTENERS, listener, _extends({}, pluginId ? {
+        pluginId
+    } : {}));
+}
+/**
+ * Tells every listener about a shipment the seller recorded. Awaited, each
+ * isolated: a listener that throws is logged and the rest still hear it.
+ */ export async function announcePluginShipment(announcement) {
+    for (const entry of resolvePluginServices(PLUGIN_SHIPMENT_LISTENERS)){
+        try {
+            await entry.impl(announcement);
+        } catch (error) {
+            console.error(`[shipments] listener "${entry.pluginId}" failed for ${announcement.hostId}/${announcement.recordId}`, error);
+        }
+    }
+}
+
+//# sourceMappingURL=plugin-shipment-records.js.map

package/src/lib/plugin-manager/plugin-shipment-records.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-shipment-records.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 { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport type { PluginShippingAddress } from './plugin-shipping-rates'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * What was sold and shipped, kept by the plugin that sold it (AGL-3612).\n *\n * A plugin that buys a carrier label needs three things from the seller of\n * the goods, and must not read the seller's documents for any of them: what\n * a record holds that still has to ship (lines, weights, the address), a way\n * to write a shipment back onto it once the label exists, and a way to tell\n * it what the carrier says has happened since. The seller registers\n * {@link PluginShipmentRecords}; the label buyer asks it. The seller's own\n * transition rules, its timeline and the emails its customers get all stay\n * inside the seller's write, so a label bought here and a parcel shipped by\n * hand land the same way.\n *\n * The words are a seller's and a carrier's, never one catalog's: a record is\n * anything with lines that ship — an order, a rental, a subscription box.\n *\n * ## Shipments announced\n *\n * A seller also announces each shipment it records, however it was recorded\n * — a label bought here, or a carrier and number typed by hand — so a plugin\n * that follows parcels can start following that one. Listeners run after the\n * write; one that throws is logged and never undoes it.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-shipment-records`); it is not in the\n * barrel.\n */\n\n/** One line of a record, as a shipper needs it. */\nexport interface PluginShipmentLine {\n  /** The line's position on the record: the id a write names it by. */\n  lineIndex: number\n  name: string\n  sku?: string\n  quantity: number\n  /** Units of the line not yet on any shipment. */\n  quantityUnshipped: number\n  /** Per unit, in the record's currency. */\n  unitValueCents: number\n  /** Per unit; absent when the seller does not know it. */\n  weightGrams?: number\n  lengthCm?: number\n  widthCm?: number\n  heightCm?: number\n  /** Harmonized System code, for customs. */\n  hsCode?: string\n  /** ISO-3166 alpha-2 country the goods were made in, for customs. */\n  originCountry?: string\n}\n\n/** A shipment already on the record. */\nexport interface PluginRecordedShipment {\n  id: string\n  carrier?: string\n  trackingNumber?: string\n  trackingUrl?: string\n  /** The label it was shipped under, when a label buyer wrote it. */\n  labelRef?: string\n  lineIndexes: number[]\n  atMs: number\n}\n\n/** A record with lines that ship. */\nexport interface PluginShippableRecord {\n  hostId: string\n  recordId: string\n  /** What a person calls it: `#1042`. */\n  displayRef: string\n  /** The seller's own status word, shown as is. */\n  status: string\n  /** Whether the seller would accept a shipment on it now. */\n  shippable: boolean\n  /** ISO-4217, lower case. */\n  currency: string\n  shipTo?: PluginShippingAddress\n  customerEmail?: string\n  lines: PluginShipmentLine[]\n  shipments: PluginRecordedShipment[]\n  /** The rate the customer chose at checkout, when it was a carrier's. */\n  chosenService?: { serviceKey?: string; label?: string; amountCents?: number }\n  createdAtMs?: number\n  /**\n   * Whether the record was paid in a payment provider's test mode (AGL-3634):\n   * no money moved, so nothing real may be sent for it. Absent when the\n   * seller does not know, which reads as live.\n   */\n  testMode?: boolean\n}\n\n/** A shipment to write. */\nexport interface PluginShipmentWrite {\n  hostId: string\n  recordId: string\n  /** What is in the parcel; absent means every unit not yet shipped. */\n  lines?: Array<{ lineIndex: number; quantity: number }>\n  carrier: string\n  trackingNumber: string\n  trackingUrl?: string\n  /** The label's file, an https URL the seller may show beside the shipment. */\n  labelUrl?: string\n  labelRef?: string\n  /** The member who bought the label, for the record's timeline. */\n  actorUid?: string\n}\n\n/**\n * What a write did. `already` is a success: the same label was written\n * before, so a retry cannot add a second shipment.\n */\nexport type PluginShipmentWriteOutcome =\n  | { outcome: 'recorded'; shipmentId: string }\n  | { outcome: 'already'; shipmentId?: string }\n  | { outcome: 'no_such_record' }\n  /** The seller's rules refused; `from` is the status that refused. */\n  | { outcome: 'blocked'; from: string; reason?: string }\n\n/** Where a parcel is, in a carrier-neutral word. */\nexport type PluginTrackingStatus =\n  | 'pre_transit'\n  | 'in_transit'\n  | 'out_for_delivery'\n  | 'delivered'\n  | 'exception'\n  | 'returned'\n\nexport const PLUGIN_TRACKING_STATUSES: readonly PluginTrackingStatus[] = [\n  'pre_transit',\n  'in_transit',\n  'out_for_delivery',\n  'delivered',\n  'exception',\n  'returned',\n]\n\n/** What a carrier says happened to one parcel. */\nexport interface PluginTrackingUpdate {\n  hostId: string\n  recordId: string\n  trackingNumber: string\n  status: PluginTrackingStatus\n  /** The carrier's own words for the event. */\n  detail?: string\n  atMs: number\n}\n\nexport type PluginTrackingOutcome =\n  | { outcome: 'recorded' }\n  /** The record already says this, so nothing was written. */\n  | { outcome: 'unchanged' }\n  | { outcome: 'no_such_record' }\n  | { outcome: 'no_such_shipment' }\n\n/** A place a site ships from. */\nexport interface PluginShipFromAddress {\n  id: string\n  name: string\n  address: PluginShippingAddress\n}\n\nexport interface PluginShipmentRecords {\n  /** One record, or `null` when the site has none by that id. */\n  read(hostId: string, recordId: string): Promise<PluginShippableRecord | null>\n  /** Writes a shipment under the seller's own rules, once per label. */\n  recordShipment(write: PluginShipmentWrite): Promise<PluginShipmentWriteOutcome>\n  /** Records what the carrier says; `delivered` moves the record on as the seller does. */\n  recordTracking(update: PluginTrackingUpdate): Promise<PluginTrackingOutcome>\n  /** The addresses the site keeps for where it ships from. */\n  shipFromAddresses(hostId: string): Promise<PluginShipFromAddress[]>\n}\n\nexport const PLUGIN_SHIPMENT_RECORDS =\n  definePluginServiceContract<PluginShipmentRecords>('core.shipment-records', {\n    multiple: false,\n  })\n\n/** Registers the seller. A second plugin is refused naming both. */\nexport function registerPluginShipmentRecords(\n  records: PluginShipmentRecords,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_SHIPMENT_RECORDS, records, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The seller, or `null` when no plugin registered one. */\nexport function pluginShipmentRecords(): PluginShipmentRecords | null {\n  return resolvePluginServices(PLUGIN_SHIPMENT_RECORDS)[0]?.impl ?? null\n}\n\n/** A shipment a seller recorded, by any door. */\nexport interface PluginShipmentAnnouncement {\n  hostId: string\n  recordId: string\n  shipmentId: string\n  carrier?: string\n  trackingNumber?: string\n  /** Present when a label buyer wrote it; a listener that bought it already follows it. */\n  labelRef?: string\n}\n\nexport type PluginShipmentListener = (\n  announcement: PluginShipmentAnnouncement,\n) => void | Promise<void>\n\nconst PLUGIN_SHIPMENT_LISTENERS = definePluginServiceContract<PluginShipmentListener>(\n  'core.shipment-listeners',\n  { multiple: true },\n)\n\n/** Joins the listeners. Re-registering under the same plugin replaces its own. */\nexport function registerPluginShipmentListener(\n  listener: PluginShipmentListener,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = getRegisteringPluginId() ?? options?.pluginId\n  registerPluginService(PLUGIN_SHIPMENT_LISTENERS, listener, {\n    ...(pluginId ? { pluginId } : {}),\n  })\n}\n\n/**\n * Tells every listener about a shipment the seller recorded. Awaited, each\n * isolated: a listener that throws is logged and the rest still hear it.\n */\nexport async function announcePluginShipment(\n  announcement: PluginShipmentAnnouncement,\n): Promise<void> {\n  for (const entry of resolvePluginServices(PLUGIN_SHIPMENT_LISTENERS)) {\n    try {\n      await entry.impl(announcement)\n    } catch (error) {\n      console.error(\n        `[shipments] listener \"${entry.pluginId}\" failed for ${announcement.hostId}/${announcement.recordId}`,\n        error,\n      )\n    }\n  }\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_TRACKING_STATUSES","PLUGIN_SHIPMENT_RECORDS","multiple","registerPluginShipmentRecords","records","options","pluginId","pluginShipmentRecords","impl","PLUGIN_SHIPMENT_LISTENERS","registerPluginShipmentListener","listener","announcePluginShipment","announcement","entry","error","console","hostId","recordId"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AAExE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA+H1B,OAAO,MAAMC,2BAA4D;IACvE;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAsCD,OAAO,MAAMC,0BACXJ,4BAAmD,yBAAyB;IAC1EK,UAAU;AACZ,GAAE;AAEJ,kEAAkE,GAClE,OAAO,SAASC,8BACdC,OAA8B,EAC9BC,OAA+B;IAE/BP,sBAAsBG,yBAAyBG,SAAS,aAClDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yDAAyD,GACzD,OAAO,SAASC;;QACPR;IAAP,gBAAOA,0BAAAA,sBAAsBE,wBAAwB,CAAC,EAAE,qBAAjDF,wBAAmDS,IAAI,mBAAI;AACpE;AAiBA,MAAMC,4BAA4BZ,4BAChC,2BACA;IAAEK,UAAU;AAAK;AAGnB,gFAAgF,GAChF,OAAO,SAASQ,+BACdC,QAAgC,EAChCN,OAA+B;QAEdT;IAAjB,MAAMU,YAAWV,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASC,QAAQ;IAC9DR,sBAAsBW,2BAA2BE,UAAU,aACrDL,WAAW;QAAEA;IAAS,IAAI,CAAC;AAEnC;AAEA;;;CAGC,GACD,OAAO,eAAeM,uBACpBC,YAAwC;IAExC,KAAK,MAAMC,SAASf,sBAAsBU,2BAA4B;QACpE,IAAI;YACF,MAAMK,MAAMN,IAAI,CAACK;QACnB,EAAE,OAAOE,OAAO;YACdC,QAAQD,KAAK,CACX,CAAC,sBAAsB,EAAED,MAAMR,QAAQ,CAAC,aAAa,EAAEO,aAAaI,MAAM,CAAC,CAAC,EAAEJ,aAAaK,QAAQ,EAAE,EACrGH;QAEJ;IACF;AACF"}

package/src/lib/plugin-manager/plugin-shipping-rates.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @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.
+ */
+/**
+ * Live parcel rates, answered by the one plugin that talks to carriers
+ * (AGL-3612).
+ *
+ * A plugin that sells goods prices delivery from its own table until the
+ * merchant asks for live rates; then it needs a carrier's quote for an
+ * address and a parcel, and it must not learn which carrier network, which
+ * account or which vendor answers. A plugin that buys labels registers here;
+ * a plugin that sells asks here, and neither imports the other.
+ *
+ * ## The shape is a parcel and an address, nothing more
+ *
+ * Every type below is postal: where it goes, what it weighs, how big it is,
+ * and what it is worth for insurance and customs. Nothing names a catalog, an
+ * order or a store, so a booking plugin shipping a rental kit asks the same
+ * question in the same words.
+ *
+ * ## Nobody home is `null`, never a refusal
+ *
+ * Unlike the tax profile, an absent quoter is a perfectly good answer: the
+ * seller falls back to its own rates, which is what it did before anyone
+ * registered. {@link pluginShippingRateQuoter} answers `null`, and a quoter
+ * whose deployment is not configured answers `available() === false`, which
+ * a caller must read the same way.
+ *
+ * ## A quote is advisory until a label is bought
+ *
+ * `amountCents` is what the carrier quoted the platform for that parcel at
+ * that moment, BEFORE any markup or handling the seller adds. The seller
+ * decides what the shopper pays; the quoter never does.
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-shipping-rates`); it is not in the
+ * barrel.
+ */
+/** A postal address. `country` is ISO-3166 alpha-2; everything else is optional. */
+export interface PluginShippingAddress {
+    name?: string;
+    company?: string;
+    line1?: string;
+    line2?: string;
+    city?: string;
+    /** State, province or region code, as the destination writes it. */
+    state?: string;
+    postalCode?: string;
+    country: string;
+    phone?: string;
+    email?: string;
+    /** Whether the address is a home, when the caller knows; carriers price it. */
+    residential?: boolean;
+}
+/** One parcel. Metric throughout; an adapter converts to its vendor's units. */
+export interface PluginShippingParcel {
+    weightGrams: number;
+    lengthCm?: number;
+    widthCm?: number;
+    heightCm?: number;
+}
+/** What a seller asks: one shipment's rates to one address. */
+export interface PluginShippingQuoteRequest {
+    /** The site the shipment leaves from; the quoter resolves its ship-from address. */
+    hostId: string;
+    to: PluginShippingAddress;
+    parcels: PluginShippingParcel[];
+    /** ISO-4217, lower case, of the amounts the caller will charge in. */
+    currency: string;
+    /** The goods' value, for insurance and customs; 0 when unknown. */
+    valueCents: number;
+    /**
+     * Service keys the seller offers (`'usps:priority'`), as
+     * {@link PluginShippingRateQuoter.listServices} names them. Empty or
+     * absent means every service the quoter can price.
+     */
+    services?: string[];
+    /** Aborted when the caller stops waiting; a quoter passes it to its fetches. */
+    signal?: AbortSignal;
+}
+/** One carrier service's price for the shipment. */
+export interface PluginShippingQuote {
+    /** Stable across quotes: `carrier:service`, the key a seller stores. */
+    serviceKey: string;
+    carrier: string;
+    service: string;
+    /** What a shopper reads: `'USPS Priority Mail'`. */
+    label: string;
+    /** The carrier's price to the platform, before any markup or handling. */
+    amountCents: number;
+    currency: string;
+    /** Transit estimate in business days, when the carrier gives one. */
+    estimatedDays?: number;
+}
+/** A service a seller may choose to offer. */
+export interface PluginShippingService {
+    serviceKey: string;
+    carrier: string;
+    label: string;
+}
+/** What address validation answers. */
+export interface PluginShippingAddressCheck {
+    /** `valid` deliverable as written; `corrected` deliverable as `suggested`; `invalid` not deliverable. */
+    verdict: 'valid' | 'corrected' | 'invalid' | 'unknown';
+    /** The address the carrier would deliver to, when it differs. */
+    suggested?: PluginShippingAddress;
+    /** Why it is not deliverable, in the carrier's words. */
+    messages: string[];
+}
+export interface PluginShippingRateQuoter {
+    /** Whether quotes can be asked for this site now: configured and switched on. */
+    available(hostId: string): Promise<boolean>;
+    /**
+     * The rates. Throws on a provider failure; a caller that cannot wait
+     * aborts `signal` and falls back to its own rates.
+     */
+    quote(request: PluginShippingQuoteRequest): Promise<PluginShippingQuote[]>;
+    /** The services a seller can pick from for this site. */
+    listServices(hostId: string): Promise<PluginShippingService[]>;
+    /** Whether an address is deliverable, and the carrier's correction. */
+    validateAddress?(hostId: string, address: PluginShippingAddress): Promise<PluginShippingAddressCheck>;
+}
+export declare const PLUGIN_SHIPPING_RATE_QUOTER: import("./plugin-services").PluginServiceContract<PluginShippingRateQuoter>;
+/** Registers the plugin that quotes carrier rates. A second plugin is refused. */
+export declare function registerPluginShippingRateQuoter(quoter: PluginShippingRateQuoter, options?: {
+    pluginId?: string;
+}): void;
+/** The quoter, or `null` when no plugin registered one. */
+export declare function pluginShippingRateQuoter(): PluginShippingRateQuoter | null;
+/**
+ * Asks the quoter and gives up after `timeoutMs`: `null` when nobody is
+ * registered, the site is not available, the provider failed, or the wait
+ * ran out. Never throws. The caller's fallback is its own rates, so every
+ * failure reads the same.
+ */
+export declare function quotePluginShippingRates(request: Omit<PluginShippingQuoteRequest, 'signal'>, options: {
+    timeoutMs: number;
+}): Promise<PluginShippingQuote[] | null>;

package/src/lib/plugin-manager/plugin-shipping-rates.js

@@ -0,0 +1,62 @@
+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_SHIPPING_RATE_QUOTER = definePluginServiceContract('core.shipping-rate-quoter', {
+    multiple: false
+});
+/** Registers the plugin that quotes carrier rates. A second plugin is refused. */ export function registerPluginShippingRateQuoter(quoter, options) {
+    registerPluginService(PLUGIN_SHIPPING_RATE_QUOTER, quoter, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The quoter, or `null` when no plugin registered one. */ export function pluginShippingRateQuoter() {
+    var _ref;
+    var _resolvePluginServices_;
+    return (_ref = (_resolvePluginServices_ = resolvePluginServices(PLUGIN_SHIPPING_RATE_QUOTER)[0]) == null ? void 0 : _resolvePluginServices_.impl) != null ? _ref : null;
+}
+/**
+ * Asks the quoter and gives up after `timeoutMs`: `null` when nobody is
+ * registered, the site is not available, the provider failed, or the wait
+ * ran out. Never throws. The caller's fallback is its own rates, so every
+ * failure reads the same.
+ */ export async function quotePluginShippingRates(request, options) {
+    const quoter = pluginShippingRateQuoter();
+    if (!quoter) return null;
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((resolve)=>{
+        timer = setTimeout(()=>{
+            controller.abort();
+            resolve(null);
+        }, Math.max(0, options.timeoutMs));
+    });
+    try {
+        return await Promise.race([
+            (async ()=>{
+                if (!await quoter.available(request.hostId)) return null;
+                return quoter.quote(_extends({}, request, {
+                    signal: controller.signal
+                }));
+            })().catch(()=>null),
+            deadline
+        ]);
+    } finally{
+        if (timer) clearTimeout(timer);
+    }
+}
+
+//# sourceMappingURL=plugin-shipping-rates.js.map

package/src/lib/plugin-manager/plugin-shipping-rates.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-shipping-rates.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 * Live parcel rates, answered by the one plugin that talks to carriers\n * (AGL-3612).\n *\n * A plugin that sells goods prices delivery from its own table until the\n * merchant asks for live rates; then it needs a carrier's quote for an\n * address and a parcel, and it must not learn which carrier network, which\n * account or which vendor answers. A plugin that buys labels registers here;\n * a plugin that sells asks here, and neither imports the other.\n *\n * ## The shape is a parcel and an address, nothing more\n *\n * Every type below is postal: where it goes, what it weighs, how big it is,\n * and what it is worth for insurance and customs. Nothing names a catalog, an\n * order or a store, so a booking plugin shipping a rental kit asks the same\n * question in the same words.\n *\n * ## Nobody home is `null`, never a refusal\n *\n * Unlike the tax profile, an absent quoter is a perfectly good answer: the\n * seller falls back to its own rates, which is what it did before anyone\n * registered. {@link pluginShippingRateQuoter} answers `null`, and a quoter\n * whose deployment is not configured answers `available() === false`, which\n * a caller must read the same way.\n *\n * ## A quote is advisory until a label is bought\n *\n * `amountCents` is what the carrier quoted the platform for that parcel at\n * that moment, BEFORE any markup or handling the seller adds. The seller\n * decides what the shopper pays; the quoter never does.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-shipping-rates`); it is not in the\n * barrel.\n */\n\n/** A postal address. `country` is ISO-3166 alpha-2; everything else is optional. */\nexport interface PluginShippingAddress {\n  name?: string\n  company?: string\n  line1?: string\n  line2?: string\n  city?: string\n  /** State, province or region code, as the destination writes it. */\n  state?: string\n  postalCode?: string\n  country: string\n  phone?: string\n  email?: string\n  /** Whether the address is a home, when the caller knows; carriers price it. */\n  residential?: boolean\n}\n\n/** One parcel. Metric throughout; an adapter converts to its vendor's units. */\nexport interface PluginShippingParcel {\n  weightGrams: number\n  lengthCm?: number\n  widthCm?: number\n  heightCm?: number\n}\n\n/** What a seller asks: one shipment's rates to one address. */\nexport interface PluginShippingQuoteRequest {\n  /** The site the shipment leaves from; the quoter resolves its ship-from address. */\n  hostId: string\n  to: PluginShippingAddress\n  parcels: PluginShippingParcel[]\n  /** ISO-4217, lower case, of the amounts the caller will charge in. */\n  currency: string\n  /** The goods' value, for insurance and customs; 0 when unknown. */\n  valueCents: number\n  /**\n   * Service keys the seller offers (`'usps:priority'`), as\n   * {@link PluginShippingRateQuoter.listServices} names them. Empty or\n   * absent means every service the quoter can price.\n   */\n  services?: string[]\n  /** Aborted when the caller stops waiting; a quoter passes it to its fetches. */\n  signal?: AbortSignal\n}\n\n/** One carrier service's price for the shipment. */\nexport interface PluginShippingQuote {\n  /** Stable across quotes: `carrier:service`, the key a seller stores. */\n  serviceKey: string\n  carrier: string\n  service: string\n  /** What a shopper reads: `'USPS Priority Mail'`. */\n  label: string\n  /** The carrier's price to the platform, before any markup or handling. */\n  amountCents: number\n  currency: string\n  /** Transit estimate in business days, when the carrier gives one. */\n  estimatedDays?: number\n}\n\n/** A service a seller may choose to offer. */\nexport interface PluginShippingService {\n  serviceKey: string\n  carrier: string\n  label: string\n}\n\n/** What address validation answers. */\nexport interface PluginShippingAddressCheck {\n  /** `valid` deliverable as written; `corrected` deliverable as `suggested`; `invalid` not deliverable. */\n  verdict: 'valid' | 'corrected' | 'invalid' | 'unknown'\n  /** The address the carrier would deliver to, when it differs. */\n  suggested?: PluginShippingAddress\n  /** Why it is not deliverable, in the carrier's words. */\n  messages: string[]\n}\n\nexport interface PluginShippingRateQuoter {\n  /** Whether quotes can be asked for this site now: configured and switched on. */\n  available(hostId: string): Promise<boolean>\n  /**\n   * The rates. Throws on a provider failure; a caller that cannot wait\n   * aborts `signal` and falls back to its own rates.\n   */\n  quote(request: PluginShippingQuoteRequest): Promise<PluginShippingQuote[]>\n  /** The services a seller can pick from for this site. */\n  listServices(hostId: string): Promise<PluginShippingService[]>\n  /** Whether an address is deliverable, and the carrier's correction. */\n  validateAddress?(\n    hostId: string,\n    address: PluginShippingAddress,\n  ): Promise<PluginShippingAddressCheck>\n}\n\nexport const PLUGIN_SHIPPING_RATE_QUOTER =\n  definePluginServiceContract<PluginShippingRateQuoter>('core.shipping-rate-quoter', {\n    multiple: false,\n  })\n\n/** Registers the plugin that quotes carrier rates. A second plugin is refused. */\nexport function registerPluginShippingRateQuoter(\n  quoter: PluginShippingRateQuoter,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_SHIPPING_RATE_QUOTER, quoter, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The quoter, or `null` when no plugin registered one. */\nexport function pluginShippingRateQuoter(): PluginShippingRateQuoter | null {\n  return resolvePluginServices(PLUGIN_SHIPPING_RATE_QUOTER)[0]?.impl ?? null\n}\n\n/**\n * Asks the quoter and gives up after `timeoutMs`: `null` when nobody is\n * registered, the site is not available, the provider failed, or the wait\n * ran out. Never throws. The caller's fallback is its own rates, so every\n * failure reads the same.\n */\nexport async function quotePluginShippingRates(\n  request: Omit<PluginShippingQuoteRequest, 'signal'>,\n  options: { timeoutMs: number },\n): Promise<PluginShippingQuote[] | null> {\n  const quoter = pluginShippingRateQuoter()\n  if (!quoter) return null\n  const controller = new AbortController()\n  let timer: ReturnType<typeof setTimeout> | undefined\n  const deadline = new Promise<null>((resolve) => {\n    timer = setTimeout(() => {\n      controller.abort()\n      resolve(null)\n    }, Math.max(0, options.timeoutMs))\n  })\n  try {\n    return await Promise.race([\n      (async (): Promise<PluginShippingQuote[] | null> => {\n        if (!(await quoter.available(request.hostId))) return null\n        return quoter.quote({ ...request, signal: controller.signal })\n      })().catch((): null => null),\n      deadline,\n    ])\n  } finally {\n    if (timer) clearTimeout(timer)\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_SHIPPING_RATE_QUOTER","multiple","registerPluginShippingRateQuoter","quoter","options","pluginId","pluginShippingRateQuoter","impl","quotePluginShippingRates","request","controller","AbortController","timer","deadline","Promise","resolve","setTimeout","abort","Math","max","timeoutMs","race","available","hostId","quote","signal","catch","clearTimeout"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAoI1B,OAAO,MAAMC,8BACXH,4BAAsD,6BAA6B;IACjFI,UAAU;AACZ,GAAE;AAEJ,gFAAgF,GAChF,OAAO,SAASC,iCACdC,MAAgC,EAChCC,OAA+B;IAE/BN,sBAAsBE,6BAA6BG,QAAQ,aACrDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yDAAyD,GACzD,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,4BAA4B,CAAC,EAAE,qBAArDD,wBAAuDQ,IAAI,mBAAI;AACxE;AAEA;;;;;CAKC,GACD,OAAO,eAAeC,yBACpBC,OAAmD,EACnDL,OAA8B;IAE9B,MAAMD,SAASG;IACf,IAAI,CAACH,QAAQ,OAAO;IACpB,MAAMO,aAAa,IAAIC;IACvB,IAAIC;IACJ,MAAMC,WAAW,IAAIC,QAAc,CAACC;QAClCH,QAAQI,WAAW;YACjBN,WAAWO,KAAK;YAChBF,QAAQ;QACV,GAAGG,KAAKC,GAAG,CAAC,GAAGf,QAAQgB,SAAS;IAClC;IACA,IAAI;QACF,OAAO,MAAMN,QAAQO,IAAI,CAAC;YACvB,CAAA;gBACC,IAAI,CAAE,MAAMlB,OAAOmB,SAAS,CAACb,QAAQc,MAAM,GAAI,OAAO;gBACtD,OAAOpB,OAAOqB,KAAK,CAAC,aAAKf;oBAASgB,QAAQf,WAAWe,MAAM;;YAC7D,CAAA,IAAKC,KAAK,CAAC,IAAY;YACvBb;SACD;IACH,SAAU;QACR,IAAID,OAAOe,aAAaf;IAC1B;AACF"}

package/src/lib/plugin-manager/plugin-sms-messaging.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @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.
+ */
+/**
+ * Sending a text message, as a platform capability any plugin may ask for
+ * (AGL-3610) — the GENERIC half. Which vendor carries the message, how it is
+ * metered and billed, and which numbers may not be texted are the provider
+ * plugin's (`@aglyn/plugins-sms`); the caller knows none of it.
+ *
+ * Shaped like the tax profile seam (`plugin-tax-profile.ts`): one contract in
+ * core, one provider plugin registers it at boot through its
+ * `serverDeclarations`, and a consumer (commerce's order texts) resolves it by
+ * contract rather than importing the plugin. The difference is the absent
+ * case: a missing tax profile must refuse a charge, while a missing SMS
+ * provider is an ordinary state — most installs have none — so
+ * {@link pluginSmsMessaging} answers `undefined` and the caller offers email
+ * only.
+ */
+export interface PluginSmsSendRequest {
+    /** The number to text, in any format a person types; the provider normalizes. */
+    to: string;
+    /** Plain text. The provider decides segmenting; keep it short. */
+    body: string;
+    /** The site the message is sent for. Metering and rate limits key off its workspace. */
+    hostId: string;
+    /**
+     * Why this text is being sent. Only `transactional` exists today: a message
+     * the recipient's own order or request owes them. Marketing texts need a
+     * consent record this contract does not carry, so it does not admit them.
+     */
+    purpose: 'transactional';
+    /** A short label for logs, e.g. `'order-shipped'`. */
+    context?: string;
+    /**
+     * Keeps the text out of the recipient's night. Given, a text that would
+     * land between 9 PM and 8 AM in `timeZone` (an IANA name) is held and
+     * delivered at 8 AM there instead; the outcome is still `sent`, with
+     * `scheduledForMs`. Omit it for a text the recipient is waiting on right
+     * now — a receipt at the counter, a sign-in code — which goes at once.
+     */
+    quietHours?: {
+        timeZone: string;
+    };
+}
+export type PluginSmsSendOutcome = {
+    status: 'sent';
+    /** The provider's message id. */
+    id: string;
+    /** The number as sent, E.164. */
+    to: string;
+    segments: number;
+    /** Held for the recipient's morning: when it will be delivered. */
+    scheduledForMs?: number;
+}
+/** No provider credentials: nothing was attempted. */
+ | {
+    status: 'not-configured';
+}
+/** The number could not be read as a phone number. */
+ | {
+    status: 'invalid-number';
+}
+/** The recipient texted STOP, or staff suppressed the number. */
+ | {
+    status: 'suppressed';
+}
+/** The workspace hit its text rate limit; nothing was sent. */
+ | {
+    status: 'rate-limited';
+} | {
+    status: 'failed';
+    error: string;
+};
+export interface PluginSmsMessaging {
+    /**
+     * Whether texts can be sent at all. Cheap and synchronous, so a route can
+     * ask it to decide whether to OFFER a text before anything is typed.
+     */
+    isConfigured(): boolean;
+    /** Sends one text. Never throws: every failure is an outcome. */
+    send(request: PluginSmsSendRequest): Promise<PluginSmsSendOutcome>;
+}
+export declare const PLUGIN_SMS_MESSAGING: import("./plugin-services").PluginServiceContract<PluginSmsMessaging>;
+export declare function registerPluginSmsMessaging(messaging: PluginSmsMessaging, options?: {
+    pluginId?: string;
+}): void;
+/** The registered provider, or `undefined` when no plugin offers texts. */
+export declare function pluginSmsMessaging(): PluginSmsMessaging | undefined;
+/** Whether a provider is registered AND configured: the UI's "offer text?" */
+export declare function pluginSmsAvailable(): boolean;