@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/model/purchase-analytics.js

@@ -0,0 +1,216 @@
+/**
+ * @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.
+ */ /** Money, to two decimals. A float sum of cents produces `59.99999999999999`. */ function toAmount(cents) {
+    return Math.round(cents) / 100;
+}
+/**
+ * Build the `purchase` a TENANT STOREFRONT reports to the MERCHANT's GA4
+ * property (AGL-1641).
+ *
+ * ## Whose revenue this is — the decision, not an inference
+ *
+ * This is the exact inverse of the marketplace call in AGL-1639, and the
+ * reason is the property the hit lands in. There, the GA property is OURS, the
+ * platform fee IS what Aglyn was paid, and `value` had to be platform net so
+ * that a marketplace sale and a subscription meant the same thing when GA
+ * added them up. Here the property is the MERCHANT's — `gtag` on a tenant site
+ * is loaded with `host.analytics.gaMeasurementId`, their measurement id — and
+ * on their storefront the merchant is the seller. Aglyn's cut is not a share
+ * of this sale from their side; it is a cost of making it.
+ *
+ * So `feeCents` is NOT subtracted. Subtracting it would report the merchant's
+ * gross margin after our fee as though it were their sales revenue, which is
+ * not a number any merchant's books, tax return or ad platform recognises.
+ *
+ * Getting this backwards is the expensive mistake: reporting platform net into
+ * a merchant's property would show every merchant on Aglyn a revenue figure a
+ * few percent of their real one.
+ *
+ * ## Tax is excluded, and no `tax` param is sent
+ *
+ * Tax collected is money held for a taxing authority, not revenue, whoever
+ * holds it — and on a storefront that is often Aglyn rather than the merchant,
+ * since Terms §10.7 makes Aglyn a marketplace facilitator where applicable law
+ * gives it a collection obligation (AGL-1956). Either way it is not the
+ * merchant's sales revenue. Every mature ecommerce integration reports revenue
+ * ex-tax and so do we.
+ *
+ * No GA4 `tax` param either, following AGL-1639 for the same reason it applied
+ * there: `value` already EXCLUDES tax, and GA4's `tax` is documented as a cost
+ * associated with the transaction — a component of the value beside it. Sent
+ * next to an ex-tax `value` it asserts a relationship that does not hold, and
+ * invites exactly the subtraction that would double-remove it.
+ *
+ * ## Why `value` derives from `totalCents` and not from the parts
+ *
+ * `totalCents` is overwritten with Stripe's `amount_total` when the webhook
+ * writes the order (`billing-webhook.ts`), so it is the one field that
+ * reconciles with Stripe by construction: it is Stripe's own number, verbatim.
+ *
+ * `taxCents` was described here as likewise `total_details.amount_tax`, Stripe's
+ * own. On the cart path it is. On the BUY-NOW path it was 0 on every order,
+ * because `checkout.ts` sends manual destination tax as an ordinary
+ * `line_items[1]` product line that Stripe never classifies as tax — so this
+ * `value` reported tax-inclusive gross into the merchant's property, the
+ * AGL-1639 overstatement, live. AGL-1711 composes the stored `taxCents` from
+ * `amount_tax` plus that line-item tax, and fixes `quantity` and
+ * `unitAmountCents` (hardcoded to 1 and to the whole charge) in the same place.
+ * Nothing here changed: the three fields this reads are simply true now.
+ *
+ * The parts used NOT to reconcile, and that is why this derivation exists.
+ * `computeOrderTotals` was called with `feeCents`, `taxCents` and
+ * `discountCents` but **never `shippingCents`**, so a stored `OrderTotals`
+ * recorded `shippingCents: 0` on every online order while the shipping the
+ * shopper paid sat inside `amount_total`. Building `value` from
+ * `itemsCents + shippingCents - discountCents` would therefore have silently
+ * dropped all shipping revenue, understating orders that carried it and
+ * leaving orders that did not looking correct. Same failure shape as the
+ * AGL-1639 overstatement, opposite sign.
+ *
+ * AGL-1698 fixed the storage — `computeCheckoutSessionTotals` passes
+ * `total_details.amount_shipping`, and the parts now sum to the total. The
+ * derivation stays on `totalCents` anyway, for a reason that outlives the bug:
+ * `totalCents` is Stripe's `amount_total` verbatim, whereas `itemsCents` is
+ * priced from the host's product docs, so a price edit between session
+ * creation and webhook delivery would make our sum disagree with the charge.
+ *
+ * ## A GA4 `shipping` param IS sent — and a `tax` one still is not
+ *
+ * These two look like an inconsistency and are not. Do not tidy them into
+ * agreement in either direction (AGL-1722).
+ *
+ * `shipping` is a COMPONENT of the `value` reported beside it: `value` is
+ * `totalCents - taxCents`, and the shipping the shopper paid is inside that
+ * number. GA4's `shipping` is documented as exactly that — shipping charged
+ * ON the transaction — so sending it decomposes the value rather than
+ * contradicting it, and a merchant can read "of the $105 you sold, $10 was
+ * shipping" without any figure being counted twice.
+ *
+ * `tax` is the opposite: `value` already EXCLUDES it. Sending a `tax` beside
+ * an ex-tax `value` asserts a relationship that does not hold and invites the
+ * subtraction that removes tax a second time. AGL-1639 and AGL-1641 both
+ * declined it for that reason and this change does not disturb them.
+ *
+ * The param was withheld until now for a truthfulness reason that has since
+ * expired twice. AGL-1641 left it out because the stored `shippingCents` was
+ * structurally 0 — sending it would have asserted FREE SHIPPING on every
+ * order rather than saying nothing. AGL-1698 fixed the storage but the Stripe
+ * figure was still structurally 0, because no Checkout Session we created
+ * declared `shipping_options`. AGL-1707 wired the merchant's configured zones
+ * and rates into the cart session and AGL-1720 into the buy-now one, so
+ * `amount_shipping` is a real number on both storefront paths for a merchant
+ * who set shipping up. Only the plumbing was left, and it is built here:
+ * `shippingCents` rides `StorefrontPurchaseSource` to the wire shape.
+ *
+ * A 0 now means what it says. A download ships nothing, a merchant who saved
+ * no rates charges nothing, and POS and draft orders resolve no shipping — on
+ * all of those `shipping: 0` is a true statement about that order, not the old
+ * structural zero, so it is sent rather than omitted. Omitting it would leave
+ * the merchant's shipping column sparse for a reason GA cannot tell apart from
+ * "not tracked".
+ *
+ * ## Worked example — the spec fixture
+ *
+ * A $100 item, a $5 coupon, $10 shipping chosen at Stripe Checkout, $9.08 tax,
+ * and a 5% Aglyn fee:
+ *
+ *   itemsCents            10000   line snapshot
+ *   - discountCents         500   Stripe `total_details.amount_discount`
+ *   + shippingCents        1000   Stripe `total_details.amount_shipping`
+ *   + taxCents              908   Stripe `total_details.amount_tax`
+ *   = totalCents          11408   Stripe `amount_total`, verbatim
+ *   - taxCents            - 908   held for the state, not revenue
+ *   = GA `value`          10500   sent as 105.00 (goods 95.00 + shipping 10.00)
+ *     GA `shipping`        1000   sent as 10.00 — INSIDE the 105.00 above, a
+ *                                 decomposition of it and not an addition
+ *     GA `tax`               —    not sent; `value` is already ex-tax
+ *
+ *   feeCents                475   Aglyn's cut — NOT subtracted; the merchant's
+ *                                 cost of sale, and our revenue is reported in
+ *                                 OUR property by the subscription/marketplace
+ *                                 `purchase`, not by this one.
+ *
+ * Before AGL-1698 the stored parts summed to 10408, not 11408: the 1000 gap was
+ * the shipping, and it is exactly what a parts-based `value` would have lost.
+ * They reconcile now, which `commerce-orders.spec.ts` pins; the guard below
+ * survives as a guard, since the derivation must not drift back to the parts.
+ *
+ * Returns `null` when there is nothing truthful to send — no transaction id,
+ * or a non-positive value. A dropped event is a gap in the merchant's report;
+ * a fabricated one is a wrong number in it, and the second is worse.
+ */ export function buildStorefrontPurchaseParams(source) {
+    var _ref, _ref1, _ref2, _ref3, _ref4;
+    const transactionId = String((_ref = source == null ? void 0 : source.transactionId) != null ? _ref : '').trim();
+    if (!transactionId) return null;
+    const totalCents = Math.round(Number((_ref1 = source == null ? void 0 : source.totalCents) != null ? _ref1 : 0));
+    const taxCents = Math.max(0, Math.round(Number((_ref2 = source == null ? void 0 : source.taxCents) != null ? _ref2 : 0)));
+    const netCents = totalCents - taxCents;
+    if (!Number.isFinite(netCents) || netCents <= 0) return null;
+    // Clamped like `taxCents`, and for the same reason: a negative component
+    // would be subtracted out of a `value` that does not move with it.
+    const shippingCents = Math.max(0, Math.round(Number((_ref3 = source == null ? void 0 : source.shippingCents) != null ? _ref3 : 0)));
+    return {
+        transaction_id: transactionId,
+        // No currency is stored on an order and `buildBeginCheckoutParams` takes
+        // the same default, so the storefront's two ecommerce events agree.
+        currency: 'USD',
+        value: toAmount(netCents),
+        // ALWAYS sent, including as 0. `value` is ex-tax and shipping is inside
+        // it, so `shipping` describes the number beside it rather than adding to
+        // it — and 0 is a true statement about an order that carried no shipping
+        // (a download, a merchant who configured no rates, POS, a draft), not the
+        // old structural zero. Omitting it on those would leave the merchant's
+        // shipping column sparse for a reason GA cannot distinguish from "not
+        // tracked".
+        shipping: toAmount(shippingCents),
+        items: ((_ref4 = source == null ? void 0 : source.lineItems) != null ? _ref4 : []).map((line)=>{
+            var _ref, _ref1, _ref2, _ref3;
+            return {
+                // The PRODUCT id, matching `view_item` / `add_to_cart` /
+                // `begin_checkout`, so GA joins all four into one per-product funnel.
+                // A variant id here would break that join at the last step.
+                item_id: String((_ref = line == null ? void 0 : line.productId) != null ? _ref : ''),
+                item_name: String((_ref1 = line == null ? void 0 : line.name) != null ? _ref1 : ''),
+                price: toAmount(Number((_ref2 = line == null ? void 0 : line.unitAmountCents) != null ? _ref2 : 0)),
+                quantity: Number((_ref3 = line == null ? void 0 : line.quantity) != null ? _ref3 : 1)
+            };
+        })
+    };
+}
+/**
+ * Reduce a stored order to the wire shape above. Server-side only — it reads
+ * fields the projection exists to withhold.
+ */ export function toStorefrontPurchaseSource(transactionId, order) {
+    var _ref, _ref1, _ref2, _ref3;
+    var _order_totals, _order_totals1, _order_totals2;
+    return {
+        transactionId,
+        totalCents: Number((_ref = order == null ? void 0 : (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref : 0),
+        taxCents: Number((_ref1 = order == null ? void 0 : (_order_totals1 = order.totals) == null ? void 0 : _order_totals1.taxCents) != null ? _ref1 : 0),
+        shippingCents: Number((_ref2 = order == null ? void 0 : (_order_totals2 = order.totals) == null ? void 0 : _order_totals2.shippingCents) != null ? _ref2 : 0),
+        lineItems: ((_ref3 = order == null ? void 0 : order.lineItems) != null ? _ref3 : []).map((line)=>{
+            var _ref, _ref1, _ref2, _ref3;
+            return {
+                productId: String((_ref = line == null ? void 0 : line.productId) != null ? _ref : ''),
+                name: String((_ref1 = line == null ? void 0 : line.name) != null ? _ref1 : ''),
+                quantity: Number((_ref2 = line == null ? void 0 : line.quantity) != null ? _ref2 : 1),
+                unitAmountCents: Number((_ref3 = line == null ? void 0 : line.unitAmountCents) != null ? _ref3 : 0)
+            };
+        })
+    };
+}
+
+//# sourceMappingURL=purchase-analytics.js.map

package/src/lib/model/purchase-analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/purchase-analytics.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 { AnalyticsEventParams } from '@aglyn/aglyn/app-utils/analytics-events'\nimport type { HostOrder } from './commerce-orders'\n\n/**\n * The GA-safe projection of a storefront order (AGL-1641). Deliberately NOT\n * `HostOrder`: this shape crosses the wire to a shopper's browser, so it can\n * only ever hold what a `purchase` event needs. `customerEmail`,\n * `customerName`, `shippingAddress` and `billingAddress` are absent by\n * construction rather than by a `delete` somebody has to remember.\n */\nexport interface StorefrontPurchaseSource {\n  /** Stripe Checkout Session id — also the order doc id. */\n  transactionId: string\n  totalCents: number\n  taxCents: number\n  /**\n   * Stripe's `total_details.amount_shipping` as the webhook stored it — or\n   * `shipping_cost.amount_total` on a subscription invoice, which has no\n   * `total_details`. Reported as GA4's `shipping`, NOT subtracted from\n   * `value`: it is part of what the merchant sold.\n   */\n  shippingCents: number\n  lineItems: {\n    productId: string\n    name: string\n    quantity: number\n    unitAmountCents: number\n  }[]\n}\n\n/** Money, to two decimals. A float sum of cents produces `59.99999999999999`. */\nfunction toAmount(cents: number): number {\n  return Math.round(cents) / 100\n}\n\n/**\n * Build the `purchase` a TENANT STOREFRONT reports to the MERCHANT's GA4\n * property (AGL-1641).\n *\n * ## Whose revenue this is — the decision, not an inference\n *\n * This is the exact inverse of the marketplace call in AGL-1639, and the\n * reason is the property the hit lands in. There, the GA property is OURS, the\n * platform fee IS what Aglyn was paid, and `value` had to be platform net so\n * that a marketplace sale and a subscription meant the same thing when GA\n * added them up. Here the property is the MERCHANT's — `gtag` on a tenant site\n * is loaded with `host.analytics.gaMeasurementId`, their measurement id — and\n * on their storefront the merchant is the seller. Aglyn's cut is not a share\n * of this sale from their side; it is a cost of making it.\n *\n * So `feeCents` is NOT subtracted. Subtracting it would report the merchant's\n * gross margin after our fee as though it were their sales revenue, which is\n * not a number any merchant's books, tax return or ad platform recognises.\n *\n * Getting this backwards is the expensive mistake: reporting platform net into\n * a merchant's property would show every merchant on Aglyn a revenue figure a\n * few percent of their real one.\n *\n * ## Tax is excluded, and no `tax` param is sent\n *\n * Tax collected is money held for a taxing authority, not revenue, whoever\n * holds it — and on a storefront that is often Aglyn rather than the merchant,\n * since Terms §10.7 makes Aglyn a marketplace facilitator where applicable law\n * gives it a collection obligation (AGL-1956). Either way it is not the\n * merchant's sales revenue. Every mature ecommerce integration reports revenue\n * ex-tax and so do we.\n *\n * No GA4 `tax` param either, following AGL-1639 for the same reason it applied\n * there: `value` already EXCLUDES tax, and GA4's `tax` is documented as a cost\n * associated with the transaction — a component of the value beside it. Sent\n * next to an ex-tax `value` it asserts a relationship that does not hold, and\n * invites exactly the subtraction that would double-remove it.\n *\n * ## Why `value` derives from `totalCents` and not from the parts\n *\n * `totalCents` is overwritten with Stripe's `amount_total` when the webhook\n * writes the order (`billing-webhook.ts`), so it is the one field that\n * reconciles with Stripe by construction: it is Stripe's own number, verbatim.\n *\n * `taxCents` was described here as likewise `total_details.amount_tax`, Stripe's\n * own. On the cart path it is. On the BUY-NOW path it was 0 on every order,\n * because `checkout.ts` sends manual destination tax as an ordinary\n * `line_items[1]` product line that Stripe never classifies as tax — so this\n * `value` reported tax-inclusive gross into the merchant's property, the\n * AGL-1639 overstatement, live. AGL-1711 composes the stored `taxCents` from\n * `amount_tax` plus that line-item tax, and fixes `quantity` and\n * `unitAmountCents` (hardcoded to 1 and to the whole charge) in the same place.\n * Nothing here changed: the three fields this reads are simply true now.\n *\n * The parts used NOT to reconcile, and that is why this derivation exists.\n * `computeOrderTotals` was called with `feeCents`, `taxCents` and\n * `discountCents` but **never `shippingCents`**, so a stored `OrderTotals`\n * recorded `shippingCents: 0` on every online order while the shipping the\n * shopper paid sat inside `amount_total`. Building `value` from\n * `itemsCents + shippingCents - discountCents` would therefore have silently\n * dropped all shipping revenue, understating orders that carried it and\n * leaving orders that did not looking correct. Same failure shape as the\n * AGL-1639 overstatement, opposite sign.\n *\n * AGL-1698 fixed the storage — `computeCheckoutSessionTotals` passes\n * `total_details.amount_shipping`, and the parts now sum to the total. The\n * derivation stays on `totalCents` anyway, for a reason that outlives the bug:\n * `totalCents` is Stripe's `amount_total` verbatim, whereas `itemsCents` is\n * priced from the host's product docs, so a price edit between session\n * creation and webhook delivery would make our sum disagree with the charge.\n *\n * ## A GA4 `shipping` param IS sent — and a `tax` one still is not\n *\n * These two look like an inconsistency and are not. Do not tidy them into\n * agreement in either direction (AGL-1722).\n *\n * `shipping` is a COMPONENT of the `value` reported beside it: `value` is\n * `totalCents - taxCents`, and the shipping the shopper paid is inside that\n * number. GA4's `shipping` is documented as exactly that — shipping charged\n * ON the transaction — so sending it decomposes the value rather than\n * contradicting it, and a merchant can read \"of the $105 you sold, $10 was\n * shipping\" without any figure being counted twice.\n *\n * `tax` is the opposite: `value` already EXCLUDES it. Sending a `tax` beside\n * an ex-tax `value` asserts a relationship that does not hold and invites the\n * subtraction that removes tax a second time. AGL-1639 and AGL-1641 both\n * declined it for that reason and this change does not disturb them.\n *\n * The param was withheld until now for a truthfulness reason that has since\n * expired twice. AGL-1641 left it out because the stored `shippingCents` was\n * structurally 0 — sending it would have asserted FREE SHIPPING on every\n * order rather than saying nothing. AGL-1698 fixed the storage but the Stripe\n * figure was still structurally 0, because no Checkout Session we created\n * declared `shipping_options`. AGL-1707 wired the merchant's configured zones\n * and rates into the cart session and AGL-1720 into the buy-now one, so\n * `amount_shipping` is a real number on both storefront paths for a merchant\n * who set shipping up. Only the plumbing was left, and it is built here:\n * `shippingCents` rides `StorefrontPurchaseSource` to the wire shape.\n *\n * A 0 now means what it says. A download ships nothing, a merchant who saved\n * no rates charges nothing, and POS and draft orders resolve no shipping — on\n * all of those `shipping: 0` is a true statement about that order, not the old\n * structural zero, so it is sent rather than omitted. Omitting it would leave\n * the merchant's shipping column sparse for a reason GA cannot tell apart from\n * \"not tracked\".\n *\n * ## Worked example — the spec fixture\n *\n * A $100 item, a $5 coupon, $10 shipping chosen at Stripe Checkout, $9.08 tax,\n * and a 5% Aglyn fee:\n *\n *   itemsCents            10000   line snapshot\n *   - discountCents         500   Stripe `total_details.amount_discount`\n *   + shippingCents        1000   Stripe `total_details.amount_shipping`\n *   + taxCents              908   Stripe `total_details.amount_tax`\n *   = totalCents          11408   Stripe `amount_total`, verbatim\n *   - taxCents            - 908   held for the state, not revenue\n *   = GA `value`          10500   sent as 105.00 (goods 95.00 + shipping 10.00)\n *     GA `shipping`        1000   sent as 10.00 — INSIDE the 105.00 above, a\n *                                 decomposition of it and not an addition\n *     GA `tax`               —    not sent; `value` is already ex-tax\n *\n *   feeCents                475   Aglyn's cut — NOT subtracted; the merchant's\n *                                 cost of sale, and our revenue is reported in\n *                                 OUR property by the subscription/marketplace\n *                                 `purchase`, not by this one.\n *\n * Before AGL-1698 the stored parts summed to 10408, not 11408: the 1000 gap was\n * the shipping, and it is exactly what a parts-based `value` would have lost.\n * They reconcile now, which `commerce-orders.spec.ts` pins; the guard below\n * survives as a guard, since the derivation must not drift back to the parts.\n *\n * Returns `null` when there is nothing truthful to send — no transaction id,\n * or a non-positive value. A dropped event is a gap in the merchant's report;\n * a fabricated one is a wrong number in it, and the second is worse.\n */\nexport function buildStorefrontPurchaseParams(\n  source: StorefrontPurchaseSource,\n): AnalyticsEventParams['purchase'] | null {\n  const transactionId = String(source?.transactionId ?? '').trim()\n  if (!transactionId) return null\n\n  const totalCents = Math.round(Number(source?.totalCents ?? 0))\n  const taxCents = Math.max(0, Math.round(Number(source?.taxCents ?? 0)))\n  const netCents = totalCents - taxCents\n  if (!Number.isFinite(netCents) || netCents <= 0) return null\n  // Clamped like `taxCents`, and for the same reason: a negative component\n  // would be subtracted out of a `value` that does not move with it.\n  const shippingCents = Math.max(0, Math.round(Number(source?.shippingCents ?? 0)))\n\n  return {\n    transaction_id: transactionId,\n    // No currency is stored on an order and `buildBeginCheckoutParams` takes\n    // the same default, so the storefront's two ecommerce events agree.\n    currency: 'USD',\n    value: toAmount(netCents),\n    // ALWAYS sent, including as 0. `value` is ex-tax and shipping is inside\n    // it, so `shipping` describes the number beside it rather than adding to\n    // it — and 0 is a true statement about an order that carried no shipping\n    // (a download, a merchant who configured no rates, POS, a draft), not the\n    // old structural zero. Omitting it on those would leave the merchant's\n    // shipping column sparse for a reason GA cannot distinguish from \"not\n    // tracked\".\n    shipping: toAmount(shippingCents),\n    items: (source?.lineItems ?? []).map((line) => ({\n      // The PRODUCT id, matching `view_item` / `add_to_cart` /\n      // `begin_checkout`, so GA joins all four into one per-product funnel.\n      // A variant id here would break that join at the last step.\n      item_id: String(line?.productId ?? ''),\n      item_name: String(line?.name ?? ''),\n      price: toAmount(Number(line?.unitAmountCents ?? 0)),\n      quantity: Number(line?.quantity ?? 1),\n    })),\n    // No `billing_interval`: a storefront order is not a subscription.\n  }\n}\n\n/**\n * Reduce a stored order to the wire shape above. Server-side only — it reads\n * fields the projection exists to withhold.\n */\nexport function toStorefrontPurchaseSource(\n  transactionId: string,\n  order: Pick<HostOrder, 'totals' | 'lineItems'>,\n): StorefrontPurchaseSource {\n  return {\n    transactionId,\n    totalCents: Number(order?.totals?.totalCents ?? 0),\n    taxCents: Number(order?.totals?.taxCents ?? 0),\n    shippingCents: Number(order?.totals?.shippingCents ?? 0),\n    lineItems: (order?.lineItems ?? []).map((line) => ({\n      productId: String(line?.productId ?? ''),\n      name: String(line?.name ?? ''),\n      quantity: Number(line?.quantity ?? 1),\n      unitAmountCents: Number(line?.unitAmountCents ?? 0),\n    })),\n  }\n}\n"],"names":["toAmount","cents","Math","round","buildStorefrontPurchaseParams","source","transactionId","String","trim","totalCents","Number","taxCents","max","netCents","isFinite","shippingCents","transaction_id","currency","value","shipping","items","lineItems","map","line","item_id","productId","item_name","name","price","unitAmountCents","quantity","toStorefrontPurchaseSource","order","totals"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAgCD,+EAA+E,GAC/E,SAASA,SAASC,KAAa;IAC7B,OAAOC,KAAKC,KAAK,CAACF,SAAS;AAC7B;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuIC,GACD,OAAO,SAASG,8BACdC,MAAgC;;IAEhC,MAAMC,gBAAgBC,eAAOF,0BAAAA,OAAQC,aAAa,mBAAI,IAAIE,IAAI;IAC9D,IAAI,CAACF,eAAe,OAAO;IAE3B,MAAMG,aAAaP,KAAKC,KAAK,CAACO,gBAAOL,0BAAAA,OAAQI,UAAU,oBAAI;IAC3D,MAAME,WAAWT,KAAKU,GAAG,CAAC,GAAGV,KAAKC,KAAK,CAACO,gBAAOL,0BAAAA,OAAQM,QAAQ,oBAAI;IACnE,MAAME,WAAWJ,aAAaE;IAC9B,IAAI,CAACD,OAAOI,QAAQ,CAACD,aAAaA,YAAY,GAAG,OAAO;IACxD,yEAAyE;IACzE,mEAAmE;IACnE,MAAME,gBAAgBb,KAAKU,GAAG,CAAC,GAAGV,KAAKC,KAAK,CAACO,gBAAOL,0BAAAA,OAAQU,aAAa,oBAAI;IAE7E,OAAO;QACLC,gBAAgBV;QAChB,yEAAyE;QACzE,oEAAoE;QACpEW,UAAU;QACVC,OAAOlB,SAASa;QAChB,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,0EAA0E;QAC1E,uEAAuE;QACvE,sEAAsE;QACtE,YAAY;QACZM,UAAUnB,SAASe;QACnBK,OAAO,UAACf,0BAAAA,OAAQgB,SAAS,oBAAI,EAAE,EAAEC,GAAG,CAAC,CAACC;;mBAAU;gBAC9C,yDAAyD;gBACzD,sEAAsE;gBACtE,4DAA4D;gBAC5DC,SAASjB,eAAOgB,wBAAAA,KAAME,SAAS,mBAAI;gBACnCC,WAAWnB,gBAAOgB,wBAAAA,KAAMI,IAAI,oBAAI;gBAChCC,OAAO5B,SAASU,gBAAOa,wBAAAA,KAAMM,eAAe,oBAAI;gBAChDC,UAAUpB,gBAAOa,wBAAAA,KAAMO,QAAQ,oBAAI;YACrC;;IAEF;AACF;AAEA;;;CAGC,GACD,OAAO,SAASC,2BACdzB,aAAqB,EACrB0B,KAA8C;;QAIzBA,eACFA,gBACKA;IAJxB,OAAO;QACL1B;QACAG,YAAYC,eAAOsB,0BAAAA,gBAAAA,MAAOC,MAAM,qBAAbD,cAAevB,UAAU,mBAAI;QAChDE,UAAUD,gBAAOsB,0BAAAA,iBAAAA,MAAOC,MAAM,qBAAbD,eAAerB,QAAQ,oBAAI;QAC5CI,eAAeL,gBAAOsB,0BAAAA,iBAAAA,MAAOC,MAAM,qBAAbD,eAAejB,aAAa,oBAAI;QACtDM,WAAW,UAACW,yBAAAA,MAAOX,SAAS,oBAAI,EAAE,EAAEC,GAAG,CAAC,CAACC;;mBAAU;gBACjDE,WAAWlB,eAAOgB,wBAAAA,KAAME,SAAS,mBAAI;gBACrCE,MAAMpB,gBAAOgB,wBAAAA,KAAMI,IAAI,oBAAI;gBAC3BG,UAAUpB,gBAAOa,wBAAAA,KAAMO,QAAQ,oBAAI;gBACnCD,iBAAiBnB,gBAAOa,wBAAAA,KAAMM,eAAe,oBAAI;YACnD;;IACF;AACF"}

package/src/lib/plugin-config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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 { PluginConfigSchema } from '@aglyn/aglyn';
+/**
+ * The ceiling a register may discount to, when the merchant has not set one
+ * (AGL-2161).
+ *
+ * 100, i.e. today's behaviour exactly. That is deliberate and is the one
+ * number in this fix that is NOT a safety judgement:
+ *
+ * - A full comp is a legitimate register operation — a damaged item, a
+ *   goodwill gesture, a staff meal — and every merchant on the platform has
+ *   had it since POS shipped.
+ * - Any lower default would change what merchants charge their own customers
+ *   on the day it deployed, without them asking. Picking that number is a
+ *   merchant policy decision, not a bug fix, and inventing one here would be
+ *   the same class of mistake as inventing a billing rate.
+ *
+ * What AGL-2161 actually fixes is that there was no ceiling to set and no
+ * refusal when one was exceeded: the request body's `discountPct` was clamped
+ * into range and rung up, so a register sending `150` silently comped the
+ * whole sale. The ceiling is now real, enforced server-side, refused rather
+ * than clamped, and one config value away from being lower.
+ */
+export declare const POS_MAX_DISCOUNT_PCT_DEFAULT = 100;
+/**
+ * Commerce plugin config schema (AGL-428 framework, AGL-2161 adopter).
+ *
+ * PURE DATA (type-only aglyn import), the same shape as bookings': the client
+ * barrel registers it via '@aglyn/aglyn' and the /server entry via
+ * '@aglyn/aglyn/server', so neither bundle drags in the other's barrel.
+ *
+ * `min`/`max` are not decoration — `mergePluginConfig` coerces a stored value
+ * into the declared range and falls back to the default on junk, so the
+ * ceiling itself cannot be forged out of bounds by a manager editing the
+ * settings doc directly.
+ */
+export declare const COMMERCE_CONFIG_SCHEMA: PluginConfigSchema;
+/**
+ * The ceiling for one org, read defensively (AGL-2161).
+ *
+ * Spelled here rather than at the call site so the POS route and any later
+ * reader cannot disagree about what a missing or malformed value means. The
+ * framework has already clamped and defaulted by the time this runs; the
+ * second `Number.isFinite` guard is for the schema-less case, where
+ * `getPluginConfig` returns the raw doc untouched.
+ */
+export declare function posMaxDiscountPct(config: Record<string, unknown> | null | undefined): number;

package/src/lib/plugin-config.js

@@ -0,0 +1,78 @@
+/**
+ * @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.
+ */ /**
+ * The ceiling a register may discount to, when the merchant has not set one
+ * (AGL-2161).
+ *
+ * 100, i.e. today's behaviour exactly. That is deliberate and is the one
+ * number in this fix that is NOT a safety judgement:
+ *
+ * - A full comp is a legitimate register operation — a damaged item, a
+ *   goodwill gesture, a staff meal — and every merchant on the platform has
+ *   had it since POS shipped.
+ * - Any lower default would change what merchants charge their own customers
+ *   on the day it deployed, without them asking. Picking that number is a
+ *   merchant policy decision, not a bug fix, and inventing one here would be
+ *   the same class of mistake as inventing a billing rate.
+ *
+ * What AGL-2161 actually fixes is that there was no ceiling to set and no
+ * refusal when one was exceeded: the request body's `discountPct` was clamped
+ * into range and rung up, so a register sending `150` silently comped the
+ * whole sale. The ceiling is now real, enforced server-side, refused rather
+ * than clamped, and one config value away from being lower.
+ */ export const POS_MAX_DISCOUNT_PCT_DEFAULT = 100;
+/**
+ * Commerce plugin config schema (AGL-428 framework, AGL-2161 adopter).
+ *
+ * PURE DATA (type-only aglyn import), the same shape as bookings': the client
+ * barrel registers it via '@aglyn/aglyn' and the /server entry via
+ * '@aglyn/aglyn/server', so neither bundle drags in the other's barrel.
+ *
+ * `min`/`max` are not decoration — `mergePluginConfig` coerces a stored value
+ * into the declared range and falls back to the default on junk, so the
+ * ceiling itself cannot be forged out of bounds by a manager editing the
+ * settings doc directly.
+ */ export const COMMERCE_CONFIG_SCHEMA = {
+    pluginId: 'commerce',
+    fields: [
+        {
+            key: 'posMaxDiscountPct',
+            label: 'Maximum register discount (%)',
+            type: 'number',
+            min: 0,
+            max: 100,
+            description: 'The largest discount the point of sale will accept on a sale. ' + 'A register that asks for more is refused, and the sale is not rung ' + 'up. Set to 0 to stop staff discounting at the register entirely.'
+        }
+    ],
+    defaults: {
+        posMaxDiscountPct: POS_MAX_DISCOUNT_PCT_DEFAULT
+    }
+};
+/**
+ * The ceiling for one org, read defensively (AGL-2161).
+ *
+ * Spelled here rather than at the call site so the POS route and any later
+ * reader cannot disagree about what a missing or malformed value means. The
+ * framework has already clamped and defaulted by the time this runs; the
+ * second `Number.isFinite` guard is for the schema-less case, where
+ * `getPluginConfig` returns the raw doc untouched.
+ */ export function posMaxDiscountPct(config) {
+    const raw = Number(config == null ? void 0 : config['posMaxDiscountPct']);
+    if (!Number.isFinite(raw)) return POS_MAX_DISCOUNT_PCT_DEFAULT;
+    return Math.min(100, Math.max(0, raw));
+}
+
+//# sourceMappingURL=plugin-config.js.map

package/src/lib/plugin-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/commerce/src/lib/plugin-config.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 { PluginConfigSchema } from '@aglyn/aglyn'\n\n/**\n * The ceiling a register may discount to, when the merchant has not set one\n * (AGL-2161).\n *\n * 100, i.e. today's behaviour exactly. That is deliberate and is the one\n * number in this fix that is NOT a safety judgement:\n *\n * - A full comp is a legitimate register operation — a damaged item, a\n *   goodwill gesture, a staff meal — and every merchant on the platform has\n *   had it since POS shipped.\n * - Any lower default would change what merchants charge their own customers\n *   on the day it deployed, without them asking. Picking that number is a\n *   merchant policy decision, not a bug fix, and inventing one here would be\n *   the same class of mistake as inventing a billing rate.\n *\n * What AGL-2161 actually fixes is that there was no ceiling to set and no\n * refusal when one was exceeded: the request body's `discountPct` was clamped\n * into range and rung up, so a register sending `150` silently comped the\n * whole sale. The ceiling is now real, enforced server-side, refused rather\n * than clamped, and one config value away from being lower.\n */\nexport const POS_MAX_DISCOUNT_PCT_DEFAULT = 100\n\n/**\n * Commerce plugin config schema (AGL-428 framework, AGL-2161 adopter).\n *\n * PURE DATA (type-only aglyn import), the same shape as bookings': the client\n * barrel registers it via '@aglyn/aglyn' and the /server entry via\n * '@aglyn/aglyn/server', so neither bundle drags in the other's barrel.\n *\n * `min`/`max` are not decoration — `mergePluginConfig` coerces a stored value\n * into the declared range and falls back to the default on junk, so the\n * ceiling itself cannot be forged out of bounds by a manager editing the\n * settings doc directly.\n */\nexport const COMMERCE_CONFIG_SCHEMA: PluginConfigSchema = {\n  pluginId: 'commerce',\n  fields: [\n    {\n      key: 'posMaxDiscountPct',\n      label: 'Maximum register discount (%)',\n      type: 'number',\n      min: 0,\n      max: 100,\n      description:\n        'The largest discount the point of sale will accept on a sale. ' +\n        'A register that asks for more is refused, and the sale is not rung ' +\n        'up. Set to 0 to stop staff discounting at the register entirely.',\n    },\n  ],\n  defaults: { posMaxDiscountPct: POS_MAX_DISCOUNT_PCT_DEFAULT },\n}\n\n/**\n * The ceiling for one org, read defensively (AGL-2161).\n *\n * Spelled here rather than at the call site so the POS route and any later\n * reader cannot disagree about what a missing or malformed value means. The\n * framework has already clamped and defaulted by the time this runs; the\n * second `Number.isFinite` guard is for the schema-less case, where\n * `getPluginConfig` returns the raw doc untouched.\n */\nexport function posMaxDiscountPct(\n  config: Record<string, unknown> | null | undefined,\n): number {\n  const raw = Number(config?.['posMaxDiscountPct'])\n  if (!Number.isFinite(raw)) return POS_MAX_DISCOUNT_PCT_DEFAULT\n  return Math.min(100, Math.max(0, raw))\n}\n"],"names":["POS_MAX_DISCOUNT_PCT_DEFAULT","COMMERCE_CONFIG_SCHEMA","pluginId","fields","key","label","type","min","max","description","defaults","posMaxDiscountPct","config","raw","Number","isFinite","Math"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAMA,+BAA+B,IAAG;AAE/C;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,yBAA6C;IACxDC,UAAU;IACVC,QAAQ;QACN;YACEC,KAAK;YACLC,OAAO;YACPC,MAAM;YACNC,KAAK;YACLC,KAAK;YACLC,aACE,mEACA,wEACA;QACJ;KACD;IACDC,UAAU;QAAEC,mBAAmBX;IAA6B;AAC9D,EAAC;AAED;;;;;;;;CAQC,GACD,OAAO,SAASW,kBACdC,MAAkD;IAElD,MAAMC,MAAMC,OAAOF,0BAAAA,MAAQ,CAAC,oBAAoB;IAChD,IAAI,CAACE,OAAOC,QAAQ,CAACF,MAAM,OAAOb;IAClC,OAAOgB,KAAKT,GAAG,CAAC,KAAKS,KAAKR,GAAG,CAAC,GAAGK;AACnC"}

package/src/lib/plugin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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.
+ */
+/**
+ * Console half (AGL-395): registers the Products nav item in the
+ * ConsoleExtension registry so the commerce console surface is owned by the
+ * plugin, like events and email. The page body still lives in the console
+ * app (`/[hostId]/products`): its product editor depends on the app's media
+ * browser, which transitively pulls in the org/session context, so a full
+ * body relocation needs a plugin-consumable media-picker context first —
+ * tracked as follow-up. The nav item omits a `Component`, so the shell's
+ * nav renders the link and the existing named route serves the page.
+ */
+export declare function registerCommerceConsole(): void;
+export * from './site';

package/src/lib/plugin.js

@@ -0,0 +1,147 @@
+/**
+ * @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 Aglyn from "@aglyn/aglyn";
+import { mdiStorefrontOutline } from "@aglyn/shared-data-mdi";
+import { lazy } from "react";
+const PosConsolePage = lazy(()=>import("./components/console/pos-page.component.js"));
+const CommerceGlanceCard = lazy(()=>import("./components/console/commerce-glance-card.component.js"));
+const NewestSiteUsersCard = lazy(()=>import("./components/console/newest-site-users-card.component.js"));
+import { COMMERCE_CONSOLE_SECTIONS } from "./components/commerce-console-sections.js";
+import { BUNDLE_ID } from "./constants/bundle-common.js";
+import { COMMERCE_PERMISSIONS } from "./model/plugin-permissions.js";
+import { COMMERCE_CONFIG_SCHEMA } from "./plugin-config.js";
+/** Code-split: the Products console page only loads when opened. */ const CommerceConsolePage = lazy(()=>import("./components/commerce-console-page.js"));
+/**
+ * Console half (AGL-395): registers the Products nav item in the
+ * ConsoleExtension registry so the commerce console surface is owned by the
+ * plugin, like events and email. The page body still lives in the console
+ * app (`/[hostId]/products`): its product editor depends on the app's media
+ * browser, which transitively pulls in the org/session context, so a full
+ * body relocation needs a plugin-consumable media-picker context first —
+ * tracked as follow-up. The nav item omits a `Component`, so the shell's
+ * nav renders the link and the existing named route serves the page.
+ */ export function registerCommerceConsole() {
+    // Plugin-declared permissions (AGL-435): tier defaults ride every
+    // resolved role set; custom roles override key-by-key.
+    Aglyn.registerPluginPermissions(COMMERCE_PERMISSIONS);
+    // Register discount ceiling (AGL-2161) — the generic settings card renders
+    // it from this schema, so there is no bespoke UI to keep in sync.
+    Aglyn.registerPluginConfigSchema(COMMERCE_CONFIG_SCHEMA);
+    Aglyn.registerConsoleExtension({
+        pluginId: BUNDLE_ID,
+        displayName: 'Commerce',
+        // Dashboard/analytics glance card (AGL-419): rendered through the
+        // shell's 'commerceGlance' widget slot.
+        widgets: [
+            {
+                slot: 'commerceGlance',
+                widgetId: 'commerce-glance',
+                title: 'Commerce',
+                Component: CommerceGlanceCard
+            }
+        ],
+        navItems: [
+            {
+                label: 'Products',
+                href: '/products',
+                icon: {
+                    path: mdiStorefrontOutline.path
+                },
+                // Sections as ROUTES (AGL-2501): `/products/orders` and friends are
+                // real URLs the shell resolves and gates, so the page mounts the one
+                // being read instead of subscribing all six.
+                sections: COMMERCE_CONSOLE_SECTIONS,
+                header: {
+                    title: 'Products',
+                    icon: {
+                        path: mdiStorefrontOutline.path
+                    },
+                    // The overview, not `catalog`: this surface is the whole commerce
+                    // console — Catalog, Orders, Promotions and Reservations.
+                    docsTopic: 'commerce'
+                },
+                Component: CommerceConsolePage
+            },
+            {
+                // POS register (AGL-312/419): relocated from the app's /pos route —
+                // the generic [pluginSlug] shell now serves it at the same URL.
+                label: 'POS',
+                href: '/pos',
+                /*
+         * WHO may open the register, declared on THIS nav item rather than on
+         * the extension.
+         *
+         * A key here narrows one surface; a key on the extension would gate
+         * every surface it registers, and Products is the sibling — a catalog
+         * anyone who works on the site may open. The register is the one that
+         * takes money and lists checked-in guests by name, so the two
+         * genuinely have different answers and only this one is narrowed.
+         *
+         * `managePos` rather than a dotted catalog key because it is the key
+         * the sale itself is refused by: `server/pos-order.ts` resolves the
+         * member's permission map and returns 403 unless `managePos` holds.
+         * The shell answers this declaration out of that same resolved map, so
+         * the console offers a register exactly to the people the route will
+         * accept a sale from — the gate and its server twin cannot disagree,
+         * because they are reading one value.
+         *
+         * `pos-order.ts` stays the enforcement point regardless. This decides
+         * whether the surface is built at all, which is the part a check
+         * inside the page cannot do: by the time the page can refuse itself it
+         * has mounted and its product, register, location and reservation
+         * listeners are already open.
+         */ permission: 'managePos',
+                icon: {
+                    path: mdiStorefrontOutline.path
+                },
+                header: {
+                    title: 'Point of Sale',
+                    docsTopic: 'pos'
+                },
+                Component: PosConsolePage
+            }
+        ]
+    });
+    /*
+   * The USER ACCOUNTS half, registered under its own id.
+   *
+   * `accounts` is a switch rather than a bundle: the member blocks and every
+   * `membership/*` handler ship inside this package, which is why the id
+   * carries no loader manifest entry of its own. A second extension is how a
+   * card about visitor accounts is gated on the switch that decides whether
+   * the site serves them — `listConsoleWidgets` filters by the workspace's
+   * effective plugin ids, and `accounts` is default-OFF per site.
+   *
+   * A separate call rather than more widgets on the commerce extension: the
+   * registry is keyed by `pluginId` and that key IS the gate, so folding this
+   * card in above would have kept the dashboard defect it fixes — `Newest
+   * site users` on a site whose /signin returns 404.
+   */ Aglyn.registerConsoleExtension({
+        pluginId: Aglyn.ACCOUNTS_PLUGIN_ID,
+        displayName: 'User Accounts',
+        widgets: [
+            {
+                slot: Aglyn.CONSOLE_WIDGET_SLOTS.hostDashboard,
+                widgetId: 'accounts-newest-site-users',
+                title: 'Newest site users',
+                Component: NewestSiteUsersCard
+            }
+        ]
+    });
+}
+export * from "./site.js";
+
+//# sourceMappingURL=plugin.js.map

package/src/lib/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/commerce/src/lib/plugin.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 * as Aglyn from '@aglyn/aglyn'\nimport { mdiStorefrontOutline } from '@aglyn/shared-data-mdi'\nimport { lazy } from 'react'\nconst PosConsolePage = lazy(() => import('./components/console/pos-page.component'))\nconst CommerceGlanceCard = lazy(\n  () => import('./components/console/commerce-glance-card.component'),\n)\nconst NewestSiteUsersCard = lazy(\n  () => import('./components/console/newest-site-users-card.component'),\n)\nimport { COMMERCE_CONSOLE_SECTIONS } from './components/commerce-console-sections'\nimport { BUNDLE_ID } from './constants/bundle-common'\nimport { COMMERCE_PERMISSIONS } from './model/plugin-permissions'\nimport { COMMERCE_CONFIG_SCHEMA } from './plugin-config'\n\n/** Code-split: the Products console page only loads when opened. */\nconst CommerceConsolePage = lazy(() => import('./components/commerce-console-page'))\n\n/**\n * Console half (AGL-395): registers the Products nav item in the\n * ConsoleExtension registry so the commerce console surface is owned by the\n * plugin, like events and email. The page body still lives in the console\n * app (`/[hostId]/products`): its product editor depends on the app's media\n * browser, which transitively pulls in the org/session context, so a full\n * body relocation needs a plugin-consumable media-picker context first —\n * tracked as follow-up. The nav item omits a `Component`, so the shell's\n * nav renders the link and the existing named route serves the page.\n */\nexport function registerCommerceConsole(): void {\n  // Plugin-declared permissions (AGL-435): tier defaults ride every\n  // resolved role set; custom roles override key-by-key.\n  Aglyn.registerPluginPermissions(COMMERCE_PERMISSIONS)\n  // Register discount ceiling (AGL-2161) — the generic settings card renders\n  // it from this schema, so there is no bespoke UI to keep in sync.\n  Aglyn.registerPluginConfigSchema(COMMERCE_CONFIG_SCHEMA)\n  Aglyn.registerConsoleExtension({\n    pluginId: BUNDLE_ID,\n    displayName: 'Commerce',\n    // Dashboard/analytics glance card (AGL-419): rendered through the\n    // shell's 'commerceGlance' widget slot.\n    widgets: [\n      {\n        slot: 'commerceGlance',\n        widgetId: 'commerce-glance',\n        title: 'Commerce',\n        Component: CommerceGlanceCard,\n      },\n    ],\n    navItems: [\n      {\n        label: 'Products',\n        href: '/products',\n        icon: { path: mdiStorefrontOutline.path },\n        // Sections as ROUTES (AGL-2501): `/products/orders` and friends are\n        // real URLs the shell resolves and gates, so the page mounts the one\n        // being read instead of subscribing all six.\n        sections: COMMERCE_CONSOLE_SECTIONS,\n        header: {\n          title: 'Products',\n          icon: { path: mdiStorefrontOutline.path },\n          // The overview, not `catalog`: this surface is the whole commerce\n          // console — Catalog, Orders, Promotions and Reservations.\n          docsTopic: 'commerce',\n        },\n        Component: CommerceConsolePage,\n      },\n      {\n        // POS register (AGL-312/419): relocated from the app's /pos route —\n        // the generic [pluginSlug] shell now serves it at the same URL.\n        label: 'POS',\n        href: '/pos',\n        /*\n         * WHO may open the register, declared on THIS nav item rather than on\n         * the extension.\n         *\n         * A key here narrows one surface; a key on the extension would gate\n         * every surface it registers, and Products is the sibling — a catalog\n         * anyone who works on the site may open. The register is the one that\n         * takes money and lists checked-in guests by name, so the two\n         * genuinely have different answers and only this one is narrowed.\n         *\n         * `managePos` rather than a dotted catalog key because it is the key\n         * the sale itself is refused by: `server/pos-order.ts` resolves the\n         * member's permission map and returns 403 unless `managePos` holds.\n         * The shell answers this declaration out of that same resolved map, so\n         * the console offers a register exactly to the people the route will\n         * accept a sale from — the gate and its server twin cannot disagree,\n         * because they are reading one value.\n         *\n         * `pos-order.ts` stays the enforcement point regardless. This decides\n         * whether the surface is built at all, which is the part a check\n         * inside the page cannot do: by the time the page can refuse itself it\n         * has mounted and its product, register, location and reservation\n         * listeners are already open.\n         */\n        permission: 'managePos',\n        icon: { path: mdiStorefrontOutline.path },\n        header: { title: 'Point of Sale', docsTopic: 'pos' },\n        Component: PosConsolePage,\n      },\n    ],\n  })\n  /*\n   * The USER ACCOUNTS half, registered under its own id.\n   *\n   * `accounts` is a switch rather than a bundle: the member blocks and every\n   * `membership/*` handler ship inside this package, which is why the id\n   * carries no loader manifest entry of its own. A second extension is how a\n   * card about visitor accounts is gated on the switch that decides whether\n   * the site serves them — `listConsoleWidgets` filters by the workspace's\n   * effective plugin ids, and `accounts` is default-OFF per site.\n   *\n   * A separate call rather than more widgets on the commerce extension: the\n   * registry is keyed by `pluginId` and that key IS the gate, so folding this\n   * card in above would have kept the dashboard defect it fixes — `Newest\n   * site users` on a site whose /signin returns 404.\n   */\n  Aglyn.registerConsoleExtension({\n    pluginId: Aglyn.ACCOUNTS_PLUGIN_ID,\n    displayName: 'User Accounts',\n    widgets: [\n      {\n        slot: Aglyn.CONSOLE_WIDGET_SLOTS.hostDashboard,\n        widgetId: 'accounts-newest-site-users',\n        title: 'Newest site users',\n        Component: NewestSiteUsersCard,\n      },\n    ],\n  })\n}\n\nexport * from './site'\n"],"names":["Aglyn","mdiStorefrontOutline","lazy","PosConsolePage","CommerceGlanceCard","NewestSiteUsersCard","COMMERCE_CONSOLE_SECTIONS","BUNDLE_ID","COMMERCE_PERMISSIONS","COMMERCE_CONFIG_SCHEMA","CommerceConsolePage","registerCommerceConsole","registerPluginPermissions","registerPluginConfigSchema","registerConsoleExtension","pluginId","displayName","widgets","slot","widgetId","title","Component","navItems","label","href","icon","path","sections","header","docsTopic","permission","ACCOUNTS_PLUGIN_ID","CONSOLE_WIDGET_SLOTS","hostDashboard"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,YAAYA,WAAW,eAAc;AACrC,SAASC,oBAAoB,QAAQ,yBAAwB;AAC7D,SAASC,IAAI,QAAQ,QAAO;AAC5B,MAAMC,iBAAiBD,KAAK,IAAM,MAAM,CAAC;AACzC,MAAME,qBAAqBF,KACzB,IAAM,MAAM,CAAC;AAEf,MAAMG,sBAAsBH,KAC1B,IAAM,MAAM,CAAC;AAEf,SAASI,yBAAyB,QAAQ,4CAAwC;AAClF,SAASC,SAAS,QAAQ,+BAA2B;AACrD,SAASC,oBAAoB,QAAQ,gCAA4B;AACjE,SAASC,sBAAsB,QAAQ,qBAAiB;AAExD,kEAAkE,GAClE,MAAMC,sBAAsBR,KAAK,IAAM,MAAM,CAAC;AAE9C;;;;;;;;;CASC,GACD,OAAO,SAASS;IACd,kEAAkE;IAClE,uDAAuD;IACvDX,MAAMY,yBAAyB,CAACJ;IAChC,2EAA2E;IAC3E,kEAAkE;IAClER,MAAMa,0BAA0B,CAACJ;IACjCT,MAAMc,wBAAwB,CAAC;QAC7BC,UAAUR;QACVS,aAAa;QACb,kEAAkE;QAClE,wCAAwC;QACxCC,SAAS;YACP;gBACEC,MAAM;gBACNC,UAAU;gBACVC,OAAO;gBACPC,WAAWjB;YACb;SACD;QACDkB,UAAU;YACR;gBACEC,OAAO;gBACPC,MAAM;gBACNC,MAAM;oBAAEC,MAAMzB,qBAAqByB,IAAI;gBAAC;gBACxC,oEAAoE;gBACpE,qEAAqE;gBACrE,6CAA6C;gBAC7CC,UAAUrB;gBACVsB,QAAQ;oBACNR,OAAO;oBACPK,MAAM;wBAAEC,MAAMzB,qBAAqByB,IAAI;oBAAC;oBACxC,kEAAkE;oBAClE,0DAA0D;oBAC1DG,WAAW;gBACb;gBACAR,WAAWX;YACb;YACA;gBACE,oEAAoE;gBACpE,gEAAgE;gBAChEa,OAAO;gBACPC,MAAM;gBACN;;;;;;;;;;;;;;;;;;;;;;;SAuBC,GACDM,YAAY;gBACZL,MAAM;oBAAEC,MAAMzB,qBAAqByB,IAAI;gBAAC;gBACxCE,QAAQ;oBAAER,OAAO;oBAAiBS,WAAW;gBAAM;gBACnDR,WAAWlB;YACb;SACD;IACH;IACA;;;;;;;;;;;;;;GAcC,GACDH,MAAMc,wBAAwB,CAAC;QAC7BC,UAAUf,MAAM+B,kBAAkB;QAClCf,aAAa;QACbC,SAAS;YACP;gBACEC,MAAMlB,MAAMgC,oBAAoB,CAACC,aAAa;gBAC9Cd,UAAU;gBACVC,OAAO;gBACPC,WAAWhB;YACb;SACD;IACH;AACF;AAEA,cAAc,YAAQ"}

package/src/lib/server/billing-webhook.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 { BillingWebhookHandler } from '@aglyn/aglyn/server';
+/**
+ * Commerce sections of the platform Stripe webhook (AGL-418): relocated
+ * verbatim from the console route — subscriptions sync, reservations,
+ * cart orders, draft orders, Commerce Starter orders, plus the license-key
+ * assignment helper (AGL-308). Registered via registerCommerceConsoleApi;
+ * every section is idempotent by doc key and self-selects on
+ * `object.metadata.type`, exactly as the inline route sections did.
+ */
+export declare const commerceBillingWebhookHandler: BillingWebhookHandler;