@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/constants/product-filters.js

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Products (`hosts/{hostId}/products`).
+ *
+ * The card's listener is `limit(500)` and stays that way — a 25,000-product
+ * catalog does not belong in a table, and the head-count has been a server
+ * aggregate since AGL-1716. What that cap must NOT decide is what a search can
+ * find, and it did: the search compared the rows already fetched, so a product
+ * past the window answered "no products match".
+ *
+ * ⛔ A SKU is matched WHOLE, not as a substring. It lived inside `variants`, an
+ * array of objects, and Firestore cannot look inside one — so the write path
+ * flattens them into `skus` and this is an `array-contains`. A SKU is a value
+ * somebody copies rather than half-remembers, which is why that trade is the
+ * right way round.
+ */ export const PRODUCT_LIST_FILTER_FIELDS = [
+    {
+        column: 'name',
+        kind: 'text',
+        path: 'name',
+        lowerPath: 'nameLower',
+        tokensPath: 'nameTokens',
+        reversedPath: 'nameReversed'
+    },
+    {
+        // Slugs are lower-case by construction (`commerceSlug`), so the stored
+        // value is its own normalized key.
+        column: 'slug',
+        kind: 'text',
+        path: 'slug',
+        lowerPath: 'slug'
+    },
+    {
+        column: 'skus',
+        kind: 'text',
+        path: 'skus',
+        tokensPath: 'skus',
+        // Ordered by the field the card already sorts on rather than by the array
+        // an `array-contains` is matching.
+        containsOrderBy: 'name',
+        operators: [
+            'contains',
+            'isNotEmpty'
+        ]
+    },
+    {
+        // The register's scan path. Exact and whole, which is what a scanner
+        // produces — and it must reach the entire catalog, not a window of it.
+        column: 'barcodes',
+        kind: 'text',
+        path: 'barcodes',
+        tokensPath: 'barcodes',
+        containsOrderBy: 'name',
+        operators: [
+            'contains',
+            'isNotEmpty'
+        ]
+    },
+    {
+        column: 'status',
+        kind: 'exact',
+        path: 'status'
+    },
+    {
+        column: 'type',
+        kind: 'exact',
+        path: 'type'
+    },
+    {
+        column: 'priceUsd',
+        kind: 'number',
+        path: 'priceUsd'
+    },
+    {
+        column: 'createdAt',
+        kind: 'date',
+        path: 'createdAt'
+    },
+    {
+        column: 'updatedAt',
+        kind: 'date',
+        path: 'updatedAt'
+    }
+];
+/** Headers for product fields that are filterable without being columns. */ export const PRODUCT_LIST_FILTER_HEADERS = {
+    slug: 'Slug',
+    skus: 'SKU',
+    barcodes: 'Barcode',
+    type: 'Type',
+    priceUsd: 'Price (USD)',
+    createdAt: 'Created',
+    updatedAt: 'Updated'
+};
+
+//# sourceMappingURL=product-filters.js.map

package/src/lib/constants/product-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/constants/product-filters.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 { ListFilterField } from '@aglyn/shared-ui-jsx/const/list-filter'\n\n/**\n * Products (`hosts/{hostId}/products`).\n *\n * The card's listener is `limit(500)` and stays that way — a 25,000-product\n * catalog does not belong in a table, and the head-count has been a server\n * aggregate since AGL-1716. What that cap must NOT decide is what a search can\n * find, and it did: the search compared the rows already fetched, so a product\n * past the window answered \"no products match\".\n *\n * ⛔ A SKU is matched WHOLE, not as a substring. It lived inside `variants`, an\n * array of objects, and Firestore cannot look inside one — so the write path\n * flattens them into `skus` and this is an `array-contains`. A SKU is a value\n * somebody copies rather than half-remembers, which is why that trade is the\n * right way round.\n */\nexport const PRODUCT_LIST_FILTER_FIELDS: readonly ListFilterField[] = [\n  {\n    column: 'name',\n    kind: 'text',\n    path: 'name',\n    lowerPath: 'nameLower',\n    tokensPath: 'nameTokens',\n    reversedPath: 'nameReversed',\n  },\n  {\n    // Slugs are lower-case by construction (`commerceSlug`), so the stored\n    // value is its own normalized key.\n    column: 'slug',\n    kind: 'text',\n    path: 'slug',\n    lowerPath: 'slug',\n  },\n  {\n    column: 'skus',\n    kind: 'text',\n    path: 'skus',\n    tokensPath: 'skus',\n    // Ordered by the field the card already sorts on rather than by the array\n    // an `array-contains` is matching.\n    containsOrderBy: 'name',\n    operators: ['contains', 'isNotEmpty'],\n  },\n  {\n    // The register's scan path. Exact and whole, which is what a scanner\n    // produces — and it must reach the entire catalog, not a window of it.\n    column: 'barcodes',\n    kind: 'text',\n    path: 'barcodes',\n    tokensPath: 'barcodes',\n    containsOrderBy: 'name',\n    operators: ['contains', 'isNotEmpty'],\n  },\n  { column: 'status', kind: 'exact', path: 'status' },\n  { column: 'type', kind: 'exact', path: 'type' },\n  { column: 'priceUsd', kind: 'number', path: 'priceUsd' },\n  { column: 'createdAt', kind: 'date', path: 'createdAt' },\n  { column: 'updatedAt', kind: 'date', path: 'updatedAt' },\n]\n\n/** Headers for product fields that are filterable without being columns. */\nexport const PRODUCT_LIST_FILTER_HEADERS: Readonly<Record<string, string>> = {\n  slug: 'Slug',\n  skus: 'SKU',\n  barcodes: 'Barcode',\n  type: 'Type',\n  priceUsd: 'Price (USD)',\n  createdAt: 'Created',\n  updatedAt: 'Updated',\n}\n"],"names":["PRODUCT_LIST_FILTER_FIELDS","column","kind","path","lowerPath","tokensPath","reversedPath","containsOrderBy","operators","PRODUCT_LIST_FILTER_HEADERS","slug","skus","barcodes","type","priceUsd","createdAt","updatedAt"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMA,6BAAyD;IACpE;QACEC,QAAQ;QACRC,MAAM;QACNC,MAAM;QACNC,WAAW;QACXC,YAAY;QACZC,cAAc;IAChB;IACA;QACE,uEAAuE;QACvE,mCAAmC;QACnCL,QAAQ;QACRC,MAAM;QACNC,MAAM;QACNC,WAAW;IACb;IACA;QACEH,QAAQ;QACRC,MAAM;QACNC,MAAM;QACNE,YAAY;QACZ,0EAA0E;QAC1E,mCAAmC;QACnCE,iBAAiB;QACjBC,WAAW;YAAC;YAAY;SAAa;IACvC;IACA;QACE,qEAAqE;QACrE,uEAAuE;QACvEP,QAAQ;QACRC,MAAM;QACNC,MAAM;QACNE,YAAY;QACZE,iBAAiB;QACjBC,WAAW;YAAC;YAAY;SAAa;IACvC;IACA;QAAEP,QAAQ;QAAUC,MAAM;QAASC,MAAM;IAAS;IAClD;QAAEF,QAAQ;QAAQC,MAAM;QAASC,MAAM;IAAO;IAC9C;QAAEF,QAAQ;QAAYC,MAAM;QAAUC,MAAM;IAAW;IACvD;QAAEF,QAAQ;QAAaC,MAAM;QAAQC,MAAM;IAAY;IACvD;QAAEF,QAAQ;QAAaC,MAAM;QAAQC,MAAM;IAAY;CACxD,CAAA;AAED,0EAA0E,GAC1E,OAAO,MAAMM,8BAAgE;IAC3EC,MAAM;IACNC,MAAM;IACNC,UAAU;IACVC,MAAM;IACNC,UAAU;IACVC,WAAW;IACXC,WAAW;AACb,EAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * @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.
+ */
+/**
+ * Cart v1 (AGL-293): a server-backed cart doc at
+ * `hosts/{hostId}/carts/{cartId}`, keyed by an httpOnly cookie. Lines
+ * store only ids + quantity — display data and prices resolve from the
+ * product docs at read/checkout time, so a stale cart can never charge
+ * a stale price. Pure helpers; the cart API owns I/O.
+ */
+export interface CartLine {
+    productId: string;
+    /** Absent = the product's default variant. */
+    variantId?: string;
+    quantity: number;
+}
+/** `hosts/{hostId}/carts/{cartId}` doc. */
+export interface HostCart {
+    lines: CartLine[];
+    /** Storefront customer once signed in (AGL-294 merge). */
+    customerId?: string;
+    updatedAtMs?: number;
+    createdAtMs?: number;
+}
+export declare const CART_MAX_LINES = 50;
+export declare const CART_MAX_QUANTITY = 99;
+/**
+ * Adds/merges a line (quantities accumulate), clamped to per-line and
+ * line-count caps. Quantity ≤ 0 removes the line.
+ */
+export declare function upsertCartLine(cart: Pick<HostCart, 'lines'>, line: CartLine, mode?: 'add' | 'set'): CartLine[];
+export declare function removeCartLine(cart: Pick<HostCart, 'lines'>, line: Pick<CartLine, 'productId' | 'variantId'>): CartLine[];
+/** Total units across lines (the mini-cart badge). */
+export declare function cartCount(cart: Pick<HostCart, 'lines'> | undefined): number;
+/**
+ * Merges a guest cart into a customer cart on sign-in (AGL-294):
+ * quantities accumulate per line, capped as usual.
+ */
+export declare function mergeCarts(customerCart: Pick<HostCart, 'lines'>, guestCart: Pick<HostCart, 'lines'>): CartLine[];

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

@@ -0,0 +1,102 @@
+/**
+ * @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.
+ */ /**
+ * Cart v1 (AGL-293): a server-backed cart doc at
+ * `hosts/{hostId}/carts/{cartId}`, keyed by an httpOnly cookie. Lines
+ * store only ids + quantity — display data and prices resolve from the
+ * product docs at read/checkout time, so a stale cart can never charge
+ * a stale price. Pure helpers; the cart API owns I/O.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+export const CART_MAX_LINES = 50;
+export const CART_MAX_QUANTITY = 99;
+function lineKey(line) {
+    var _line_variantId;
+    return `${line.productId}:${(_line_variantId = line.variantId) != null ? _line_variantId : ''}`;
+}
+/**
+ * A line quantity, coerced to a whole finite number (AGL-2285).
+ *
+ * `Math.round(line.quantity)` was the whole sanitiser, and `Math.round(NaN)` is
+ * `NaN` — which then walked past the guard below, because `NaN <= 0` is
+ * `false`. A cart line with `quantity: NaN` (a legal Firestore double) was
+ * stored, and from there `cartCount` reported `NaN` in the mini-cart badge and
+ * `cart-checkout.ts` computed `itemsCents`, the platform fee and the Stripe
+ * `line_items[n][quantity]` as `NaN` too — so Stripe 400s and the shopper
+ * cannot check out AT ALL until they find the poisoned line and remove it.
+ *
+ * Answering 0 is what makes the existing `<= 0` guard do its job: an
+ * unusable quantity removes the line (or refuses to add one) rather than
+ * writing a value nothing downstream can compare against. The same lesson as
+ * AGL-2229 one collection over — `Math.max`/`Math.min`/`Math.round` propagate
+ * `NaN`, they do not discard it.
+ */ function wholeQuantity(value) {
+    const quantity = Math.round(Number(value != null ? value : 0));
+    return Number.isFinite(quantity) ? quantity : 0;
+}
+/**
+ * Adds/merges a line (quantities accumulate), clamped to per-line and
+ * line-count caps. Quantity ≤ 0 removes the line.
+ */ export function upsertCartLine(cart, line, mode = 'add') {
+    const quantity = wholeQuantity(line.quantity);
+    const key = lineKey(line);
+    const existing = cart.lines.find((item)=>lineKey(item) === key);
+    if (!existing) {
+        if (quantity <= 0) return cart.lines;
+        if (cart.lines.length >= CART_MAX_LINES) return cart.lines;
+        return [
+            ...cart.lines,
+            _extends({}, line, {
+                quantity: Math.min(CART_MAX_QUANTITY, quantity)
+            })
+        ];
+    }
+    // The STORED side is coerced too (AGL-2285): a line written before this
+    // guard, or by any other writer, can still hold a non-finite quantity, and
+    // adding to it would carry that forward forever.
+    const nextQuantity = mode === 'add' ? wholeQuantity(existing.quantity) + quantity : quantity;
+    if (nextQuantity <= 0) {
+        return cart.lines.filter((item)=>lineKey(item) !== key);
+    }
+    return cart.lines.map((item)=>lineKey(item) === key ? _extends({}, item, {
+            quantity: Math.min(CART_MAX_QUANTITY, nextQuantity)
+        }) : item);
+}
+export function removeCartLine(cart, line) {
+    const key = lineKey(line);
+    return cart.lines.filter((item)=>lineKey(item) !== key);
+}
+/** Total units across lines (the mini-cart badge). */ export function cartCount(cart) {
+    var _ref;
+    // Coerced per line (AGL-2285) so one stored `NaN` cannot make the badge read
+    // `NaN` for a cart that otherwise has real items in it.
+    return ((_ref = cart == null ? void 0 : cart.lines) != null ? _ref : []).reduce((sum, line)=>sum + wholeQuantity(line == null ? void 0 : line.quantity), 0);
+}
+/**
+ * Merges a guest cart into a customer cart on sign-in (AGL-294):
+ * quantities accumulate per line, capped as usual.
+ */ export function mergeCarts(customerCart, guestCart) {
+    let lines = [
+        ...customerCart.lines
+    ];
+    for (const line of guestCart.lines){
+        lines = upsertCartLine({
+            lines
+        }, line, 'add');
+    }
+    return lines;
+}
+
+//# sourceMappingURL=commerce-cart.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-cart.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 * Cart v1 (AGL-293): a server-backed cart doc at\n * `hosts/{hostId}/carts/{cartId}`, keyed by an httpOnly cookie. Lines\n * store only ids + quantity — display data and prices resolve from the\n * product docs at read/checkout time, so a stale cart can never charge\n * a stale price. Pure helpers; the cart API owns I/O.\n */\n\nexport interface CartLine {\n  productId: string\n  /** Absent = the product's default variant. */\n  variantId?: string\n  quantity: number\n}\n\n/** `hosts/{hostId}/carts/{cartId}` doc. */\nexport interface HostCart {\n  lines: CartLine[]\n  /** Storefront customer once signed in (AGL-294 merge). */\n  customerId?: string\n  updatedAtMs?: number\n  createdAtMs?: number\n}\n\nexport const CART_MAX_LINES = 50\nexport const CART_MAX_QUANTITY = 99\n\nfunction lineKey(line: Pick<CartLine, 'productId' | 'variantId'>): string {\n  return `${line.productId}:${line.variantId ?? ''}`\n}\n\n/**\n * A line quantity, coerced to a whole finite number (AGL-2285).\n *\n * `Math.round(line.quantity)` was the whole sanitiser, and `Math.round(NaN)` is\n * `NaN` — which then walked past the guard below, because `NaN <= 0` is\n * `false`. A cart line with `quantity: NaN` (a legal Firestore double) was\n * stored, and from there `cartCount` reported `NaN` in the mini-cart badge and\n * `cart-checkout.ts` computed `itemsCents`, the platform fee and the Stripe\n * `line_items[n][quantity]` as `NaN` too — so Stripe 400s and the shopper\n * cannot check out AT ALL until they find the poisoned line and remove it.\n *\n * Answering 0 is what makes the existing `<= 0` guard do its job: an\n * unusable quantity removes the line (or refuses to add one) rather than\n * writing a value nothing downstream can compare against. The same lesson as\n * AGL-2229 one collection over — `Math.max`/`Math.min`/`Math.round` propagate\n * `NaN`, they do not discard it.\n */\nfunction wholeQuantity(value: unknown): number {\n  const quantity = Math.round(Number(value ?? 0))\n  return Number.isFinite(quantity) ? quantity : 0\n}\n\n/**\n * Adds/merges a line (quantities accumulate), clamped to per-line and\n * line-count caps. Quantity ≤ 0 removes the line.\n */\nexport function upsertCartLine(\n  cart: Pick<HostCart, 'lines'>,\n  line: CartLine,\n  mode: 'add' | 'set' = 'add',\n): CartLine[] {\n  const quantity = wholeQuantity(line.quantity)\n  const key = lineKey(line)\n  const existing = cart.lines.find((item) => lineKey(item) === key)\n  if (!existing) {\n    if (quantity <= 0) return cart.lines\n    if (cart.lines.length >= CART_MAX_LINES) return cart.lines\n    return [\n      ...cart.lines,\n      { ...line, quantity: Math.min(CART_MAX_QUANTITY, quantity) },\n    ]\n  }\n  // The STORED side is coerced too (AGL-2285): a line written before this\n  // guard, or by any other writer, can still hold a non-finite quantity, and\n  // adding to it would carry that forward forever.\n  const nextQuantity =\n    mode === 'add' ? wholeQuantity(existing.quantity) + quantity : quantity\n  if (nextQuantity <= 0) {\n    return cart.lines.filter((item) => lineKey(item) !== key)\n  }\n  return cart.lines.map((item) =>\n    lineKey(item) === key\n      ? { ...item, quantity: Math.min(CART_MAX_QUANTITY, nextQuantity) }\n      : item,\n  )\n}\n\nexport function removeCartLine(\n  cart: Pick<HostCart, 'lines'>,\n  line: Pick<CartLine, 'productId' | 'variantId'>,\n): CartLine[] {\n  const key = lineKey(line)\n  return cart.lines.filter((item) => lineKey(item) !== key)\n}\n\n/** Total units across lines (the mini-cart badge). */\nexport function cartCount(cart: Pick<HostCart, 'lines'> | undefined): number {\n  // Coerced per line (AGL-2285) so one stored `NaN` cannot make the badge read\n  // `NaN` for a cart that otherwise has real items in it.\n  return (cart?.lines ?? []).reduce(\n    (sum, line) => sum + wholeQuantity(line?.quantity),\n    0,\n  )\n}\n\n/**\n * Merges a guest cart into a customer cart on sign-in (AGL-294):\n * quantities accumulate per line, capped as usual.\n */\nexport function mergeCarts(\n  customerCart: Pick<HostCart, 'lines'>,\n  guestCart: Pick<HostCart, 'lines'>,\n): CartLine[] {\n  let lines = [...customerCart.lines]\n  for (const line of guestCart.lines) {\n    lines = upsertCartLine({ lines }, line, 'add')\n  }\n  return lines\n}\n"],"names":["CART_MAX_LINES","CART_MAX_QUANTITY","lineKey","line","productId","variantId","wholeQuantity","value","quantity","Math","round","Number","isFinite","upsertCartLine","cart","mode","key","existing","lines","find","item","length","min","nextQuantity","filter","map","removeCartLine","cartCount","reduce","sum","mergeCarts","customerCart","guestCart"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;CAMC;AAkBD,OAAO,MAAMA,iBAAiB,GAAE;AAChC,OAAO,MAAMC,oBAAoB,GAAE;AAEnC,SAASC,QAAQC,IAA+C;QAClCA;IAA5B,OAAO,GAAGA,KAAKC,SAAS,CAAC,CAAC,GAAED,kBAAAA,KAAKE,SAAS,YAAdF,kBAAkB,IAAI;AACpD;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,SAASG,cAAcC,KAAc;IACnC,MAAMC,WAAWC,KAAKC,KAAK,CAACC,OAAOJ,gBAAAA,QAAS;IAC5C,OAAOI,OAAOC,QAAQ,CAACJ,YAAYA,WAAW;AAChD;AAEA;;;CAGC,GACD,OAAO,SAASK,eACdC,IAA6B,EAC7BX,IAAc,EACdY,OAAsB,KAAK;IAE3B,MAAMP,WAAWF,cAAcH,KAAKK,QAAQ;IAC5C,MAAMQ,MAAMd,QAAQC;IACpB,MAAMc,WAAWH,KAAKI,KAAK,CAACC,IAAI,CAAC,CAACC,OAASlB,QAAQkB,UAAUJ;IAC7D,IAAI,CAACC,UAAU;QACb,IAAIT,YAAY,GAAG,OAAOM,KAAKI,KAAK;QACpC,IAAIJ,KAAKI,KAAK,CAACG,MAAM,IAAIrB,gBAAgB,OAAOc,KAAKI,KAAK;QAC1D,OAAO;eACFJ,KAAKI,KAAK;YACb,aAAKf;gBAAMK,UAAUC,KAAKa,GAAG,CAACrB,mBAAmBO;;SAClD;IACH;IACA,wEAAwE;IACxE,2EAA2E;IAC3E,iDAAiD;IACjD,MAAMe,eACJR,SAAS,QAAQT,cAAcW,SAAST,QAAQ,IAAIA,WAAWA;IACjE,IAAIe,gBAAgB,GAAG;QACrB,OAAOT,KAAKI,KAAK,CAACM,MAAM,CAAC,CAACJ,OAASlB,QAAQkB,UAAUJ;IACvD;IACA,OAAOF,KAAKI,KAAK,CAACO,GAAG,CAAC,CAACL,OACrBlB,QAAQkB,UAAUJ,MACd,aAAKI;YAAMZ,UAAUC,KAAKa,GAAG,CAACrB,mBAAmBsB;aACjDH;AAER;AAEA,OAAO,SAASM,eACdZ,IAA6B,EAC7BX,IAA+C;IAE/C,MAAMa,MAAMd,QAAQC;IACpB,OAAOW,KAAKI,KAAK,CAACM,MAAM,CAAC,CAACJ,OAASlB,QAAQkB,UAAUJ;AACvD;AAEA,oDAAoD,GACpD,OAAO,SAASW,UAAUb,IAAyC;;IACjE,6EAA6E;IAC7E,wDAAwD;IACxD,OAAO,SAACA,wBAAAA,KAAMI,KAAK,mBAAI,EAAE,EAAEU,MAAM,CAC/B,CAACC,KAAK1B,OAAS0B,MAAMvB,cAAcH,wBAAAA,KAAMK,QAAQ,GACjD;AAEJ;AAEA;;;CAGC,GACD,OAAO,SAASsB,WACdC,YAAqC,EACrCC,SAAkC;IAElC,IAAId,QAAQ;WAAIa,aAAab,KAAK;KAAC;IACnC,KAAK,MAAMf,QAAQ6B,UAAUd,KAAK,CAAE;QAClCA,QAAQL,eAAe;YAAEK;QAAM,GAAGf,MAAM;IAC1C;IACA,OAAOe;AACT"}

package/src/lib/model/commerce-connect-transfer.d.ts

@@ -0,0 +1,243 @@
+/**
+ * @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.
+ */
+/**
+ * How a storefront destination charge splits between Aglyn and the merchant —
+ * and, when Stripe Tax is on, why the split cannot be expressed as a fee
+ * (AGL-1956).
+ *
+ * ## The defect this module exists to close
+ *
+ * Every storefront checkout is a DESTINATION charge created on AGLYN's
+ * platform account: platform secret key, no `Stripe-Account` header, no
+ * `on_behalf_of`, with `payment_intent_data[transfer_data][destination]`
+ * naming the merchant's connected account. On a `mode: 'stripe'` store the
+ * session also carries `automatic_tax[enabled]`, and AGL-1904 MEASURED what
+ * that means: the tax is computed against **Aglyn's** registrations, reported
+ * as `automatic_tax.liability: { type: "self" }`, and is **Aglyn's to remit**.
+ * See `../server/storefront-tax.ts` for the two-arm experiment.
+ *
+ * The sessions then set `payment_intent_data[application_fee_amount]`. On a
+ * destination charge that form means Stripe transfers the **whole charge** to
+ * the connected account and debits the fee at the destination — measured, and
+ * recorded at `billing-webhook.ts` (the AGL-1794 note: "`transfer.amount`
+ * equals `charge.amount`"). `amount_total` INCLUDES the Stripe Tax.
+ *
+ * So on every taxed storefront sale the sales tax Aglyn owes the state was
+ * transferred to the merchant, and only the commission came back. Aglyn was
+ * left holding the liability and none of the money. This is the same trap the
+ * marketplace plugin found and closed in AGL-1544, and the fix here is the
+ * same one: **a fixed `transfer_data[amount]`, and no `application_fee_amount`
+ * at all** — because the fee form makes Stripe do the arithmetic on a total
+ * that has the tax inside it.
+ *
+ * ## Only ONE of the two knobs may do the arithmetic
+ *
+ * `application_fee_amount` says "give the merchant everything except this".
+ * `transfer_data[amount]` says "give the merchant exactly this". They are two
+ * spellings of the same split and Stripe rejects a PaymentIntent carrying
+ * both, so the emitter below is written as a single choice with no path that
+ * can emit the pair. Which one is correct depends entirely on WHICH SIDE of
+ * the split holds the unknown:
+ *
+ *   - **Merchant owes the tax** (`manual` mode, or no tax at all). The
+ *     variable part — the merchant's tax line — is the merchant's own money.
+ *     Fixing the FEE is exact: Aglyn keeps its commission and every cent of
+ *     variance stays where it belongs.
+ *   - **Aglyn owes the tax** (`stripe` mode). The variable part is now
+ *     AGLYN's money, and a fixed fee hands all of it to the merchant. Fixing
+ *     the TRANSFER is what keeps it.
+ *
+ * ## The residual, stated out loud: shopper-chosen shipping
+ *
+ * Neither knob can be exact on a Stripe Tax sale that also offers a CHOICE of
+ * shipping rates, because at session-creation time two numbers are unknown —
+ * the tax (Aglyn's) and which shipping option the shopper will pick (the
+ * merchant's) — and there is only one knob left to fix. Whichever is fixed,
+ * the other side's variance lands on the wrong party:
+ *
+ *   - Fixing the FEE misallocates the ENTIRE tax, on EVERY taxed sale,
+ *     unbounded. That is the defect above.
+ *   - Fixing the TRANSFER misallocates at most `dearest − cheapest` shipping,
+ *     and only on a store that offers more than one rate.
+ *
+ * The transfer is therefore fixed at the CHEAPEST option, never the dearest.
+ * Not a preference — the dearest is unsafe: a transfer of
+ * `goods + dearest − fee` can EXCEED a charge where the shopper picked the
+ * cheapest, and Stripe rejects a transfer larger than its charge, which would
+ * fail the payment outright rather than mis-split it. The cheapest is always
+ * payable, because the shopper's actual shipping can only be higher.
+ *
+ * The bounded remainder — a shopper who upgraded shipping on a Stripe Tax
+ * store — is money owed to the MERCHANT that Aglyn is holding. It is recorded
+ * on the session as `metadata[transferCents]` and
+ * `metadata[transferShippingCents]` so it is derivable per order rather than
+ * lost, and closing it needs a top-up transfer at
+ * `checkout.session.completed`, which is a new outbound money path and is
+ * deliberately NOT bundled with this fix. Tracked on AGL-1956.
+ *
+ * Pure and total: integer cents in, integer cents out, no clamping surprises
+ * except the documented floor at zero.
+ */
+/** Which party's registrations the tax on this sale was computed against. */
+export type StorefrontTaxOwner = 'platform' | 'merchant';
+export interface DestinationChargeSplit {
+    /** The merchant's connected account id. */
+    accountId: string;
+    /**
+     * Aglyn's take in cents — the advertised platform fee plus the passed-through
+     * card cost (`resolveTransactionFeeCents`). Never negative.
+     */
+    feeCents: number;
+    /**
+     * `platform` when the session carries `automatic_tax[enabled]` and Stripe
+     * Tax computes against Aglyn's registrations (AGL-1904). `merchant` for a
+     * `manual` rate the merchant set and owes, and for an untaxed sale.
+     */
+    taxOwner: StorefrontTaxOwner;
+    /**
+     * What Stripe will charge for the GOODS — after any coupon is priced in, and
+     * excluding shipping and every tax line. The merchant's money.
+     */
+    merchantGoodsCents: number;
+    /**
+     * The CHEAPEST shipping option offered on this session, or 0 when the
+     * merchant offers none. See the module note on why this is the cheapest and
+     * not the dearest.
+     */
+    shippingFloorCents?: number;
+}
+/**
+ * What the merchant is paid, in cents, when AGLYN owes the tax.
+ *
+ * `goods + cheapest shipping − fee`, floored at zero. The floor is a real
+ * case, not defensive padding: `resolveTransactionFeeCents` adds Stripe's
+ * fixed 30¢ card cost, so a sub-dollar order can carry a fee worth more than
+ * the goods. The merchant is paid nothing on such an order, which is the
+ * honest outcome — Aglyn is out of pocket on it either way — and it must
+ * never be expressed as a NEGATIVE transfer, which Stripe rejects.
+ */
+export declare function platformLiableTransferCents(split: Pick<DestinationChargeSplit, 'feeCents' | 'merchantGoodsCents' | 'shippingFloorCents'>): number;
+/**
+ * What a paid SUBSCRIPTION invoice says about the tax on it, and therefore
+ * whether the platform has to pull that tax back out of the transfer
+ * (AGL-1956).
+ *
+ * ## Why the recurring path needs a different instrument entirely
+ *
+ * Everything above is about a knob set when the charge is CREATED. A Stripe
+ * Subscription has neither knob: it accepts no `transfer_data[amount]`, only
+ * `application_fee_percent`. On a destination charge that means Stripe
+ * transfers the WHOLE charge to the connected account and debits the fee at
+ * the destination, and the charge has the Stripe Tax inside it — so the
+ * merchant is handed the state's money on every taxed cycle. `checkout.ts`
+ * therefore excludes subscriptions from `destinationChargeParams` and leaves
+ * them on the fee form.
+ *
+ * AGL-2317 makes that strictly worse, not better. It refunds the part of the
+ * application fee that was taken on tax and shipping BACK to the connected
+ * account, which is right on its own terms (Aglyn's advertised cut is a cut of
+ * sales) but means the merchant ends the cycle holding **one hundred percent**
+ * of a tax Aglyn is the one registered to remit.
+ *
+ * ## The money is already at the merchant, so the correction is a REVERSAL
+ *
+ * Worth stating explicitly, because the sign is easy to get backwards and this
+ * module documents a residual that runs the OTHER way. The shipping residual
+ * above is a case where the transfer was FIXED too low and the merchant is
+ * owed more — that one needs a top-up. This is the opposite: the fee form
+ * OVER-transfers, the tax is physically sitting in the connected account's
+ * balance, and the only instrument that moves it back to the platform is a
+ * transfer reversal. A top-up here would pay the merchant the tax twice.
+ *
+ * ## Three answers, never two
+ *
+ * The whole point of the three-state is that **a missing tax field must not
+ * read as "no tax"**. Stripe removed the scalar `invoice.tax` in favour of
+ * `total_taxes[]`, and which spelling an endpoint receives is dashboard
+ * configuration this repo cannot see. A reader that reached for one field and
+ * defaulted the miss to `0` would answer "no reversal" on every invoice after
+ * a Stripe version bump nobody here can observe — a swallowed read rendering
+ * as a measured zero, with the money going the wrong way and nothing looking
+ * wrong. So an invoice that claims automatic tax while stating NO tax field at
+ * all is `unreadable`, and the caller is required to make noise about it.
+ *
+ * A `tax: 0`, or a present-but-empty `total_taxes: []`, is a real answer and
+ * is `skip`. That is also what a $0 or fully-discounted invoice produces, which
+ * is why the no-op costs nothing.
+ *
+ * Pure and total: no throw, no clamping beyond the documented floor at zero.
+ */
+export type SubscriptionTaxReversalDecision = 
+/** Aglyn owes this tax and the merchant is holding it. Pull back exactly this. */
+{
+    kind: 'reverse';
+    taxCents: number;
+}
+/** Nothing to do, and nothing wrong. No network call is warranted. */
+ | {
+    kind: 'skip';
+    reason: 'merchant-tax' | 'no-tax';
+}
+/** The invoice claims tax it will not state. LOUD, never silent. */
+ | {
+    kind: 'unreadable';
+    reason: string;
+};
+/**
+ * Which party's registrations a subscription invoice's tax was computed
+ * against — the same `taxOwner` distinction `destinationChargeParams` makes,
+ * read off the invoice instead of off the store's settings.
+ *
+ * `automatic_tax.enabled` is THE discriminator and the tax lines are never it,
+ * for the reason `storefront-tax.ts` states at length: a MANUAL-rate
+ * subscription carries a real Stripe Tax Rate on its line (AGL-1751), so every
+ * cycle it bills arrives with a populated `total_taxes[]` that is
+ * indistinguishable from a Stripe Tax one by shape. Reading the lines would
+ * reverse the merchant's OWN tax out of their payout on every cycle — the
+ * failure that steals from the merchant rather than from the state.
+ *
+ * `liability.type === 'account'` means Stripe computed against the CONNECTED
+ * account's registrations, so the tax is theirs and stays with them. `self`,
+ * and an absent liability (older API versions omit the field, where the only
+ * account a platform-created invoice could be liable under is the platform),
+ * mean Aglyn. This mirrors `storefrontTaxRow` exactly, deliberately: the filed
+ * tax record and the reversal must not be able to disagree about who owed it.
+ */
+export declare function subscriptionInvoiceTaxOwner(invoice: unknown): StorefrontTaxOwner;
+/** See `SubscriptionTaxReversalDecision`. */
+export declare function subscriptionInvoiceTaxReversal(invoice: unknown): SubscriptionTaxReversalDecision;
+/**
+ * The cheapest rate on a resolved shipping plan, in cents. `0` for a plan with
+ * no options, which is also the right transfer contribution for a store that
+ * charges no shipping.
+ */
+export declare function shippingFloorCents(options?: readonly {
+    amountCents?: unknown;
+}[]): number;
+/**
+ * The Connect keys for a storefront destination charge — the destination, and
+ * EXACTLY ONE of `application_fee_amount` / `transfer_data[amount]`.
+ *
+ * Emitted from one place so no checkout path can pick the wrong knob on its
+ * own, and so the pair can never both appear (Stripe rejects that, and the two
+ * would be contradicting each other about the same split).
+ *
+ * The `metadata[transferCents]` companion is deliberately NOT emitted here —
+ * each caller owns its own metadata block, and the value is
+ * `platformLiableTransferCents(split)`.
+ */
+export declare function destinationChargeParams(split: DestinationChargeSplit): Record<string, string>;