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

package/src/lib/plugin-manager/plugin-sms-messaging.js

@@ -0,0 +1,39 @@
+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_SMS_MESSAGING = definePluginServiceContract('core.messaging.sms', {
+    multiple: false
+});
+export function registerPluginSmsMessaging(messaging, options) {
+    registerPluginService(PLUGIN_SMS_MESSAGING, messaging, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered provider, or `undefined` when no plugin offers texts. */ export function pluginSmsMessaging() {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(PLUGIN_SMS_MESSAGING)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+/** Whether a provider is registered AND configured: the UI's "offer text?" */ export function pluginSmsAvailable() {
+    try {
+        var _pluginSmsMessaging;
+        return ((_pluginSmsMessaging = pluginSmsMessaging()) == null ? void 0 : _pluginSmsMessaging.isConfigured()) === true;
+    } catch (unused) {
+        return false;
+    }
+}
+
+//# sourceMappingURL=plugin-sms-messaging.js.map

package/src/lib/plugin-manager/plugin-sms-messaging.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-sms-messaging.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 * Sending a text message, as a platform capability any plugin may ask for\n * (AGL-3610) — the GENERIC half. Which vendor carries the message, how it is\n * metered and billed, and which numbers may not be texted are the provider\n * plugin's (`@aglyn/plugins-sms`); the caller knows none of it.\n *\n * Shaped like the tax profile seam (`plugin-tax-profile.ts`): one contract in\n * core, one provider plugin registers it at boot through its\n * `serverDeclarations`, and a consumer (commerce's order texts) resolves it by\n * contract rather than importing the plugin. The difference is the absent\n * case: a missing tax profile must refuse a charge, while a missing SMS\n * provider is an ordinary state — most installs have none — so\n * {@link pluginSmsMessaging} answers `undefined` and the caller offers email\n * only.\n */\nexport interface PluginSmsSendRequest {\n  /** The number to text, in any format a person types; the provider normalizes. */\n  to: string\n  /** Plain text. The provider decides segmenting; keep it short. */\n  body: string\n  /** The site the message is sent for. Metering and rate limits key off its workspace. */\n  hostId: string\n  /**\n   * Why this text is being sent. Only `transactional` exists today: a message\n   * the recipient's own order or request owes them. Marketing texts need a\n   * consent record this contract does not carry, so it does not admit them.\n   */\n  purpose: 'transactional'\n  /** A short label for logs, e.g. `'order-shipped'`. */\n  context?: string\n  /**\n   * Keeps the text out of the recipient's night. Given, a text that would\n   * land between 9 PM and 8 AM in `timeZone` (an IANA name) is held and\n   * delivered at 8 AM there instead; the outcome is still `sent`, with\n   * `scheduledForMs`. Omit it for a text the recipient is waiting on right\n   * now — a receipt at the counter, a sign-in code — which goes at once.\n   */\n  quietHours?: { timeZone: string }\n}\n\nexport type PluginSmsSendOutcome =\n  | {\n      status: 'sent'\n      /** The provider's message id. */\n      id: string\n      /** The number as sent, E.164. */\n      to: string\n      segments: number\n      /** Held for the recipient's morning: when it will be delivered. */\n      scheduledForMs?: number\n    }\n  /** No provider credentials: nothing was attempted. */\n  | { status: 'not-configured' }\n  /** The number could not be read as a phone number. */\n  | { status: 'invalid-number' }\n  /** The recipient texted STOP, or staff suppressed the number. */\n  | { status: 'suppressed' }\n  /** The workspace hit its text rate limit; nothing was sent. */\n  | { status: 'rate-limited' }\n  | { status: 'failed'; error: string }\n\nexport interface PluginSmsMessaging {\n  /**\n   * Whether texts can be sent at all. Cheap and synchronous, so a route can\n   * ask it to decide whether to OFFER a text before anything is typed.\n   */\n  isConfigured(): boolean\n  /** Sends one text. Never throws: every failure is an outcome. */\n  send(request: PluginSmsSendRequest): Promise<PluginSmsSendOutcome>\n}\n\nexport const PLUGIN_SMS_MESSAGING =\n  definePluginServiceContract<PluginSmsMessaging>('core.messaging.sms', {\n    multiple: false,\n  })\n\nexport function registerPluginSmsMessaging(\n  messaging: PluginSmsMessaging,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_SMS_MESSAGING, messaging, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered provider, or `undefined` when no plugin offers texts. */\nexport function pluginSmsMessaging(): PluginSmsMessaging | undefined {\n  return resolvePluginServices(PLUGIN_SMS_MESSAGING)[0]?.impl\n}\n\n/** Whether a provider is registered AND configured: the UI's \"offer text?\" */\nexport function pluginSmsAvailable(): boolean {\n  try {\n    return pluginSmsMessaging()?.isConfigured() === true\n  } catch {\n    return false\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_SMS_MESSAGING","multiple","registerPluginSmsMessaging","messaging","options","pluginId","pluginSmsMessaging","impl","pluginSmsAvailable","isConfigured"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAyE1B,OAAO,MAAMC,uBACXH,4BAAgD,sBAAsB;IACpEI,UAAU;AACZ,GAAE;AAEJ,OAAO,SAASC,2BACdC,SAA6B,EAC7BC,OAA+B;IAE/BN,sBAAsBE,sBAAsBG,WAAW,aACjDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yEAAyE,GACzE,OAAO,SAASC;QACPP;IAAP,QAAOA,0BAAAA,sBAAsBC,qBAAqB,CAAC,EAAE,qBAA9CD,wBAAgDQ,IAAI;AAC7D;AAEA,4EAA4E,GAC5E,OAAO,SAASC;IACd,IAAI;YACKF;QAAP,OAAOA,EAAAA,sBAAAA,yCAAAA,oBAAsBG,YAAY,QAAO;IAClD,EAAE,eAAM;QACN,OAAO;IACT;AACF"}

package/src/lib/plugin-manager/plugin-stock-levels.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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.
+ */
+/**
+ * Stock counts kept somewhere else (AGL-3634).
+ *
+ * When a warehouse that is not the merchant's — a fulfillment network, a
+ * supplier — holds the goods, its count is the true one, and the store's own
+ * count should say what it says. The plugin that reads that count must not
+ * write the seller's products itself, so the seller registers
+ * {@link PluginStockLevels} and applies each count under its own rules: the
+ * ledger row that explains the change, the sold-out flag, the low-stock
+ * alert, back-in-stock email.
+ *
+ * Counts are matched by SKU, the one identifier a warehouse and a store
+ * share. A count the seller cannot apply says why, per SKU, so the plugin
+ * that sent it can show the merchant: no product has that SKU, the product
+ * does not track stock, or it counts stock per location (where one number
+ * would erase the others).
+ *
+ * Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-stock-levels`); it is not in the
+ * barrel.
+ */
+/** One SKU's count: the units that can be sold now. */
+export interface PluginStockLevel {
+    sku: string;
+    quantity: number;
+}
+export type PluginStockLevelOutcome = 
+/** The count changed to `after`. */
+'updated'
+/** The count already said this. */
+ | 'unchanged'
+/** No live product of the store has this SKU. */
+ | 'unknown_sku'
+/** The product does not track stock, so there is no count to set. */
+ | 'untracked'
+/** The product counts stock per location; one number would erase the others. */
+ | 'per_location'
+/** The count was not a whole number of zero or more. */
+ | 'invalid'
+/** The write did not land; the next sync tries again. */
+ | 'failed';
+export interface PluginStockLevelResult {
+    sku: string;
+    outcome: PluginStockLevelOutcome;
+    /** The count before, when the seller read one. */
+    before?: number;
+    /** The count after, when the seller wrote one. */
+    after?: number;
+}
+export interface PluginStockLevelRequest {
+    hostId: string;
+    levels: readonly PluginStockLevel[];
+    /** Who counted: shown beside the change in the store's stock history, e.g. `ShipBob`. */
+    source: string;
+}
+export interface PluginStockLevels {
+    /** Sets each SKU's count; one result per SKU asked, in order. */
+    setAvailable(request: PluginStockLevelRequest): Promise<PluginStockLevelResult[]>;
+}
+/** Registers the seller. A second plugin is refused naming both. */
+export declare function registerPluginStockLevels(levels: PluginStockLevels, options?: {
+    pluginId?: string;
+}): void;
+/** The seller, or `null` when no plugin registered one. */
+export declare function pluginStockLevels(): PluginStockLevels | null;

package/src/lib/plugin-manager/plugin-stock-levels.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_STOCK_LEVELS = definePluginServiceContract('core.stock-levels', {
+    multiple: false
+});
+/** Registers the seller. A second plugin is refused naming both. */ export function registerPluginStockLevels(levels, options) {
+    registerPluginService(PLUGIN_STOCK_LEVELS, levels, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The seller, or `null` when no plugin registered one. */ export function pluginStockLevels() {
+    var _ref;
+    var _resolvePluginServices_;
+    return (_ref = (_resolvePluginServices_ = resolvePluginServices(PLUGIN_STOCK_LEVELS)[0]) == null ? void 0 : _resolvePluginServices_.impl) != null ? _ref : null;
+}
+
+//# sourceMappingURL=plugin-stock-levels.js.map

package/src/lib/plugin-manager/plugin-stock-levels.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-stock-levels.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 * Stock counts kept somewhere else (AGL-3634).\n *\n * When a warehouse that is not the merchant's — a fulfillment network, a\n * supplier — holds the goods, its count is the true one, and the store's own\n * count should say what it says. The plugin that reads that count must not\n * write the seller's products itself, so the seller registers\n * {@link PluginStockLevels} and applies each count under its own rules: the\n * ledger row that explains the change, the sold-out flag, the low-stock\n * alert, back-in-stock email.\n *\n * Counts are matched by SKU, the one identifier a warehouse and a store\n * share. A count the seller cannot apply says why, per SKU, so the plugin\n * that sent it can show the merchant: no product has that SKU, the product\n * does not track stock, or it counts stock per location (where one number\n * would erase the others).\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-stock-levels`); it is not in the\n * barrel.\n */\n\n/** One SKU's count: the units that can be sold now. */\nexport interface PluginStockLevel {\n  sku: string\n  quantity: number\n}\n\nexport type PluginStockLevelOutcome =\n  /** The count changed to `after`. */\n  | 'updated'\n  /** The count already said this. */\n  | 'unchanged'\n  /** No live product of the store has this SKU. */\n  | 'unknown_sku'\n  /** The product does not track stock, so there is no count to set. */\n  | 'untracked'\n  /** The product counts stock per location; one number would erase the others. */\n  | 'per_location'\n  /** The count was not a whole number of zero or more. */\n  | 'invalid'\n  /** The write did not land; the next sync tries again. */\n  | 'failed'\n\nexport interface PluginStockLevelResult {\n  sku: string\n  outcome: PluginStockLevelOutcome\n  /** The count before, when the seller read one. */\n  before?: number\n  /** The count after, when the seller wrote one. */\n  after?: number\n}\n\nexport interface PluginStockLevelRequest {\n  hostId: string\n  levels: readonly PluginStockLevel[]\n  /** Who counted: shown beside the change in the store's stock history, e.g. `ShipBob`. */\n  source: string\n}\n\nexport interface PluginStockLevels {\n  /** Sets each SKU's count; one result per SKU asked, in order. */\n  setAvailable(request: PluginStockLevelRequest): Promise<PluginStockLevelResult[]>\n}\n\nconst PLUGIN_STOCK_LEVELS = definePluginServiceContract<PluginStockLevels>('core.stock-levels', {\n  multiple: false,\n})\n\n/** Registers the seller. A second plugin is refused naming both. */\nexport function registerPluginStockLevels(levels: PluginStockLevels, options?: { pluginId?: string }): void {\n  registerPluginService(PLUGIN_STOCK_LEVELS, levels, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The seller, or `null` when no plugin registered one. */\nexport function pluginStockLevels(): PluginStockLevels | null {\n  return resolvePluginServices(PLUGIN_STOCK_LEVELS)[0]?.impl ?? null\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_STOCK_LEVELS","multiple","registerPluginStockLevels","levels","options","pluginId","pluginStockLevels","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAmE1B,MAAMC,sBAAsBH,4BAA+C,qBAAqB;IAC9FI,UAAU;AACZ;AAEA,kEAAkE,GAClE,OAAO,SAASC,0BAA0BC,MAAyB,EAAEC,OAA+B;IAClGN,sBAAsBE,qBAAqBG,QAAQ,aAC7CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,yDAAyD,GACzD,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,oBAAoB,CAAC,EAAE,qBAA7CD,wBAA+CQ,IAAI,mBAAI;AAChE"}

package/src/lib/plugin-manager/plugin-tax-profile.d.ts

@@ -98,3 +98,157 @@ export declare function registerPluginTaxProfile(profile: PluginTaxProfile, opti
 export declare function pluginTaxProfileOwner(): string | null;
 /** The tax rule. THROWS when no plugin registered one; see the module note. */
 export declare function pluginTaxProfile(): PluginTaxProfile;
+/**
+ * AN OUTSIDE TAX ENGINE, answering for a merchant who connected one
+ * (AGL-3631).
+ *
+ * The tax profile above is the merchant's own flat arithmetic. Some merchants
+ * calculate tax in a service of their own — an Avalara AvaTax or TaxJar
+ * account, under their own registrations — and want the plugin that charges
+ * to ask that service instead of a rate table. This contract is that
+ * question, asked the same way whichever service answers it:
+ *
+ * - {@link PluginTaxEngine.status} — whether a site has an engine connected
+ *   and which one;
+ * - {@link PluginTaxEngine.quote} — the tax on a basket, by line, for a
+ *   destination (or the site's own address for an in-person sale);
+ * - {@link PluginTaxEngine.validateAddress} — the engine's own reading of an
+ *   address, for a plugin that wants it checked before it ships or taxes.
+ *
+ * Recording a paid sale with the engine, and reversing it on a refund or a
+ * cancellation, is NOT asked here. The seller's plugin already announces
+ * those facts as domain events (`order.paid`, `order.refunded`,
+ * `order.cancelled`), with retries, so the engine's plugin subscribes to them
+ * and the seller never has to know an engine records anything.
+ *
+ * ## A slot, and an empty one is an answer
+ *
+ * One plugin owns outside engines; it dispatches to whichever service a site
+ * connected. Unlike the tax profile, an empty slot is a normal state — most
+ * deployments carry no engine — so {@link pluginTaxEngine} answers `null`,
+ * and a caller that wanted one prices the sale its usual way and says so.
+ *
+ * ## The engine is slow and outside, so the caller holds a deadline
+ *
+ * {@link quotePluginTaxEngine} never throws and never waits past its
+ * deadline: a checkout that hung on a vendor would lose the sale, and one
+ * that failed outright would lose it too. It answers what happened —
+ * `unavailable`, `timeout` or `error` — so the caller can fall back to the
+ * tax path it had before, flag the order, and log why.
+ */
+/** A postal address as a tax engine reads it. `country` is ISO-3166 alpha-2. */
+export interface PluginTaxAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    /** State, province or region code, e.g. `TX`. */
+    region?: string;
+    postalCode?: string;
+    country: string;
+}
+/** One taxable line of a basket. Money is integer cents in the request's currency. */
+export interface PluginTaxEngineLine {
+    /** The caller's own id for the line, echoed back on the answer. */
+    id: string;
+    /** The product the line sells, so the engine's plugin can find its tax code. */
+    productId?: string;
+    variantId?: string;
+    sku?: string;
+    description?: string;
+    quantity: number;
+    /** The line's total after any discount on it, EXCLUSIVE of tax. */
+    amountCents: number;
+    /** A tax code the caller already holds; otherwise the engine's plugin supplies one. */
+    taxCode?: string;
+    /** A line the seller marked tax-exempt: quoted at zero whatever the engine says. */
+    exempt?: boolean;
+}
+/** What a caller asks an engine. */
+export interface PluginTaxEngineQuoteRequest {
+    hostId: string;
+    /** ISO 4217, lower or upper case. */
+    currency: string;
+    /** Where the sale happens: `pos` is in person, taxed at the site's own address. */
+    channel: 'online' | 'pos' | 'invoice';
+    lines: readonly PluginTaxEngineLine[];
+    /**
+     * A discount on the whole basket, spread by the engine's plugin across the
+     * lines that are not exempt. Line-level discounts are already inside each
+     * line's `amountCents`.
+     */
+    discountCents?: number;
+    /** Shipping charged, when the caller wants it quoted. */
+    shippingCents?: number;
+    /** The destination. Absent or `null`, the engine taxes at the site's own address. */
+    shipTo?: PluginTaxAddress | null;
+    /** The buyer, so an exemption the merchant recorded for them applies. */
+    customer?: {
+        email?: string | null;
+        id?: string | null;
+    };
+}
+/** One line of an answer. */
+export interface PluginTaxEngineQuoteLine {
+    id: string;
+    taxCents: number;
+}
+/** What an engine answered. Every figure is integer cents. */
+export interface PluginTaxEngineQuote {
+    /** The engine's id, e.g. `avalara`. */
+    provider: string;
+    /** Its name in the merchant's words, e.g. `Avalara AvaTax`. */
+    providerLabel: string;
+    taxCents: number;
+    lines: readonly PluginTaxEngineQuoteLine[];
+    shippingTaxCents: number;
+    /** Whether the answer came from the engine's test environment. */
+    sandbox: boolean;
+}
+/** Whether a site has an engine connected. */
+export interface PluginTaxEngineStatus {
+    connected: boolean;
+    provider?: string;
+    providerLabel?: string;
+    sandbox?: boolean;
+}
+/** An engine's reading of an address. */
+export interface PluginTaxAddressValidation {
+    valid: boolean;
+    /** The address as the engine normalized it, when it could. */
+    normalized: PluginTaxAddress | null;
+    /** What the engine said about it, in its own words. */
+    messages: readonly string[];
+}
+export interface PluginTaxEngine {
+    status(hostId: string): Promise<PluginTaxEngineStatus>;
+    /** THROWS on any failure: no connection, a refusal, a network error. */
+    quote(request: PluginTaxEngineQuoteRequest): Promise<PluginTaxEngineQuote>;
+    /** THROWS when no engine is connected for the site or the engine fails. */
+    validateAddress(hostId: string, address: PluginTaxAddress): Promise<PluginTaxAddressValidation>;
+}
+export declare const PLUGIN_TAX_ENGINE: import("./plugin-services").PluginServiceContract<PluginTaxEngine>;
+/** Registers the plugin that answers for outside tax engines. */
+export declare function registerPluginTaxEngine(engine: PluginTaxEngine, options?: {
+    pluginId?: string;
+}): void;
+/** The engine's plugin, or `null` when no plugin registered one. */
+export declare function pluginTaxEngine(): PluginTaxEngine | null;
+/** How long a quote may take before the caller prices the sale without it. */
+export declare const PLUGIN_TAX_ENGINE_QUOTE_TIMEOUT_MS = 5000;
+/** What {@link quotePluginTaxEngine} came to. */
+export type PluginTaxEngineQuoteOutcome = {
+    ok: true;
+    quote: PluginTaxEngineQuote;
+} | {
+    ok: false;
+    /** No engine plugin, or none connected for the site. */
+    reason: 'unavailable' | 'timeout' | 'error';
+    message: string;
+};
+/**
+ * Asks the engine for a quote within a deadline. Never throws: see the
+ * module note on why the caller, not the engine, holds the clock.
+ */
+export declare function quotePluginTaxEngine(request: PluginTaxEngineQuoteRequest, options?: {
+    timeoutMs?: number;
+}): Promise<PluginTaxEngineQuoteOutcome>;

package/src/lib/plugin-manager/plugin-tax-profile.js

@@ -35,5 +35,61 @@ export const PLUGIN_TAX_PROFILE = definePluginServiceContract('core.tax-profile'
     }
     return entry.impl;
 }
+export const PLUGIN_TAX_ENGINE = definePluginServiceContract('core.tax-engine', {
+    multiple: false
+});
+/** Registers the plugin that answers for outside tax engines. */ export function registerPluginTaxEngine(engine, options) {
+    registerPluginService(PLUGIN_TAX_ENGINE, engine, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The engine's plugin, or `null` when no plugin registered one. */ export function pluginTaxEngine() {
+    var _ref;
+    var _resolvePluginServices_;
+    return (_ref = (_resolvePluginServices_ = resolvePluginServices(PLUGIN_TAX_ENGINE)[0]) == null ? void 0 : _resolvePluginServices_.impl) != null ? _ref : null;
+}
+/** How long a quote may take before the caller prices the sale without it. */ export const PLUGIN_TAX_ENGINE_QUOTE_TIMEOUT_MS = 5000;
+/**
+ * Asks the engine for a quote within a deadline. Never throws: see the
+ * module note on why the caller, not the engine, holds the clock.
+ */ export async function quotePluginTaxEngine(request, options = {}) {
+    var _options_timeoutMs;
+    const engine = pluginTaxEngine();
+    if (!engine) {
+        return {
+            ok: false,
+            reason: 'unavailable',
+            message: 'no tax engine plugin is registered'
+        };
+    }
+    const timeoutMs = Math.max(1, (_options_timeoutMs = options.timeoutMs) != null ? _options_timeoutMs : PLUGIN_TAX_ENGINE_QUOTE_TIMEOUT_MS);
+    let timer;
+    const deadline = new Promise((resolve)=>{
+        timer = setTimeout(()=>resolve({
+                ok: false,
+                reason: 'timeout',
+                message: `the tax engine did not answer within ${timeoutMs} ms`
+            }), timeoutMs);
+    });
+    const asked = Promise.resolve().then(()=>engine.quote(request)).then((quote)=>({
+            ok: true,
+            quote
+        }), (error)=>{
+        var _ref;
+        return {
+            ok: false,
+            reason: 'error',
+            message: String((_ref = error == null ? void 0 : error.message) != null ? _ref : error).slice(0, 300)
+        };
+    });
+    try {
+        return await Promise.race([
+            asked,
+            deadline
+        ]);
+    } finally{
+        if (timer) clearTimeout(timer);
+    }
+}
 
 //# sourceMappingURL=plugin-tax-profile.js.map

package/src/lib/plugin-manager/plugin-tax-profile.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-tax-profile.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 * The tenant's tax rule, answered by the one plugin that owns it (AGL-3080).\n *\n * More than one plugin takes money — a storefront sells goods, a calendar\n * sells appointments — and a merchant has ONE tax profile. The plugin that\n * keeps it works out what a flat rate adds to a charge and which regime a\n * settled payment was taxed under; any other plugin that charges asks here.\n * Importing the owner's model instead is how two money paths end up with two\n * rounding rules, and the second is found by an accountant.\n *\n * ## Where the rate is kept, and the arithmetic over it\n *\n * The merchant's rates are the owner's settings, stored where the owner keeps\n * them, so a caller asks for one — {@link PluginTaxProfile.flatRate}, the\n * contract's one read, by site and by the kind of charge — and never reads\n * the owner's documents itself. A plugin that knew where another plugin kept\n * a merchant's tax settings would charge untaxed, and record it as untaxed,\n * the day those settings moved.\n *\n * The other two questions are pure and synchronous arithmetic over values the\n * caller already holds: the rate it was handed, a charge in cents, a settled\n * payment object. Nobody is asked who they are.\n *\n * ## No profile is a refusal, never a zero\n *\n * {@link pluginTaxProfile} THROWS when no plugin registered one. Every other\n * seam here answers `null` for \"nobody home\", and this one must not: a caller\n * that read `null` as \"no tax\" would charge a customer an untaxed total and\n * record it as untaxed, silently, and the merchant would owe the difference.\n * A refused sale is seen the same day.\n *\n * It cannot happen in a working build. Both apps load every plugin's server\n * entry before a plugin handler, a cron or the billing webhook runs\n * (`ensureAll`), so the owner's registration is in place wherever a charge is\n * priced; `tax-profile-is-registered.spec.ts` in each app holds that.\n *\n * ## One owner\n *\n * A workspace has one tax profile, so the contract is a slot: a second\n * plugin's profile is refused naming both and the incumbent keeps serving.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-tax-profile`); it is not in the barrel.\n */\n\n/** What a flat rate adds to one charge. All zero and empty when it adds nothing. */\nexport interface PluginResolvedFlatTax {\n  taxCents: number\n  /** What the line is called on the receipt. */\n  label: string\n  pct: number\n}\n\nexport interface PluginTaxProfile {\n  /**\n   * The merchant's flat rate for one kind of charge on a site, as the owner\n   * stores it — to be handed to {@link PluginTaxProfile.flatTax} as read. `charge` names what\n   * is being sold in the owner's words for its rates (`service` for an\n   * appointment). A site that set none, or a kind the owner keeps no rate\n   * for, answers `undefined`, which `flatTax` prices at zero. Server-side:\n   * the owner reads its own settings document.\n   */\n  flatRate(hostId: string, charge: string): Promise<unknown>\n  /**\n   * Tax, EXCLUSIVE, for a flat merchant rate on one charged amount. `rate` is\n   * the merchant's stored setting, passed as read: the owner decides what a\n   * usable rate is, and an absent, zero, negative or out-of-range one answers\n   * zero rather than throwing.\n   */\n  flatTax(\n    rate: unknown,\n    chargeCents: number,\n    fallbackLabel: string,\n  ): PluginResolvedFlatTax\n  /**\n   * Which regime a settled payment was taxed under, as the owner records it.\n   * `manualTaxCents` is the tax this caller added as a line of its own, which\n   * the payment processor reports as no tax at all.\n   */\n  taxModeOf(settledPayment: unknown, manualTaxCents?: number): string\n}\n\nexport const PLUGIN_TAX_PROFILE = definePluginServiceContract<PluginTaxProfile>(\n  'core.tax-profile',\n  { multiple: false },\n)\n\n/** Registers the plugin that owns the tenant's tax rule. */\nexport function registerPluginTaxProfile(\n  profile: PluginTaxProfile,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_TAX_PROFILE, profile, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The owner, or `null` — for a caller that only wants to know who it is. */\nexport function pluginTaxProfileOwner(): string | null {\n  return resolvePluginServices(PLUGIN_TAX_PROFILE)[0]?.pluginId ?? null\n}\n\n/** The tax rule. THROWS when no plugin registered one; see the module note. */\nexport function pluginTaxProfile(): PluginTaxProfile {\n  const entry = resolvePluginServices(PLUGIN_TAX_PROFILE)[0]\n  if (!entry) {\n    throw new Error(\n      'no plugin registered a tax profile, so this charge cannot be priced: ' +\n        'refusing rather than charging it untaxed',\n    )\n  }\n  return entry.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_TAX_PROFILE","multiple","registerPluginTaxProfile","profile","options","pluginId","pluginTaxProfileOwner","pluginTaxProfile","entry","Error","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAoF1B,OAAO,MAAMC,qBAAqBH,4BAChC,oBACA;IAAEI,UAAU;AAAM,GACnB;AAED,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,OAAyB,EACzBC,OAA+B;IAE/BN,sBAAsBE,oBAAoBG,SAAS,aAC7CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,2EAA2E,GAC3E,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,mBAAmB,CAAC,EAAE,qBAA5CD,wBAA8CM,QAAQ,mBAAI;AACnE;AAEA,6EAA6E,GAC7E,OAAO,SAASE;IACd,MAAMC,QAAQT,sBAAsBC,mBAAmB,CAAC,EAAE;IAC1D,IAAI,CAACQ,OAAO;QACV,MAAM,IAAIC,MACR,0EACE;IAEN;IACA,OAAOD,MAAME,IAAI;AACnB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-tax-profile.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 * The tenant's tax rule, answered by the one plugin that owns it (AGL-3080).\n *\n * More than one plugin takes money — a storefront sells goods, a calendar\n * sells appointments — and a merchant has ONE tax profile. The plugin that\n * keeps it works out what a flat rate adds to a charge and which regime a\n * settled payment was taxed under; any other plugin that charges asks here.\n * Importing the owner's model instead is how two money paths end up with two\n * rounding rules, and the second is found by an accountant.\n *\n * ## Where the rate is kept, and the arithmetic over it\n *\n * The merchant's rates are the owner's settings, stored where the owner keeps\n * them, so a caller asks for one — {@link PluginTaxProfile.flatRate}, the\n * contract's one read, by site and by the kind of charge — and never reads\n * the owner's documents itself. A plugin that knew where another plugin kept\n * a merchant's tax settings would charge untaxed, and record it as untaxed,\n * the day those settings moved.\n *\n * The other two questions are pure and synchronous arithmetic over values the\n * caller already holds: the rate it was handed, a charge in cents, a settled\n * payment object. Nobody is asked who they are.\n *\n * ## No profile is a refusal, never a zero\n *\n * {@link pluginTaxProfile} THROWS when no plugin registered one. Every other\n * seam here answers `null` for \"nobody home\", and this one must not: a caller\n * that read `null` as \"no tax\" would charge a customer an untaxed total and\n * record it as untaxed, silently, and the merchant would owe the difference.\n * A refused sale is seen the same day.\n *\n * It cannot happen in a working build. Both apps load every plugin's server\n * entry before a plugin handler, a cron or the billing webhook runs\n * (`ensureAll`), so the owner's registration is in place wherever a charge is\n * priced; `tax-profile-is-registered.spec.ts` in each app holds that.\n *\n * ## One owner\n *\n * A workspace has one tax profile, so the contract is a slot: a second\n * plugin's profile is refused naming both and the incumbent keeps serving.\n *\n * Import this module by its own subpath\n * (`@aglyn/aglyn/plugin-manager/plugin-tax-profile`); it is not in the barrel.\n */\n\n/** What a flat rate adds to one charge. All zero and empty when it adds nothing. */\nexport interface PluginResolvedFlatTax {\n  taxCents: number\n  /** What the line is called on the receipt. */\n  label: string\n  pct: number\n}\n\nexport interface PluginTaxProfile {\n  /**\n   * The merchant's flat rate for one kind of charge on a site, as the owner\n   * stores it — to be handed to {@link PluginTaxProfile.flatTax} as read. `charge` names what\n   * is being sold in the owner's words for its rates (`service` for an\n   * appointment). A site that set none, or a kind the owner keeps no rate\n   * for, answers `undefined`, which `flatTax` prices at zero. Server-side:\n   * the owner reads its own settings document.\n   */\n  flatRate(hostId: string, charge: string): Promise<unknown>\n  /**\n   * Tax, EXCLUSIVE, for a flat merchant rate on one charged amount. `rate` is\n   * the merchant's stored setting, passed as read: the owner decides what a\n   * usable rate is, and an absent, zero, negative or out-of-range one answers\n   * zero rather than throwing.\n   */\n  flatTax(\n    rate: unknown,\n    chargeCents: number,\n    fallbackLabel: string,\n  ): PluginResolvedFlatTax\n  /**\n   * Which regime a settled payment was taxed under, as the owner records it.\n   * `manualTaxCents` is the tax this caller added as a line of its own, which\n   * the payment processor reports as no tax at all.\n   */\n  taxModeOf(settledPayment: unknown, manualTaxCents?: number): string\n}\n\nexport const PLUGIN_TAX_PROFILE = definePluginServiceContract<PluginTaxProfile>(\n  'core.tax-profile',\n  { multiple: false },\n)\n\n/** Registers the plugin that owns the tenant's tax rule. */\nexport function registerPluginTaxProfile(\n  profile: PluginTaxProfile,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_TAX_PROFILE, profile, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The owner, or `null` — for a caller that only wants to know who it is. */\nexport function pluginTaxProfileOwner(): string | null {\n  return resolvePluginServices(PLUGIN_TAX_PROFILE)[0]?.pluginId ?? null\n}\n\n/** The tax rule. THROWS when no plugin registered one; see the module note. */\nexport function pluginTaxProfile(): PluginTaxProfile {\n  const entry = resolvePluginServices(PLUGIN_TAX_PROFILE)[0]\n  if (!entry) {\n    throw new Error(\n      'no plugin registered a tax profile, so this charge cannot be priced: ' +\n        'refusing rather than charging it untaxed',\n    )\n  }\n  return entry.impl\n}\n\n/**\n * AN OUTSIDE TAX ENGINE, answering for a merchant who connected one\n * (AGL-3631).\n *\n * The tax profile above is the merchant's own flat arithmetic. Some merchants\n * calculate tax in a service of their own — an Avalara AvaTax or TaxJar\n * account, under their own registrations — and want the plugin that charges\n * to ask that service instead of a rate table. This contract is that\n * question, asked the same way whichever service answers it:\n *\n * - {@link PluginTaxEngine.status} — whether a site has an engine connected\n *   and which one;\n * - {@link PluginTaxEngine.quote} — the tax on a basket, by line, for a\n *   destination (or the site's own address for an in-person sale);\n * - {@link PluginTaxEngine.validateAddress} — the engine's own reading of an\n *   address, for a plugin that wants it checked before it ships or taxes.\n *\n * Recording a paid sale with the engine, and reversing it on a refund or a\n * cancellation, is NOT asked here. The seller's plugin already announces\n * those facts as domain events (`order.paid`, `order.refunded`,\n * `order.cancelled`), with retries, so the engine's plugin subscribes to them\n * and the seller never has to know an engine records anything.\n *\n * ## A slot, and an empty one is an answer\n *\n * One plugin owns outside engines; it dispatches to whichever service a site\n * connected. Unlike the tax profile, an empty slot is a normal state — most\n * deployments carry no engine — so {@link pluginTaxEngine} answers `null`,\n * and a caller that wanted one prices the sale its usual way and says so.\n *\n * ## The engine is slow and outside, so the caller holds a deadline\n *\n * {@link quotePluginTaxEngine} never throws and never waits past its\n * deadline: a checkout that hung on a vendor would lose the sale, and one\n * that failed outright would lose it too. It answers what happened —\n * `unavailable`, `timeout` or `error` — so the caller can fall back to the\n * tax path it had before, flag the order, and log why.\n */\n\n/** A postal address as a tax engine reads it. `country` is ISO-3166 alpha-2. */\nexport interface PluginTaxAddress {\n  line1?: string\n  line2?: string\n  city?: string\n  /** State, province or region code, e.g. `TX`. */\n  region?: string\n  postalCode?: string\n  country: string\n}\n\n/** One taxable line of a basket. Money is integer cents in the request's currency. */\nexport interface PluginTaxEngineLine {\n  /** The caller's own id for the line, echoed back on the answer. */\n  id: string\n  /** The product the line sells, so the engine's plugin can find its tax code. */\n  productId?: string\n  variantId?: string\n  sku?: string\n  description?: string\n  quantity: number\n  /** The line's total after any discount on it, EXCLUSIVE of tax. */\n  amountCents: number\n  /** A tax code the caller already holds; otherwise the engine's plugin supplies one. */\n  taxCode?: string\n  /** A line the seller marked tax-exempt: quoted at zero whatever the engine says. */\n  exempt?: boolean\n}\n\n/** What a caller asks an engine. */\nexport interface PluginTaxEngineQuoteRequest {\n  hostId: string\n  /** ISO 4217, lower or upper case. */\n  currency: string\n  /** Where the sale happens: `pos` is in person, taxed at the site's own address. */\n  channel: 'online' | 'pos' | 'invoice'\n  lines: readonly PluginTaxEngineLine[]\n  /**\n   * A discount on the whole basket, spread by the engine's plugin across the\n   * lines that are not exempt. Line-level discounts are already inside each\n   * line's `amountCents`.\n   */\n  discountCents?: number\n  /** Shipping charged, when the caller wants it quoted. */\n  shippingCents?: number\n  /** The destination. Absent or `null`, the engine taxes at the site's own address. */\n  shipTo?: PluginTaxAddress | null\n  /** The buyer, so an exemption the merchant recorded for them applies. */\n  customer?: { email?: string | null; id?: string | null }\n}\n\n/** One line of an answer. */\nexport interface PluginTaxEngineQuoteLine {\n  id: string\n  taxCents: number\n}\n\n/** What an engine answered. Every figure is integer cents. */\nexport interface PluginTaxEngineQuote {\n  /** The engine's id, e.g. `avalara`. */\n  provider: string\n  /** Its name in the merchant's words, e.g. `Avalara AvaTax`. */\n  providerLabel: string\n  taxCents: number\n  lines: readonly PluginTaxEngineQuoteLine[]\n  shippingTaxCents: number\n  /** Whether the answer came from the engine's test environment. */\n  sandbox: boolean\n}\n\n/** Whether a site has an engine connected. */\nexport interface PluginTaxEngineStatus {\n  connected: boolean\n  provider?: string\n  providerLabel?: string\n  sandbox?: boolean\n}\n\n/** An engine's reading of an address. */\nexport interface PluginTaxAddressValidation {\n  valid: boolean\n  /** The address as the engine normalized it, when it could. */\n  normalized: PluginTaxAddress | null\n  /** What the engine said about it, in its own words. */\n  messages: readonly string[]\n}\n\nexport interface PluginTaxEngine {\n  status(hostId: string): Promise<PluginTaxEngineStatus>\n  /** THROWS on any failure: no connection, a refusal, a network error. */\n  quote(request: PluginTaxEngineQuoteRequest): Promise<PluginTaxEngineQuote>\n  /** THROWS when no engine is connected for the site or the engine fails. */\n  validateAddress(\n    hostId: string,\n    address: PluginTaxAddress,\n  ): Promise<PluginTaxAddressValidation>\n}\n\nexport const PLUGIN_TAX_ENGINE = definePluginServiceContract<PluginTaxEngine>(\n  'core.tax-engine',\n  { multiple: false },\n)\n\n/** Registers the plugin that answers for outside tax engines. */\nexport function registerPluginTaxEngine(\n  engine: PluginTaxEngine,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_TAX_ENGINE, engine, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The engine's plugin, or `null` when no plugin registered one. */\nexport function pluginTaxEngine(): PluginTaxEngine | null {\n  return resolvePluginServices(PLUGIN_TAX_ENGINE)[0]?.impl ?? null\n}\n\n/** How long a quote may take before the caller prices the sale without it. */\nexport const PLUGIN_TAX_ENGINE_QUOTE_TIMEOUT_MS = 5_000\n\n/** What {@link quotePluginTaxEngine} came to. */\nexport type PluginTaxEngineQuoteOutcome =\n  | { ok: true; quote: PluginTaxEngineQuote }\n  | {\n      ok: false\n      /** No engine plugin, or none connected for the site. */\n      reason: 'unavailable' | 'timeout' | 'error'\n      message: string\n    }\n\n/**\n * Asks the engine for a quote within a deadline. Never throws: see the\n * module note on why the caller, not the engine, holds the clock.\n */\nexport async function quotePluginTaxEngine(\n  request: PluginTaxEngineQuoteRequest,\n  options: { timeoutMs?: number } = {},\n): Promise<PluginTaxEngineQuoteOutcome> {\n  const engine = pluginTaxEngine()\n  if (!engine) {\n    return {\n      ok: false,\n      reason: 'unavailable',\n      message: 'no tax engine plugin is registered',\n    }\n  }\n  const timeoutMs = Math.max(1, options.timeoutMs ?? PLUGIN_TAX_ENGINE_QUOTE_TIMEOUT_MS)\n  let timer: ReturnType<typeof setTimeout> | undefined\n  const deadline = new Promise<PluginTaxEngineQuoteOutcome>((resolve) => {\n    timer = setTimeout(\n      () =>\n        resolve({\n          ok: false,\n          reason: 'timeout',\n          message: `the tax engine did not answer within ${timeoutMs} ms`,\n        }),\n      timeoutMs,\n    )\n  })\n  const asked = Promise.resolve()\n    .then(() => engine.quote(request))\n    .then(\n      (quote): PluginTaxEngineQuoteOutcome => ({ ok: true, quote }),\n      (error: unknown): PluginTaxEngineQuoteOutcome => ({\n        ok: false,\n        reason: 'error',\n        message: String((error as Error)?.message ?? error).slice(0, 300),\n      }),\n    )\n  try {\n    return await Promise.race([asked, deadline])\n  } finally {\n    if (timer) clearTimeout(timer)\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_TAX_PROFILE","multiple","registerPluginTaxProfile","profile","options","pluginId","pluginTaxProfileOwner","pluginTaxProfile","entry","Error","impl","PLUGIN_TAX_ENGINE","registerPluginTaxEngine","engine","pluginTaxEngine","PLUGIN_TAX_ENGINE_QUOTE_TIMEOUT_MS","quotePluginTaxEngine","request","ok","reason","message","timeoutMs","Math","max","timer","deadline","Promise","resolve","setTimeout","asked","then","quote","error","String","slice","race","clearTimeout"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAoF1B,OAAO,MAAMC,qBAAqBH,4BAChC,oBACA;IAAEI,UAAU;AAAM,GACnB;AAED,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,OAAyB,EACzBC,OAA+B;IAE/BN,sBAAsBE,oBAAoBG,SAAS,aAC7CC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,2EAA2E,GAC3E,OAAO,SAASC;;QACPP;IAAP,gBAAOA,0BAAAA,sBAAsBC,mBAAmB,CAAC,EAAE,qBAA5CD,wBAA8CM,QAAQ,mBAAI;AACnE;AAEA,6EAA6E,GAC7E,OAAO,SAASE;IACd,MAAMC,QAAQT,sBAAsBC,mBAAmB,CAAC,EAAE;IAC1D,IAAI,CAACQ,OAAO;QACV,MAAM,IAAIC,MACR,0EACE;IAEN;IACA,OAAOD,MAAME,IAAI;AACnB;AA2IA,OAAO,MAAMC,oBAAoBd,4BAC/B,mBACA;IAAEI,UAAU;AAAM,GACnB;AAED,+DAA+D,GAC/D,OAAO,SAASW,wBACdC,MAAuB,EACvBT,OAA+B;IAE/BN,sBAAsBa,mBAAmBE,QAAQ,aAC3CT,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,kEAAkE,GAClE,OAAO,SAASS;;QACPf;IAAP,gBAAOA,0BAAAA,sBAAsBY,kBAAkB,CAAC,EAAE,qBAA3CZ,wBAA6CW,IAAI,mBAAI;AAC9D;AAEA,4EAA4E,GAC5E,OAAO,MAAMK,qCAAqC,KAAK;AAYvD;;;CAGC,GACD,OAAO,eAAeC,qBACpBC,OAAoC,EACpCb,UAAkC,CAAC,CAAC;QAUNA;IAR9B,MAAMS,SAASC;IACf,IAAI,CAACD,QAAQ;QACX,OAAO;YACLK,IAAI;YACJC,QAAQ;YACRC,SAAS;QACX;IACF;IACA,MAAMC,YAAYC,KAAKC,GAAG,CAAC,IAAGnB,qBAAAA,QAAQiB,SAAS,YAAjBjB,qBAAqBW;IACnD,IAAIS;IACJ,MAAMC,WAAW,IAAIC,QAAqC,CAACC;QACzDH,QAAQI,WACN,IACED,QAAQ;gBACNT,IAAI;gBACJC,QAAQ;gBACRC,SAAS,CAAC,qCAAqC,EAAEC,UAAU,GAAG,CAAC;YACjE,IACFA;IAEJ;IACA,MAAMQ,QAAQH,QAAQC,OAAO,GAC1BG,IAAI,CAAC,IAAMjB,OAAOkB,KAAK,CAACd,UACxBa,IAAI,CACH,CAACC,QAAwC,CAAA;YAAEb,IAAI;YAAMa;QAAM,CAAA,GAC3D,CAACC;;eAAiD;YAChDd,IAAI;YACJC,QAAQ;YACRC,SAASa,eAAQD,yBAAD,AAACA,MAAiBZ,OAAO,mBAAIY,OAAOE,KAAK,CAAC,GAAG;QAC/D;;IAEJ,IAAI;QACF,OAAO,MAAMR,QAAQS,IAAI,CAAC;YAACN;YAAOJ;SAAS;IAC7C,SAAU;QACR,IAAID,OAAOY,aAAaZ;IAC1B;AACF"}

package/src/lib/plugin-manager/plugin-theme-font-catalog.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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 { HostThemeFontCategory, HostThemeFontMetrics } from '@aglyn/shared-data-types';
+/**
+ * What a published page needs to know about a font family a theme names
+ * (AGL-3656), asked of whichever plugin catalogs fonts rather than read off a
+ * list in core.
+ *
+ * The page loads only the weights and italics a family really offers — a
+ * theme asking for an 800 the family does not have would otherwise get the
+ * browser's nearest face, or a synthesized bold — and sizes a local fallback
+ * face to the family's own metrics, so nothing moves when the web font swaps
+ * in. With no catalog registered, a page loads what the theme lists and
+ * swaps with no metric-matched fallback, which is what every page did before.
+ */
+export interface ThemeFontFacts {
+    family: string;
+    category: HostThemeFontCategory;
+    /** The upright weights the family offers. */
+    weights: number[];
+    /** The italic weights the family offers. */
+    italics: number[];
+    /**
+     * The weight range of the family's variable font, when it has one. Such a
+     * family can be served as one file holding every weight or as a file per
+     * weight, and the page picks whichever is smaller for the weights it uses.
+     */
+    variableWeights?: [number, number];
+    /** Of the regular face; absent when the catalog could not read them. */
+    metrics?: HostThemeFontMetrics;
+}
+export interface PluginThemeFontCatalog {
+    /** The family's facts, matched case-insensitively, or undefined when unknown. */
+    facts(family: string): Promise<ThemeFontFacts | undefined>;
+}
+export declare const PLUGIN_THEME_FONT_CATALOG: import("./plugin-services").PluginServiceContract<PluginThemeFontCatalog>;
+export declare function registerPluginThemeFontCatalog(catalog: PluginThemeFontCatalog, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * A family's facts from the registered catalog; undefined when no plugin
+ * catalogs fonts, the family is not in it, or the catalog failed. Never
+ * throws: a page renders without a fact rather than without its theme.
+ */
+export declare function themeFontFacts(family: string): Promise<ThemeFontFacts | undefined>;

package/src/lib/plugin-manager/plugin-theme-font-catalog.js

@@ -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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { definePluginServiceContract, registerPluginService, resolvePluginService } from "./plugin-services.js";
+export const PLUGIN_THEME_FONT_CATALOG = definePluginServiceContract('core.theme.fontCatalog', {
+    multiple: false
+});
+export function registerPluginThemeFontCatalog(catalog, options) {
+    registerPluginService(PLUGIN_THEME_FONT_CATALOG, catalog, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/**
+ * A family's facts from the registered catalog; undefined when no plugin
+ * catalogs fonts, the family is not in it, or the catalog failed. Never
+ * throws: a page renders without a fact rather than without its theme.
+ */ export async function themeFontFacts(family) {
+    const catalog = resolvePluginService(PLUGIN_THEME_FONT_CATALOG);
+    if (!catalog) return undefined;
+    try {
+        return await catalog.facts(family);
+    } catch (unused) {
+        return undefined;
+    }
+}
+
+//# sourceMappingURL=plugin-theme-font-catalog.js.map

package/src/lib/plugin-manager/plugin-theme-font-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-theme-font-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 type {\n  HostThemeFontCategory,\n  HostThemeFontMetrics,\n} from '@aglyn/shared-data-types'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginService,\n} from './plugin-services'\n\n/**\n * What a published page needs to know about a font family a theme names\n * (AGL-3656), asked of whichever plugin catalogs fonts rather than read off a\n * list in core.\n *\n * The page loads only the weights and italics a family really offers — a\n * theme asking for an 800 the family does not have would otherwise get the\n * browser's nearest face, or a synthesized bold — and sizes a local fallback\n * face to the family's own metrics, so nothing moves when the web font swaps\n * in. With no catalog registered, a page loads what the theme lists and\n * swaps with no metric-matched fallback, which is what every page did before.\n */\nexport interface ThemeFontFacts {\n  family: string\n  category: HostThemeFontCategory\n  /** The upright weights the family offers. */\n  weights: number[]\n  /** The italic weights the family offers. */\n  italics: number[]\n  /**\n   * The weight range of the family's variable font, when it has one. Such a\n   * family can be served as one file holding every weight or as a file per\n   * weight, and the page picks whichever is smaller for the weights it uses.\n   */\n  variableWeights?: [number, number]\n  /** Of the regular face; absent when the catalog could not read them. */\n  metrics?: HostThemeFontMetrics\n}\n\nexport interface PluginThemeFontCatalog {\n  /** The family's facts, matched case-insensitively, or undefined when unknown. */\n  facts(family: string): Promise<ThemeFontFacts | undefined>\n}\n\nexport const PLUGIN_THEME_FONT_CATALOG =\n  definePluginServiceContract<PluginThemeFontCatalog>('core.theme.fontCatalog', {\n    multiple: false,\n  })\n\nexport function registerPluginThemeFontCatalog(\n  catalog: PluginThemeFontCatalog,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_THEME_FONT_CATALOG, catalog, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/**\n * A family's facts from the registered catalog; undefined when no plugin\n * catalogs fonts, the family is not in it, or the catalog failed. Never\n * throws: a page renders without a fact rather than without its theme.\n */\nexport async function themeFontFacts(\n  family: string,\n): Promise<ThemeFontFacts | undefined> {\n  const catalog = resolvePluginService(PLUGIN_THEME_FONT_CATALOG)\n  if (!catalog) return undefined\n  try {\n    return await catalog.facts(family)\n  } catch {\n    return undefined\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginService","PLUGIN_THEME_FONT_CATALOG","multiple","registerPluginThemeFontCatalog","catalog","options","pluginId","themeFontFacts","family","undefined","facts"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAMD,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAoC1B,OAAO,MAAMC,4BACXH,4BAAoD,0BAA0B;IAC5EI,UAAU;AACZ,GAAE;AAEJ,OAAO,SAASC,+BACdC,OAA+B,EAC/BC,OAA+B;IAE/BN,sBAAsBE,2BAA2BG,SAAS,aACpDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA;;;;CAIC,GACD,OAAO,eAAeC,eACpBC,MAAc;IAEd,MAAMJ,UAAUJ,qBAAqBC;IACrC,IAAI,CAACG,SAAS,OAAOK;IACrB,IAAI;QACF,OAAO,MAAML,QAAQM,KAAK,CAACF;IAC7B,EAAE,eAAM;QACN,OAAOC;IACT;AACF"}

package/src/lib/plugin-manager/plugin-tracking-pages.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 branded tracking page for a parcel, offered by another plugin
+ * (AGL-3635).
+ *
+ * A seller links each shipment to the carrier's own tracker. A merchant who
+ * follows parcels through a tracking service has a page of their own for it
+ * — their logo, their help links, their other products — and wants buyers
+ * sent there instead. A plugin that knows such a page registers here; the
+ * seller asks before it draws a shipment for a buyer, and keeps the
+ * carrier's link when nobody answers.
+ *
+ * The words are a parcel's: a site, the record it shipped for, a carrier and
+ * a number. Import this module by its own subpath
+ * (`@aglyn/aglyn/plugin-manager/plugin-tracking-pages`); it is not in the
+ * barrel.
+ */
+export interface PluginTrackingPageRequest {
+    hostId: string;
+    recordId: string;
+    /** The carrier as the record names it: free text. */
+    carrier?: string | null;
+    trackingNumber: string;
+    signal?: AbortSignal;
+}
+/** The page's URL, or `null` when this plugin has none for that parcel. */
+export type PluginTrackingPageProvider = (request: PluginTrackingPageRequest) => Promise<string | null>;
+/** Joins the providers. Re-registering under the same plugin replaces its own. */
+export declare function registerPluginTrackingPage(provider: PluginTrackingPageProvider, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * The first provider's page for each parcel, asked together and given up
+ * on after `timeoutMs`. Answers a map from tracking number to an `https:`
+ * URL; a parcel no provider answered for is absent, and the seller keeps
+ * its own link. Never throws.
+ */
+export declare function resolvePluginTrackingPages(requests: ReadonlyArray<Omit<PluginTrackingPageRequest, 'signal'>>, options: {
+    timeoutMs: number;
+}): Promise<Map<string, string>>;