@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/model/commerce-tax.js

@@ -0,0 +1,92 @@
+/**
+ * @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.
+ */ /**
+ * Taxes v1 (AGL-285): manual rates per region resolved most-specific
+ * first (country+state beats country), or Stripe Tax automatic
+ * calculation when the host opts in. Settings live on the
+ * `hosts/{hostId}/settings/store` doc under `tax`. Pure — checkout and
+ * POS call these; Stripe Tax mode bypasses them entirely.
+ */ /**
+ * The highest percentage this accepts. A rate above 100% is a decimal-point
+ * typo (`825` for `8.25`), not a jurisdiction, and multiplying a guest's
+ * deposit by nine because of one is a far worse failure than collecting
+ * nothing. Out of range resolves to OFF rather than being clamped to a number
+ * the merchant did not choose — and the editor says so on screen, so the
+ * refusal is never silent.
+ */ export const FLAT_TAX_MAX_PCT = 100;
+/** True when a typed percentage is one this will actually apply. */ export function isUsableFlatTaxPct(pct) {
+    const value = Number(pct);
+    return Number.isFinite(value) && value > 0 && value <= FLAT_TAX_MAX_PCT;
+}
+/**
+ * Tax cents for a flat merchant rate on one charged amount, EXCLUSIVE — added
+ * on top of the price, never back-calculated out of it.
+ *
+ * `pricesIncludeTax` is deliberately not consulted: it is a goods-pricing
+ * setting, and honouring it here would mean a merchant types a lodging rate,
+ * saves, and the guest's total does not move — a setting that reads as
+ * configured while collecting nothing is the AGL-1999 failure restated.
+ *
+ * Pure and total. Unusable input answers zero and never throws.
+ */ export function resolveFlatTaxCents(rate, chargeCents, fallbackLabel) {
+    const pct = Number(rate == null ? void 0 : rate.pct);
+    if (!isUsableFlatTaxPct(pct)) return {
+        taxCents: 0,
+        label: '',
+        pct: 0
+    };
+    const taxCents = computeTaxCents(chargeCents, pct, false);
+    if (!(taxCents > 0)) return {
+        taxCents: 0,
+        label: '',
+        pct: 0
+    };
+    return {
+        taxCents,
+        label: ((rate == null ? void 0 : rate.label) || fallbackLabel).slice(0, 120),
+        pct
+    };
+}
+/** Most-specific matching rate, or null (no tax). */ export function resolveTaxRate(settings, address) {
+    var _address_country, _address_state, _settings_rates;
+    if (!settings || settings.mode === 'stripe') return null;
+    const country = ((_address_country = address.country) != null ? _address_country : '').toUpperCase();
+    const state = ((_address_state = address.state) != null ? _address_state : '').toUpperCase();
+    if (!country) return null;
+    let match = null;
+    for (const rate of (_settings_rates = settings.rates) != null ? _settings_rates : []){
+        if (rate.country.toUpperCase() !== country) continue;
+        if (rate.state) {
+            if (rate.state.toUpperCase() === state) return rate;
+            continue;
+        }
+        match = match != null ? match : rate;
+    }
+    return match;
+}
+/**
+ * Tax cents for a taxable amount. Exclusive pricing adds on top;
+ * inclusive pricing back-calculates the contained tax (for receipts —
+ * the charge total does not change).
+ */ export function computeTaxCents(taxableCents, pct, pricesIncludeTax = false) {
+    if (!(pct > 0) || !(taxableCents > 0)) return 0;
+    if (pricesIncludeTax) {
+        return Math.round(taxableCents - taxableCents / (1 + pct / 100));
+    }
+    return Math.round(taxableCents * pct / 100);
+}
+
+//# sourceMappingURL=commerce-tax.js.map

package/src/lib/model/commerce-tax.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-tax.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\n/**\n * Taxes v1 (AGL-285): manual rates per region resolved most-specific\n * first (country+state beats country), or Stripe Tax automatic\n * calculation when the host opts in. Settings live on the\n * `hosts/{hostId}/settings/store` doc under `tax`. Pure — checkout and\n * POS call these; Stripe Tax mode bypasses them entirely.\n */\n\nexport interface TaxRate {\n  /** ISO-3166 alpha-2, e.g. 'US'. */\n  country: string\n  /** Region/state code, e.g. 'TX'; absent = whole country. */\n  state?: string\n  /** Percent, e.g. 8.25. */\n  pct: number\n  /** Receipt label, e.g. 'TX sales tax'. */\n  label?: string\n}\n\n/**\n * A FLAT, merchant-entered rate for a regime the goods sales-tax machinery\n * above does not describe (AGL-1969 lodging, AGL-2028 services).\n *\n * ## Why this is not another `TaxRate`\n *\n * `rates[]` is a SALES tax table resolved against an address, most-specific\n * first. Lodging (occupancy/hotel tax) and service tax are separate regimes\n * with their own rates, their own registration and their own return, and the\n * number a merchant typed into the goods table is not the right number for a\n * night or an appointment. Reading `rates[]` for either would be confidently\n * wrong rather than merely absent — which is exactly why `reserve.ts` and\n * `bookings/server.ts` charged nothing at all until the merchant was given a\n * field of their own to answer in.\n *\n * ## Off is the default and the default is load-bearing\n *\n * An absent, zero, negative, non-finite or out-of-range `pct` resolves to\n * ZERO. Nothing an existing merchant is charging today moves because this\n * shipped; a rate applies only once a merchant has typed one and saved.\n *\n * ## It is always MANUAL, in every store mode\n *\n * Deliberately independent of `TaxSettings.mode`. Stripe Tax cannot compute\n * either regime from these sessions — it needs a lodging or service tax code\n * no handler here sends — so a `mode: 'stripe'` store would otherwise have no\n * way to collect them at all. Riding as an ordinary line item makes the\n * derived `taxMode` read `manual`: the merchant's own rate, never computed\n * against Aglyn's registrations (AGL-1904).\n *\n * ## Aglyn takes NO position on what is owed\n *\n * This is a calculator the merchant configures, records and can read back. It\n * states no view on whether a jurisdiction imposes the tax, on who must\n * register, or on who must remit — those attach by operation of law and\n * belong to counsel (AGL-1904).\n *\n * ⚠️ The sentence that used to stand here — \"Terms §10.3 already puts the\n * question on the merchant\" — is FALSE as of 2026-08-24 (AGL-1956). Aglyn\n * accepts marketplace-facilitator status, ToS §10.3 no longer assigns sales\n * tax to the merchant, and the new ToS §10.7 says Aglyn calculates, collects\n * and remits it WHERE IT HAS A FACILITATOR OBLIGATION. Do not cite §10.3 as\n * authority for merchant-facing tax copy again.\n *\n * What is still true, and is why this module did not change: these FLAT RATES\n * are the manual/lodging/service path, which never touches Aglyn's\n * registrations and is not what §10.7 covers. The rates a merchant types here\n * remain theirs to determine.\n *\n * The merchant-facing copy this note used to call an OWED follow-up is DONE.\n * `storefront-tax-summary-card.component.tsx` said \"Aglyn does not make that\n * determination for you\" and was rewritten to §10.7 in `f7e5465f5`.\n * `tax-settings-card.component.tsx` was read and needed no change — it governs\n * exactly these flat lodging/service rates, which §10.7 does not reach, so it\n * was already saying the right thing about the right taxes. Recorded rather\n * than deleted: the next reader should not have to re-derive that the second\n * card's silence is correct rather than overlooked.\n */\nexport interface FlatTaxRate {\n  /** Percent, e.g. 6. Absent or non-positive = off, which is the default. */\n  pct?: number\n  /** Receipt label, e.g. 'Occupancy tax'. */\n  label?: string\n}\n\n/** What a flat rate resolved to for one charge. */\nexport interface ResolvedFlatTax {\n  taxCents: number\n  /** The label to put on the receipt line; empty when there is no tax. */\n  label: string\n  /** The percentage actually applied — 0 when the rate is off or invalid. */\n  pct: number\n}\n\n/**\n * The highest percentage this accepts. A rate above 100% is a decimal-point\n * typo (`825` for `8.25`), not a jurisdiction, and multiplying a guest's\n * deposit by nine because of one is a far worse failure than collecting\n * nothing. Out of range resolves to OFF rather than being clamped to a number\n * the merchant did not choose — and the editor says so on screen, so the\n * refusal is never silent.\n */\nexport const FLAT_TAX_MAX_PCT = 100\n\n/** True when a typed percentage is one this will actually apply. */\nexport function isUsableFlatTaxPct(pct: unknown): boolean {\n  const value = Number(pct)\n  return Number.isFinite(value) && value > 0 && value <= FLAT_TAX_MAX_PCT\n}\n\n/**\n * Tax cents for a flat merchant rate on one charged amount, EXCLUSIVE — added\n * on top of the price, never back-calculated out of it.\n *\n * `pricesIncludeTax` is deliberately not consulted: it is a goods-pricing\n * setting, and honouring it here would mean a merchant types a lodging rate,\n * saves, and the guest's total does not move — a setting that reads as\n * configured while collecting nothing is the AGL-1999 failure restated.\n *\n * Pure and total. Unusable input answers zero and never throws.\n */\nexport function resolveFlatTaxCents(\n  rate: FlatTaxRate | undefined | null,\n  chargeCents: number,\n  fallbackLabel: string,\n): ResolvedFlatTax {\n  const pct = Number(rate?.pct)\n  if (!isUsableFlatTaxPct(pct)) return { taxCents: 0, label: '', pct: 0 }\n  const taxCents = computeTaxCents(chargeCents, pct, false)\n  if (!(taxCents > 0)) return { taxCents: 0, label: '', pct: 0 }\n  return {\n    taxCents,\n    label: (rate?.label || fallbackLabel).slice(0, 120),\n    pct,\n  }\n}\n\nexport interface TaxSettings {\n  /**\n   * 'manual' rates below, 'stripe' for Stripe Tax automatic, or 'none' —\n   * an EXPLICIT decision not to collect (AGL-1999). `undefined` is not a\n   * fourth mode: it means nobody has decided, and `storefrontTaxDecision`\n   * refuses the sale rather than zero-rating it silently.\n   */\n  mode?: 'manual' | 'stripe' | 'none'\n  /** Displayed prices already include tax (VAT-style). */\n  pricesIncludeTax?: boolean\n  /**\n   * Store origin (AGL-285): the legacy single-product checkout taxes by\n   * origin because the buyer address arrives inside Stripe Checkout;\n   * Checkout v2 (AGL-296) collects the address first and taxes by\n   * destination.\n   */\n  origin?: TaxAddress\n  rates?: TaxRate[]\n  /**\n   * OCCUPANCY / LODGING tax on a reservation deposit (AGL-1969). Off unless\n   * the merchant sets it — see `FlatTaxRate`. Read by `reserve.ts` only.\n   */\n  lodging?: FlatTaxRate\n  /**\n   * SERVICE tax on a paid booking (AGL-2028). Off unless the merchant sets\n   * it — see `FlatTaxRate`. Read by the bookings plugin only.\n   *\n   * ITS EXISTENCE IS THE OPT-IN. AGL-2000 declined to apply the goods\n   * `rates[]` to an appointment partly because nothing said the merchant\n   * meant those settings to cover bookings — they are another plugin's\n   * surface. A field of its own, labelled for services and blank until\n   * somebody fills it in, is the merchant saying so explicitly. Reading\n   * `rates[]` for a booking is still wrong and still nothing does it.\n   */\n  service?: FlatTaxRate\n}\n\nexport interface TaxAddress {\n  country?: string\n  state?: string\n}\n\n/** Most-specific matching rate, or null (no tax). */\nexport function resolveTaxRate(\n  settings: TaxSettings | undefined,\n  address: TaxAddress,\n): TaxRate | null {\n  if (!settings || settings.mode === 'stripe') return null\n  const country = (address.country ?? '').toUpperCase()\n  const state = (address.state ?? '').toUpperCase()\n  if (!country) return null\n  let match: TaxRate | null = null\n  for (const rate of settings.rates ?? []) {\n    if (rate.country.toUpperCase() !== country) continue\n    if (rate.state) {\n      if (rate.state.toUpperCase() === state) return rate\n      continue\n    }\n    match = match ?? rate\n  }\n  return match\n}\n\n/**\n * Tax cents for a taxable amount. Exclusive pricing adds on top;\n * inclusive pricing back-calculates the contained tax (for receipts —\n * the charge total does not change).\n */\nexport function computeTaxCents(\n  taxableCents: number,\n  pct: number,\n  pricesIncludeTax = false,\n): number {\n  if (!(pct > 0) || !(taxableCents > 0)) return 0\n  if (pricesIncludeTax) {\n    return Math.round(taxableCents - taxableCents / (1 + pct / 100))\n  }\n  return Math.round((taxableCents * pct) / 100)\n}\n"],"names":["FLAT_TAX_MAX_PCT","isUsableFlatTaxPct","pct","value","Number","isFinite","resolveFlatTaxCents","rate","chargeCents","fallbackLabel","taxCents","label","computeTaxCents","slice","resolveTaxRate","settings","address","mode","country","toUpperCase","state","match","rates","taxableCents","pricesIncludeTax","Math","round"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;CAMC,GAuFD;;;;;;;CAOC,GACD,OAAO,MAAMA,mBAAmB,IAAG;AAEnC,kEAAkE,GAClE,OAAO,SAASC,mBAAmBC,GAAY;IAC7C,MAAMC,QAAQC,OAAOF;IACrB,OAAOE,OAAOC,QAAQ,CAACF,UAAUA,QAAQ,KAAKA,SAASH;AACzD;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASM,oBACdC,IAAoC,EACpCC,WAAmB,EACnBC,aAAqB;IAErB,MAAMP,MAAME,OAAOG,wBAAAA,KAAML,GAAG;IAC5B,IAAI,CAACD,mBAAmBC,MAAM,OAAO;QAAEQ,UAAU;QAAGC,OAAO;QAAIT,KAAK;IAAE;IACtE,MAAMQ,WAAWE,gBAAgBJ,aAAaN,KAAK;IACnD,IAAI,CAAEQ,CAAAA,WAAW,CAAA,GAAI,OAAO;QAAEA,UAAU;QAAGC,OAAO;QAAIT,KAAK;IAAE;IAC7D,OAAO;QACLQ;QACAC,OAAO,AAACJ,CAAAA,CAAAA,wBAAAA,KAAMI,KAAK,KAAIF,aAAY,EAAGI,KAAK,CAAC,GAAG;QAC/CX;IACF;AACF;AA4CA,mDAAmD,GACnD,OAAO,SAASY,eACdC,QAAiC,EACjCC,OAAmB;QAGFA,kBACFA,gBAGID;IALnB,IAAI,CAACA,YAAYA,SAASE,IAAI,KAAK,UAAU,OAAO;IACpD,MAAMC,UAAU,EAACF,mBAAAA,QAAQE,OAAO,YAAfF,mBAAmB,IAAIG,WAAW;IACnD,MAAMC,QAAQ,EAACJ,iBAAAA,QAAQI,KAAK,YAAbJ,iBAAiB,IAAIG,WAAW;IAC/C,IAAI,CAACD,SAAS,OAAO;IACrB,IAAIG,QAAwB;IAC5B,KAAK,MAAMd,SAAQQ,kBAAAA,SAASO,KAAK,YAAdP,kBAAkB,EAAE,CAAE;QACvC,IAAIR,KAAKW,OAAO,CAACC,WAAW,OAAOD,SAAS;QAC5C,IAAIX,KAAKa,KAAK,EAAE;YACd,IAAIb,KAAKa,KAAK,CAACD,WAAW,OAAOC,OAAO,OAAOb;YAC/C;QACF;QACAc,QAAQA,gBAAAA,QAASd;IACnB;IACA,OAAOc;AACT;AAEA;;;;CAIC,GACD,OAAO,SAAST,gBACdW,YAAoB,EACpBrB,GAAW,EACXsB,mBAAmB,KAAK;IAExB,IAAI,CAAEtB,CAAAA,MAAM,CAAA,KAAM,CAAEqB,CAAAA,eAAe,CAAA,GAAI,OAAO;IAC9C,IAAIC,kBAAkB;QACpB,OAAOC,KAAKC,KAAK,CAACH,eAAeA,eAAgB,CAAA,IAAIrB,MAAM,GAAE;IAC/D;IACA,OAAOuB,KAAKC,KAAK,CAAC,AAACH,eAAerB,MAAO;AAC3C"}

package/src/lib/model/commerce.d.ts

@@ -0,0 +1,551 @@
+/**
+ * @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.
+ */
+/**
+ * Commerce catalog v1 (AGL-276): products with options/variants,
+ * hierarchical categories, tags, and manual/smart collections. Pure
+ * model + helpers — no I/O; the products hub and storefront APIs operate
+ * over these shapes. Documents live under `hosts/{hostId}/products`,
+ * `.../productCategories`, and `.../collections`; the legacy Commerce
+ * Starter product doc (AGL-90: name/priceUsd/inventory) lifts into this
+ * shape via `liftLegacyProduct`, so existing docs keep working.
+ */
+/** Product price ceiling (whole USD). */
+export declare const COMMERCE_MAX_PRICE_USD = 10000;
+export type ProductType = 'physical' | 'digital' | 'service';
+export type ProductStatus = 'draft' | 'active' | 'archived';
+/** One axis of variation, e.g. { name: 'Size', values: ['S','M','L'] }. */
+export interface ProductOption {
+    name: string;
+    values: string[];
+}
+/** A sellable configuration of a product (every product has ≥ 1). */
+export interface ProductVariant {
+    /** Stable id unique within the product (never reused after delete). */
+    id: string;
+    /** Option selections keyed by option name; {} for the default variant. */
+    options?: Record<string, string>;
+    sku?: string;
+    barcode?: string;
+    priceUsd: number;
+    /** Strike-through price; a sale badge shows when > priceUsd. */
+    compareAtPriceUsd?: number;
+    weightGrams?: number;
+    /** null/undefined = untracked; 0 = sold out (matches AGL-96). */
+    inventory?: number | null;
+    /**
+     * Per-location stock (AGL-286); `inventory` stays the summed
+     * denormalization. Absent = single default location.
+     */
+    inventoryByLocation?: Record<string, number>;
+    /** Media-library image URL shown when this variant is selected. */
+    imageUrl?: string;
+}
+/** `hosts/{hostId}/locations/{id}` doc (AGL-286). */
+export interface InventoryLocation {
+    name: string;
+    isDefault?: boolean;
+    address?: string;
+}
+/**
+ * `hosts/{hostId}/registers/{id}` doc (AGL-472): a named point-of-sale
+ * register. Creation is capped by the plan's `posRegisters` quota (Pro 1,
+ * Business 2, Advanced 5; raised by a per-org entitlement override for the
+ * $89/mo add-on), enforced server-side by the resources route. Each POS
+ * sale stamps its `registerId` so takings are attributable per register.
+ */
+export interface PosRegister {
+    name: string;
+    /** Optional default inventory location this register sells from. */
+    locationId?: string;
+}
+/**
+ * The register ids within the plan's `posRegisters` cap (AGL-482), ranked
+ * by creation order — the same ordering `pos-order.ts` enforces at sale
+ * time. Registers beyond the cap (e.g. after a Business→Pro downgrade) are
+ * excluded so the console/POS can dim or hide them instead of surfacing a
+ * checkout 403. `cap` of `Infinity` returns all.
+ */
+export declare function registersWithinCap(registers: Array<{
+    $id: string;
+    createdAt?: any;
+}>, cap: number): Set<string>;
+/**
+ * `hosts/{hostId}/suppliers/{id}` doc (AGL-289): where dropshipped
+ * order lines route on payment. Email and webhook are both optional but
+ * one must be set for routing to do anything; webhook payloads are
+ * HMAC-SHA256-signed with `webhookSecret`.
+ */
+export interface HostSupplier {
+    name: string;
+    email?: string;
+    webhookUrl?: string;
+    webhookSecret?: string;
+}
+/** `hosts/{hostId}/products/{id}` doc. */
+export interface HostProduct {
+    name: string;
+    /** Host-unique URL segment for /products/{slug}. */
+    slug: string;
+    description?: string;
+    type: ProductType;
+    status: ProductStatus;
+    /** Ordered media-library image URLs (first = primary). */
+    mediaUrls?: string[];
+    categoryIds?: string[];
+    tags?: string[];
+    options?: ProductOption[];
+    variants: ProductVariant[];
+    /** Per-product overrides for PDP meta tags (AGL-299 consumes). */
+    seo?: {
+        title?: string;
+        description?: string;
+        imageUrl?: string;
+    };
+    /** Supplier for dropship routing (AGL-289). */
+    supplierId?: string;
+    /** Out-of-stock behavior (AGL-281): deny (default) or allow backorder. */
+    oversellPolicy?: 'deny' | 'backorder';
+    /** Never taxed regardless of tax settings (AGL-285). */
+    taxExempt?: boolean;
+    /**
+     * Digital delivery (AGL-302): downloadable files for `digital`
+     * products. Buyers always download the CURRENT list, so uploading a
+     * new version re-delivers to everyone.
+     */
+    digitalFiles?: Array<{
+        url: string;
+        fileName: string;
+        version?: string;
+    }>;
+    /** Max download attempts per order line; absent = unlimited. */
+    downloadLimit?: number;
+    /**
+     * Recurring billing (AGL-303): buyers subscribe instead of buying
+     * once; an active subscription is the entitlement content gating
+     * checks (AGL-309).
+     */
+    subscription?: {
+        interval: 'month' | 'year';
+        trialDays?: number;
+    };
+    /**
+     * Buyer-chosen billing (AGL-545): with `subscription` set, true lets
+     * the buyer pick one-time OR subscribe on the PDP (default one-time);
+     * absent/false keeps the product subscription-only.
+     */
+    subscriptionOptional?: boolean;
+    /** Members-only videos (AGL-315), streamed via short-TTL links. */
+    gatedVideos?: Array<{
+        url: string;
+        title?: string;
+    }>;
+    /** Manual related products for the upsell block (AGL-325). */
+    relatedProductIds?: string[];
+    /** Buying this issues a gift-card code for its price (AGL-322). */
+    giftCard?: boolean;
+    /** Tracked-total at/below this alerts host managers (AGL-281). */
+    lowStockThreshold?: number;
+    createdAtMs?: number;
+    updatedAtMs?: number;
+    deletedAt?: number | null;
+    /** Legacy Commerce Starter fields kept so old docs read back (AGL-90). */
+    priceUsd?: number;
+    inventory?: number | null;
+    imageUrl?: string;
+}
+/** `hosts/{hostId}/productCategories/{id}` doc (tree via parentId). */
+export interface ProductCategory {
+    name: string;
+    slug: string;
+    parentId?: string | null;
+    order?: number;
+}
+export type CollectionRuleField = 'tag' | 'categoryId' | 'priceUsd' | 'name' | 'type';
+export type CollectionRuleOp = 'eq' | 'neq' | 'lt' | 'gt' | 'contains';
+export interface CollectionRule {
+    field: CollectionRuleField;
+    op: CollectionRuleOp;
+    value: string | number;
+}
+/** `hosts/{hostId}/collections/{id}` doc. */
+export interface HostCollection {
+    name: string;
+    slug: string;
+    description?: string;
+    mode: 'manual' | 'smart';
+    /** Manual mode: explicit ordered membership. */
+    productIds?: string[];
+    /** Smart mode: rules evaluated over active products. */
+    rules?: CollectionRule[];
+    /** Smart mode: true = every rule must match (default), false = any. */
+    matchAll?: boolean;
+    /** Media-library image URL for the collection card/landing hero. */
+    imageUrl?: string;
+    order?: number;
+}
+/**
+ * Payment-provider seam (AGL-284): checkout/session creation goes
+ * through a provider id so PayPal (etc.) can slot in without reworking
+ * callers. Stripe is the only implementation today; store settings
+ * (AGL-295) will carry the selection when a second provider exists.
+ */
+export type PaymentProviderId = 'stripe';
+export interface PaymentCheckoutRequest {
+    provider: PaymentProviderId;
+    hostId: string;
+    amountCents: number;
+    feeCents: number;
+    productName: string;
+    successUrl: string;
+    cancelUrl: string;
+    metadata?: Record<string, string>;
+}
+/** Variant ceiling per product (Shopify parity). */
+export declare const COMMERCE_MAX_VARIANTS = 100;
+export declare const COMMERCE_MAX_OPTIONS = 3;
+export declare const COMMERCE_MAX_OPTION_VALUES = 25;
+export declare const COMMERCE_SLUG_MAX_LENGTH = 80;
+/** Lowercase-kebab slug from a product/category/collection name. */
+export declare function commerceSlug(name: string): string;
+/**
+ * The search keys a product write carries, so the catalog can be searched by
+ * the QUERY rather than by the rows a listener happened to fetch (AGL-2501).
+ *
+ * The hub lists `limit(500)`, and the search compared what that returned — so
+ * a product past the window answered "no products match", which reads as the
+ * product not existing rather than as the search not reaching it. Filtering
+ * server-side needs fields Firestore can index, and neither of the two things
+ * a merchant searches by is one:
+ *
+ *   - A NAME needs case-insensitive contains, which Firestore has no operator
+ *     for. `nameSearchFields` denormalizes it into the three shapes that are
+ *     indexable — an exact key, word-prefix tokens for `array-contains`, and
+ *     the key reversed so "ends with" becomes a prefix range.
+ *   - A SKU lives inside `variants`, an array of OBJECTS, and Firestore cannot
+ *     query a field inside one. Flattened here into a top-level array so a SKU
+ *     is one `array-contains`.
+ *
+ * ⛔ A SKU therefore matches WHOLE, not as a substring: "abc-123" finds it and
+ * "123" does not. That is the right way round for a SKU, which is a value
+ * somebody copies rather than half-remembers — unlike a name, where the tokens
+ * above buy word-prefix matching precisely because names are half-remembered.
+ *
+ * `barcodes` is the same flattening for the same reason, and it is the one the
+ * register depends on: a keyboard-wedge scanner types the code and presses
+ * Enter, so the lookup has to be exact and has to reach the whole catalog. A
+ * scan is never a half-remembered value.
+ *
+ * Lower-cased because the translator lower-cases the typed query before it
+ * builds the `array-contains`; stored and typed have to be normalized the same
+ * way or the two silently disagree.
+ *
+ * ⚠️ Each array is OMITTED when a product has none, rather than written as
+ * `[]`. `isNotEmpty` is served as `!= null`, and an empty array is not null —
+ * so a product with no SKUs at all would answer "has a SKU" for every row.
+ *
+ * ⚠️ Spread this at EVERY write that sets a product's name or variants. A
+ * write that sets the name without it leaves the keys describing the previous
+ * name, and the product becomes findable only by what it used to be called.
+ */
+export declare function productSearchFields(product: {
+    name: string;
+    variants?: ProductVariant[];
+}): {
+    name: string;
+    nameLower: string;
+    nameTokens: string[];
+    nameReversed: string;
+    skus?: string[];
+    barcodes?: string[];
+};
+/**
+ * Cartesian product of option values → the variant option combinations
+ * the products hub materializes into a variants matrix. Empty/absent
+ * options yield a single default combination ({}).
+ */
+export declare function expandVariantMatrix(options: ProductOption[] | undefined): Array<Record<string, string>>;
+/**
+ * The option axes renamed, with every variant's selection carried to the new
+ * name in place (AGL-3066).
+ *
+ * A variant keeps its selections keyed by option NAME, so a rename has to move
+ * each key rather than rebuild the matrix: a rebuild matches variants by name
+ * and value, finds none under the new name, and replaces every variant with a
+ * new id holding the first variant's price and stock and no SKU, barcode,
+ * compare-at price or weight. Moving the key keeps the id every order line
+ * and stock movement refers to, and every field a person set.
+ *
+ * `names` holds one entry per option, in order; an entry that is not a string
+ * keeps that option's name. Each selection keeps its position among a
+ * variant's selections, because a variant is labeled by them in order.
+ *
+ * Two options may share a name for a moment while a person types. A variant
+ * cannot hold two selections under one name, so while the new names are not
+ * all different nothing is moved, and `validateProduct` refuses the product.
+ * The selection left under the old name is found again by its value once the
+ * names differ, so typing through a duplicate loses nothing.
+ */
+export declare function renameProductOptions(product: Pick<HostProduct, 'options' | 'variants'>, names: ReadonlyArray<string | null | undefined>): Pick<HostProduct, 'options' | 'variants'>;
+/**
+ * Whether a variant has a price a sale can charge (AGL-2916).
+ *
+ * A product proposed by AI is created with every price left empty for the
+ * merchant to set, so a stored variant can lack one. `Number(undefined)` is
+ * no price, and neither is `null`, which `Number` reads as zero: a sale door
+ * that priced either would charge nothing, or fail at the processor.
+ */
+export declare function variantHasPrice(variant: object | null | undefined): boolean;
+/** Whether any variant of a product still needs its price set (AGL-2916). */
+export declare function productPriceMissing(product: {
+    variants?: readonly object[];
+}): boolean;
+/** Copy proposed for a product, by field (AGL-2916). A field left out is left alone. */
+export interface ProductCopyValues {
+    description?: string;
+    tags?: string[];
+    categoryIds?: string[];
+    /** One name per option the product has, in order. */
+    optionNames?: string[];
+    seoTitle?: string;
+    seoDescription?: string;
+}
+/**
+ * The fields proposed copy changes on a product (AGL-2916), in the shape the
+ * editor stores them: only the fields `values` names. Tags and categories are
+ * each kept once; the search listing keeps its share image; and option names
+ * rename the product's options through `renameProductOptions`, keeping every
+ * variant, only when they name each option once with a name of its own.
+ */
+export declare function productCopyPatch(product: Pick<HostProduct, 'options' | 'variants' | 'seo'>, values: ProductCopyValues): Partial<Pick<HostProduct, 'description' | 'tags' | 'categoryIds' | 'seo' | 'options' | 'variants'>>;
+/** A product proposed for a store, before anyone has priced it (AGL-2916). */
+export interface ProposedProduct {
+    name: string;
+    type: ProductType;
+    description: string;
+    tags: string[];
+    options: ProductOption[];
+    seoTitle: string;
+    seoDescription: string;
+}
+/** A new product whose variants carry no price yet. */
+export type UnpricedProductDraft = Omit<HostProduct, 'variants'> & {
+    variants: Array<Omit<ProductVariant, 'priceUsd'>>;
+};
+/**
+ * The document a proposed product is created as (AGL-2916): a `draft`, under
+ * a slug no product in `takenSlugs` has, with one variant for each
+ * combination of its options and NO price on any of them. Prices are the
+ * merchant's to set: the editor refuses to save the product until every
+ * variant has one, and no sale door sells a variant without one
+ * (`variantHasPrice`). The search keys travel with the name, as on every
+ * create path.
+ */
+export declare function unpricedProductDraft(proposal: ProposedProduct, takenSlugs: ReadonlySet<string>, nowMs: number): UnpricedProductDraft;
+/** Variant whose option selections match exactly; undefined if none. */
+export declare function findVariant(product: Pick<HostProduct, 'variants'>, selections: Record<string, string>): ProductVariant | undefined;
+/** [min, max] price across variants; [0, 0] when there are none. */
+export declare function productPriceRange(product: Pick<HostProduct, 'variants'>): [number, number];
+/** Sum of tracked inventory; null when every variant is untracked. */
+export declare function productInventory(product: Pick<HostProduct, 'variants'>): number | null;
+/**
+ * Reasons an inventory adjustment doc may carry (AGL-281).
+ *
+ * `cancellation` is the only one written automatically in the PLUS direction
+ * (AGL-1808): cancelling an order the transition rules prove was never
+ * fulfilled puts back exactly what the sale took. It is deliberately not
+ * `refund` — no money moved — and not `correction`, which is what a merchant
+ * picks when the count disagreed with the shelf for a reason nobody recorded.
+ * Kept out of the "Adjust stock" dialog's menu on purpose: a merchant reaching
+ * for it by hand means something else happened.
+ */
+export type InventoryAdjustmentReason = 'sale' | 'refund' | 'restock' | 'correction' | 'damage' | 'cancellation';
+/** `hosts/{hostId}/inventoryAdjustments/{id}` doc. */
+export interface InventoryAdjustment {
+    productId: string;
+    variantId: string;
+    /** Positive = stock added, negative = removed. */
+    delta: number;
+    /**
+     * What the count ACTUALLY moved by, when the floor in
+     * `adjustVariantInventory` absorbed part of `delta` (AGL-2149). Written only
+     * when the two differ, which for a sale means a backorder product that sold
+     * past zero: `delta` stays the units sold — that is the merchant's stock
+     * history and it must keep saying "3 went out the door" — while this says how
+     * many of them the count could give up.
+     *
+     * A REVERSAL MUST READ THIS, NOT `delta`. Restoring `delta` on a backorder
+     * sale that the floor swallowed invents inventory that never existed: 0 sells
+     * 3, the count stays 0, and a `+3` on cancellation leaves 3 units nobody has.
+     * Absent on every row written before AGL-2149 and on every row where nothing
+     * was clamped, so `appliedDelta ?? delta` is the reader.
+     */
+    appliedDelta?: number;
+    reason: InventoryAdjustmentReason;
+    /** Order id for sale/refund adjustments. */
+    orderId?: string;
+    /** Location for multi-location stock (AGL-286); absent = default. */
+    locationId?: string;
+    atMs: number;
+}
+/**
+ * Whether `quantity` of a variant is purchasable (AGL-281): untracked
+ * stock always is; tracked stock honors the product's oversell policy.
+ */
+export declare function canPurchase(product: Pick<HostProduct, 'variants' | 'oversellPolicy'>, variantId: string | undefined, quantity?: number): boolean;
+/**
+ * What the register has to SAY about a line it is about to sell (AGL-2357).
+ *
+ * ## The defect
+ *
+ * `pos-order.ts` contains no `canPurchase` call. Every storefront door gates on
+ * it; the register does not, so a merchant who set `oversellPolicy: 'deny'` in
+ * the product editor silently got `backorder` at the counter — the count floors
+ * at zero underneath and nothing anywhere says so.
+ *
+ * ## The decision, and why it is a shortfall and not a refusal
+ *
+ * Warn, never block. A till is the wrong place for a stale number to stop a
+ * real sale: the cashier is holding the goods, the physical shelf is the truth,
+ * and refusing loses a sale over data that is behind. But "deny" must at least
+ * SAY something. So this reports the shortfall and the caller sells anyway.
+ * Honouring the policy with a manager-level override is the post-launch shape
+ * (AGL-2372) and wants an audit trail this deliberately does not build.
+ *
+ * ## Why the test is `canPurchase`
+ *
+ * Exactly the gate the register was missing, and no wider. An untracked variant
+ * has no number to be short against, and a `backorder` product's merchant chose
+ * to sell past zero — warning them would be noise about a setting they set on
+ * purpose. So a shortfall is reported only where a purchase would have been
+ * refused anywhere else in the product.
+ */
+export interface StockShortfall {
+    productId: string;
+    variantId?: string;
+    /** Product name at the time of sale, for a message the cashier can read. */
+    name: string;
+    variantLabel?: string;
+    /** Units the cashier is ringing up. */
+    requested: number;
+    /** Units the count says are on the shelf; never negative. */
+    available: number;
+}
+export declare function stockShortfall(product: Pick<HostProduct, 'variants' | 'oversellPolicy'>, variantId: string | undefined, quantity?: number): {
+    available: number;
+} | null;
+/**
+ * Whether stock tracking MEANS anything on a product (AGL-1744).
+ *
+ * `canPurchase` above gates every checkout on stock, subscription sessions
+ * included, but nothing ever decrements for a subscription — not on the
+ * initial charge (the `commerce-subscription` webhook branch deliberately
+ * writes no order and touches no inventory, AGL-1732) and not on renewal
+ * (`invoice.payment_succeeded` is unhandled repo-wide, AGL-1743). So on a
+ * subscription-only product that gate is permanently satisfied: one unit of
+ * stock sells an unlimited number of subscriptions, and the count never
+ * moves however many boxes ship. The merchant set a number, the system
+ * checks it on every sale, and the number is never true.
+ *
+ * AGL-1750 resolved the half AGL-1744 had to leave open: every paid invoice
+ * of a PHYSICAL subscription now mints an order and decrements its variant's
+ * stock (the `invoice.paid` branch of the commerce webhook), opening cycle
+ * included. So the honest split is now three-way:
+ *
+ *   - `subscriptionOptional` ("Both") products have a real one-time path —
+ *     the cart only ever builds `mode: 'payment'` sessions, and buy-now with
+ *     `billing: 'once'` records a plain order — and that path decrements
+ *     honestly. Withdrawing stock tracking there would delete a working
+ *     control and re-open the AGL-1711 oversell on the half that works.
+ *   - a PHYSICAL subscription box consumes a unit every cycle, and since
+ *     AGL-1750 the cycle's own order decrements it — the count moves as the
+ *     boxes ship, so the number the merchant sets is kept true again.
+ *   - a DIGITAL or SERVICE subscription-only product still has no
+ *     decrementing path anywhere, so the field stays withdrawn there: one
+ *     unit would still sell unlimited subscriptions.
+ *
+ * This says nothing about what `canPurchase` returns — that is the gate for
+ * every other purchase path and is deliberately untouched. This is a console
+ * predicate: it stops the editor inviting a merchant to set a number the
+ * system will never keep true.
+ */
+export declare function stockTrackingApplies(product: Pick<HostProduct, 'subscription' | 'subscriptionOptional' | 'type'>): boolean;
+/** Buyer's requested billing mode on a checkout POST (AGL-545). */
+export type CheckoutBillingChoice = 'once' | 'subscribe';
+/**
+ * Resolves the Stripe Checkout mode for a product + the buyer's
+ * requested billing choice (AGL-545). The product doc is authoritative:
+ * - no `subscription` → always one-time (the request field is ignored)
+ * - `subscription` without `subscriptionOptional` → always subscription
+ *   (a forged `billing: 'once'` cannot buy a subscription product once)
+ * - `subscriptionOptional` → the buyer chooses; absent/invalid choices
+ *   default to one-time, matching the PDP default.
+ */
+export declare function resolveCheckoutBillingMode(product: Pick<HostProduct, 'subscription' | 'subscriptionOptional'>, requested?: string | null): 'payment' | 'subscription';
+/**
+ * Applies a stock delta to one variant, flooring at zero (race-window
+ * sales can't drive the display negative), and returns the new variants
+ * array — callers persist it plus the `productInventory` denormalization.
+ * With `locationId`, the delta lands in that location's bucket and the
+ * flat `inventory` re-sums across locations (AGL-286).
+ */
+export declare function adjustVariantInventory(product: Pick<HostProduct, 'variants'>, variantId: string, delta: number, locationId?: string): ProductVariant[];
+/**
+ * What `adjustVariantInventory` will ACTUALLY move the count by (AGL-2149).
+ *
+ * The floor in that helper is not a rounding detail, it is a silent absorber. A
+ * backorder product (`oversellPolicy: 'backorder'`, which `canPurchase` admits
+ * at any stock level) sitting at 0 sells 3: `Math.max(0, 0 + -3)` is 0, so the
+ * count does not move — correctly, since inventory is a shelf count and shelves
+ * do not go negative — but the ledger row said `-3` and every reversal read it
+ * as three units to put back. Cancelling that order handed the merchant 3 units
+ * that never existed and a stock badge that offers them for sale.
+ *
+ * Removing the floor is not the alternative: every reader of `inventory` — the
+ * badges, `canPurchase`, `productInventory`, `isLowStock` — assumes it cannot
+ * go negative, and a negative count would be a far wider change than the bug.
+ * So the clamp stays and the amount it absorbed is recorded instead.
+ *
+ * Deliberately mirrors `adjustVariantInventory`'s own arithmetic, including
+ * which field the clamp applies to in the location-tracked case, so the two
+ * cannot disagree about what happened.
+ */
+export declare function appliedVariantInventoryDelta(product: Pick<HostProduct, 'variants'>, variantId: string, delta: number, locationId?: string): number;
+/**
+ * Moves stock between two locations of a tracked variant (AGL-286).
+ * Quantity clamps to what the source location holds; the flat total is
+ * unchanged by construction.
+ */
+export declare function transferVariantInventory(product: Pick<HostProduct, 'variants'>, variantId: string, fromLocationId: string, toLocationId: string, quantity: number): ProductVariant[];
+/** True when tracked stock is at/below the product's alert threshold. */
+export declare function isLowStock(product: Pick<HostProduct, 'variants' | 'lowStockThreshold'>): boolean;
+/**
+ * Smart-collection membership: draft/archived/deleted products never
+ * match; manual collections answer from productIds.
+ */
+export declare function matchesCollection(product: HostProduct, collection: HostCollection, productId?: string): boolean;
+/**
+ * Lifts a legacy Commerce Starter doc (AGL-90: flat name/priceUsd/
+ * inventory/imageUrl) into the catalog shape with a single default
+ * variant. Already-lifted docs pass through unchanged.
+ */
+export declare function liftLegacyProduct(raw: Partial<HostProduct> & {
+    name?: string;
+}): HostProduct;
+/** Actionable error, or null when the product is storable. */
+export declare function validateProduct(product: HostProduct): string | null;
+/** Actionable error, or null when the collection is storable. */
+export declare function validateCollection(collection: HostCollection): string | null;