@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/storefront-tax-record.js

@@ -0,0 +1,218 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { firebaseAdmin, getOrgForHost } from "@aglyn/tenant-data-admin";
+import { storefrontTaxRow } from "./storefront-tax.js";
+/**
+ * Writes `storefrontTaxCollected/{stripeId}` for every storefront sale that
+ * carried tax (AGL-1904) — the row that makes tax collected under Aglyn's
+ * registration visible to Aglyn's own quarterly return.
+ *
+ * ## The hole this closes
+ *
+ * AGL-1811 records one `platformRevenue` row per paid invoice and the Texas
+ * return is their sum. That collection is deliberately scoped to AGLYN's own
+ * charges: the console webhook only writes a row when the invoice's customer
+ * resolves through the `stripeCustomers` index, which `writeOrgBilling` stamps
+ * for Aglyn's billing customers and nothing else stamps. A storefront
+ * shopper's customer is never in it.
+ *
+ * That scoping is correct for what it was built for and it left a gap: a
+ * `mode: 'stripe'` storefront sale charges the shopper tax computed on
+ * AGLYN's registrations (measured — see `storefront-tax.ts`), settles it into
+ * Aglyn's platform balance, and NOTHING recorded it anywhere Aglyn's return
+ * could see. The merchant's order document carries a `totals.taxCents`, but
+ * that is the merchant's books, per host, and no return sums it.
+ *
+ * ## Why a SEPARATE collection rather than more `platformRevenue` rows
+ *
+ * Structural, and the reason must survive a future tidy-up: a
+ * `platformRevenue` row's `netCents` is Aglyn's revenue, and a storefront
+ * row's is mostly the MERCHANT's — it transfers straight out to the connected
+ * account. Merging the two would make the return's "total sales" figure silently
+ * include other companies' receipts. Keeping them in different collections
+ * means no query, sum or future refactor can accidentally add them together;
+ * the return reports the storefront figures as their own section, and what
+ * belongs on which line of a filed return stays a question for the preparer
+ * and for counsel rather than one this code answers.
+ *
+ * ## What is recorded, and what is not
+ *
+ * Recorded: cart, buy-now, reservation and draft-order sessions, plus every
+ * storefront subscription INVOICE (opening cycle and renewals both — the
+ * subscription's own `checkout.session.completed` is deliberately skipped so
+ * the opening cycle is not counted twice, the same rule AGL-1811 applies).
+ *
+ * Manual-mode sales are recorded too, with `taxMode: 'manual'`, precisely so
+ * the two modes can be told apart at read time instead of being invisible.
+ * They are NOT Aglyn-collected and the return never sums them into the
+ * Aglyn-liable figure.
+ *
+ * **Refunds are not yet reflected.** A refunded storefront sale keeps its full
+ * tax on this record, so the Aglyn-liable figure is an OVER-statement of what
+ * is owed rather than an under-statement. That direction is deliberate:
+ * over-stating what is held for the state is correctable at filing time,
+ * under-stating it is a shortfall discovered by an auditor. Stated here rather
+ * than left to be discovered.
+ *
+ * Never throws. A recording failure logs and returns — a throw here propagates
+ * through `runBillingWebhookHandlers` into a 500 that Stripe redelivers
+ * forever, which is the AGL-1743 lesson.
+ */ /** The commerce session types that settle money on the platform account. */ const SESSION_TYPES = new Set([
+    'commerce-cart',
+    'commerce-order',
+    'commerce-reservation',
+    'commerce-draft',
+    // A paid service booking (AGL-2000). It carries no tax by a stated
+    // decision (`bookings/server.ts`), but it is a storefront sale and it was
+    // absent from this set entirely — so it was not merely untaxed, it did not
+    // appear in the record that would let anyone NOTICE it was untaxed or
+    // reconcile it later. An untaxed sale that is recorded reads
+    // `taxMode: 'none'`; an unrecorded one reads as nothing at all.
+    'booking-payment'
+]);
+/**
+ * Session types whose zero tax is a decision taken HERE, not by the merchant
+ * (AGL-2000). Their rows are filed even at `taxMode: 'none'`, so an untaxed
+ * service or stay is reconcilable instead of merely missing. See the note at
+ * the `taxMode === 'none'` gate below.
+ */ const PLATFORM_UNTAXED_TYPES = new Set([
+    'booking-payment',
+    'commerce-reservation'
+]);
+function stripeKey() {
+    var _process_env_STRIPE_SECRET_KEY;
+    return String((_process_env_STRIPE_SECRET_KEY = process.env.STRIPE_SECRET_KEY) != null ? _process_env_STRIPE_SECRET_KEY : '');
+}
+/**
+ * A Checkout Session's tax BREAKDOWN, which the webhook payload does not
+ * carry: `total_details.breakdown` is an expandable field, so the delivered
+ * object states `amount_tax` and nothing about the base it was applied to.
+ *
+ * Returns the expanded session, or null when the read cannot be made. Null is
+ * not a failure that stops the recording — the row is written from the
+ * delivered object with `taxLines: []`, and a taxed row with no stated base is
+ * COUNTED in the return's `attention` rather than dropped or zeroed.
+ */ async function expandedSession(sessionId) {
+    const key = stripeKey();
+    if (!key || !sessionId) return null;
+    try {
+        const response = await fetch(`https://api.stripe.com/v1/checkout/sessions/${encodeURIComponent(sessionId)}?expand[]=total_details.breakdown`, {
+            headers: {
+                Authorization: `Bearer ${key}`
+            }
+        });
+        if (!response.ok) return null;
+        const body = await response.json().catch(()=>null);
+        return (body == null ? void 0 : body.id) ? body : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/** The host this Stripe object belongs to, from whichever metadata bag. */ function hostIdOf(object) {
+    var _ref, _ref1, _ref2;
+    var _object_metadata, _object_subscription_details_metadata, _object_subscription_details, _object_parent_subscription_details_metadata, _object_parent_subscription_details, _object_parent;
+    return String((_ref = (_ref1 = (_ref2 = object == null ? void 0 : (_object_metadata = object.metadata) == null ? void 0 : _object_metadata.hostId) != null ? _ref2 : object == null ? void 0 : (_object_subscription_details = object.subscription_details) == null ? void 0 : (_object_subscription_details_metadata = _object_subscription_details.metadata) == null ? void 0 : _object_subscription_details_metadata.hostId) != null ? _ref1 : object == null ? void 0 : (_object_parent = object.parent) == null ? void 0 : (_object_parent_subscription_details = _object_parent.subscription_details) == null ? void 0 : (_object_parent_subscription_details_metadata = _object_parent_subscription_details.metadata) == null ? void 0 : _object_parent_subscription_details_metadata.hostId) != null ? _ref : '');
+}
+function metadataTypeOf(object) {
+    var _ref, _ref1, _ref2;
+    var _object_metadata, _object_subscription_details_metadata, _object_subscription_details, _object_parent_subscription_details_metadata, _object_parent_subscription_details, _object_parent;
+    return String((_ref = (_ref1 = (_ref2 = object == null ? void 0 : (_object_metadata = object.metadata) == null ? void 0 : _object_metadata.type) != null ? _ref2 : object == null ? void 0 : (_object_subscription_details = object.subscription_details) == null ? void 0 : (_object_subscription_details_metadata = _object_subscription_details.metadata) == null ? void 0 : _object_subscription_details_metadata.type) != null ? _ref1 : object == null ? void 0 : (_object_parent = object.parent) == null ? void 0 : (_object_parent_subscription_details = _object_parent.subscription_details) == null ? void 0 : (_object_parent_subscription_details_metadata = _object_parent_subscription_details.metadata) == null ? void 0 : _object_parent_subscription_details_metadata.type) != null ? _ref : '');
+}
+/**
+ * Records one storefront sale's tax, or does nothing when this event is not
+ * one. Returns the row written, for the specs — never for control flow.
+ */ export async function recordStorefrontTax(type, object) {
+    try {
+        var _ref, _ref1;
+        var _this;
+        const metadataType = metadataTypeOf(object);
+        const hostId = hostIdOf(object);
+        if (!hostId) return null;
+        let kind;
+        let taxSource = object;
+        let manualTaxCents = 0;
+        if (type === 'checkout.session.completed' && SESSION_TYPES.has(metadataType) && (object == null ? void 0 : object.payment_status) === 'paid') {
+            var _ref2, _ref3;
+            var _object_metadata, _object_total_details, _object_automatic_tax;
+            kind = 'session';
+            // The manual tax rides as an ordinary `line_items[1]` Stripe is never
+            // told is tax (AGL-1711), so the session's own metadata snapshot is the
+            // only witness to it. A cart session carries no such line at all.
+            manualTaxCents = Math.max(0, Number((_ref2 = object == null ? void 0 : (_object_metadata = object.metadata) == null ? void 0 : _object_metadata.taxCents) != null ? _ref2 : 0)) || 0;
+            // Expanded whenever Stripe COMPUTED tax on this session — which since
+            // AGL-1953 includes a `manual`-mode cart or draft order, where the tax
+            // rides a real Tax Rate and Stripe therefore states a `taxable_amount`
+            // for it. Gated on the delivered `amount_tax` rather than done
+            // unconditionally so the buy-now and POS constructions, which report 0
+            // there and answer from metadata, still cost no extra Stripe read.
+            const stripeStatedTax = Number((_ref3 = object == null ? void 0 : (_object_total_details = object.total_details) == null ? void 0 : _object_total_details.amount_tax) != null ? _ref3 : 0);
+            if ((object == null ? void 0 : (_object_automatic_tax = object.automatic_tax) == null ? void 0 : _object_automatic_tax.enabled) === true || Number.isFinite(stripeStatedTax) && stripeStatedTax > 0) {
+                var _ref4, _ref5;
+                taxSource = (_ref4 = await expandedSession(String((_ref5 = object == null ? void 0 : object.id) != null ? _ref5 : ''))) != null ? _ref4 : object;
+            }
+        } else if ((type === 'invoice.paid' || type === 'invoice.payment_succeeded') && metadataType === 'commerce-subscription') {
+            // Every cycle including the opening one. The subscription's own
+            // `checkout.session.completed` is NOT a second source — recording both
+            // would count the opening sale twice (AGL-1811's rule, same reason).
+            kind = 'invoice';
+        } else {
+            return null;
+        }
+        const row = storefrontTaxRow(taxSource, {
+            kind,
+            hostId,
+            manualTaxCents
+        });
+        if (!row) return null;
+        // Nothing to file and nothing to explain: no tax computed, no tax charged.
+        // A `stripe-automatic` row is kept even at zero tax — that a Stripe Tax
+        // sale answered "not collecting" is itself the audit answer to why a
+        // jurisdiction is absent from the return.
+        //
+        // EXCEPT where the absence is AGLYN'S decision rather than the merchant's
+        // (AGL-2000). A zero-tax commerce sale means the merchant configured no
+        // tax — their call, their liability, nothing here to explain. A booking or
+        // a reservation is untaxed because THIS CODEBASE decided not to compute a
+        // goods rate on a service or a room (`bookings/server.ts`, `reserve.ts`),
+        // and that is exactly the kind of absence somebody has to be able to find
+        // later: it is the platform answering a tax question on a merchant's
+        // revenue. Dropping those rows made the decision invisible in the one
+        // place anyone would go looking for it.
+        if (row.taxMode === 'none' && !PLATFORM_UNTAXED_TYPES.has(metadataType)) {
+            return null;
+        }
+        const documentId = String((_ref = object == null ? void 0 : object.id) != null ? _ref : '');
+        if (!documentId) return null;
+        const orgId = (_ref1 = (_this = await getOrgForHost(hostId).catch(()=>null)) == null ? void 0 : _this.orgId) != null ? _ref1 : null;
+        await firebaseAdmin.app().firestore().collection('storefrontTaxCollected').doc(documentId).set(_extends({}, row, {
+            orgId,
+            recordedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp()
+        }), // Keyed by the Stripe object id and merged, so a redelivery — and the
+        // `invoice.paid` / `invoice.payment_succeeded` pair Stripe sends for
+        // ONE payment — restamps a single document instead of duplicating a
+        // taxable sale.
+        {
+            merge: true
+        });
+        return row;
+    } catch (error) {
+        console.error('[AGL-1904] storefront tax recording failed', error);
+        return null;
+    }
+}
+
+//# sourceMappingURL=storefront-tax-record.js.map

package/src/lib/server/storefront-tax-record.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/storefront-tax-record.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 { firebaseAdmin, getOrgForHost } from '@aglyn/tenant-data-admin'\nimport { storefrontTaxRow, type StorefrontTaxRow } from './storefront-tax'\n\n/**\n * Writes `storefrontTaxCollected/{stripeId}` for every storefront sale that\n * carried tax (AGL-1904) — the row that makes tax collected under Aglyn's\n * registration visible to Aglyn's own quarterly return.\n *\n * ## The hole this closes\n *\n * AGL-1811 records one `platformRevenue` row per paid invoice and the Texas\n * return is their sum. That collection is deliberately scoped to AGLYN's own\n * charges: the console webhook only writes a row when the invoice's customer\n * resolves through the `stripeCustomers` index, which `writeOrgBilling` stamps\n * for Aglyn's billing customers and nothing else stamps. A storefront\n * shopper's customer is never in it.\n *\n * That scoping is correct for what it was built for and it left a gap: a\n * `mode: 'stripe'` storefront sale charges the shopper tax computed on\n * AGLYN's registrations (measured — see `storefront-tax.ts`), settles it into\n * Aglyn's platform balance, and NOTHING recorded it anywhere Aglyn's return\n * could see. The merchant's order document carries a `totals.taxCents`, but\n * that is the merchant's books, per host, and no return sums it.\n *\n * ## Why a SEPARATE collection rather than more `platformRevenue` rows\n *\n * Structural, and the reason must survive a future tidy-up: a\n * `platformRevenue` row's `netCents` is Aglyn's revenue, and a storefront\n * row's is mostly the MERCHANT's — it transfers straight out to the connected\n * account. Merging the two would make the return's \"total sales\" figure silently\n * include other companies' receipts. Keeping them in different collections\n * means no query, sum or future refactor can accidentally add them together;\n * the return reports the storefront figures as their own section, and what\n * belongs on which line of a filed return stays a question for the preparer\n * and for counsel rather than one this code answers.\n *\n * ## What is recorded, and what is not\n *\n * Recorded: cart, buy-now, reservation and draft-order sessions, plus every\n * storefront subscription INVOICE (opening cycle and renewals both — the\n * subscription's own `checkout.session.completed` is deliberately skipped so\n * the opening cycle is not counted twice, the same rule AGL-1811 applies).\n *\n * Manual-mode sales are recorded too, with `taxMode: 'manual'`, precisely so\n * the two modes can be told apart at read time instead of being invisible.\n * They are NOT Aglyn-collected and the return never sums them into the\n * Aglyn-liable figure.\n *\n * **Refunds are not yet reflected.** A refunded storefront sale keeps its full\n * tax on this record, so the Aglyn-liable figure is an OVER-statement of what\n * is owed rather than an under-statement. That direction is deliberate:\n * over-stating what is held for the state is correctable at filing time,\n * under-stating it is a shortfall discovered by an auditor. Stated here rather\n * than left to be discovered.\n *\n * Never throws. A recording failure logs and returns — a throw here propagates\n * through `runBillingWebhookHandlers` into a 500 that Stripe redelivers\n * forever, which is the AGL-1743 lesson.\n */\n\n/** The commerce session types that settle money on the platform account. */\nconst SESSION_TYPES = new Set([\n  'commerce-cart',\n  'commerce-order',\n  'commerce-reservation',\n  'commerce-draft',\n  // A paid service booking (AGL-2000). It carries no tax by a stated\n  // decision (`bookings/server.ts`), but it is a storefront sale and it was\n  // absent from this set entirely — so it was not merely untaxed, it did not\n  // appear in the record that would let anyone NOTICE it was untaxed or\n  // reconcile it later. An untaxed sale that is recorded reads\n  // `taxMode: 'none'`; an unrecorded one reads as nothing at all.\n  'booking-payment',\n])\n\n/**\n * Session types whose zero tax is a decision taken HERE, not by the merchant\n * (AGL-2000). Their rows are filed even at `taxMode: 'none'`, so an untaxed\n * service or stay is reconcilable instead of merely missing. See the note at\n * the `taxMode === 'none'` gate below.\n */\nconst PLATFORM_UNTAXED_TYPES = new Set(['booking-payment', 'commerce-reservation'])\n\nfunction stripeKey(): string {\n  return String(process.env.STRIPE_SECRET_KEY ?? '')\n}\n\n/**\n * A Checkout Session's tax BREAKDOWN, which the webhook payload does not\n * carry: `total_details.breakdown` is an expandable field, so the delivered\n * object states `amount_tax` and nothing about the base it was applied to.\n *\n * Returns the expanded session, or null when the read cannot be made. Null is\n * not a failure that stops the recording — the row is written from the\n * delivered object with `taxLines: []`, and a taxed row with no stated base is\n * COUNTED in the return's `attention` rather than dropped or zeroed.\n */\nasync function expandedSession(sessionId: string): Promise<any | null> {\n  const key = stripeKey()\n  if (!key || !sessionId) return null\n  try {\n    const response = await fetch(\n      `https://api.stripe.com/v1/checkout/sessions/${encodeURIComponent(\n        sessionId,\n      )}?expand[]=total_details.breakdown`,\n      { headers: { Authorization: `Bearer ${key}` } },\n    )\n    if (!response.ok) return null\n    const body = await response.json().catch(() => null)\n    return body?.id ? body : null\n  } catch {\n    return null\n  }\n}\n\n/** The host this Stripe object belongs to, from whichever metadata bag. */\nfunction hostIdOf(object: any): string {\n  return String(\n    object?.metadata?.hostId ??\n      object?.subscription_details?.metadata?.hostId ??\n      object?.parent?.subscription_details?.metadata?.hostId ??\n      '',\n  )\n}\n\nfunction metadataTypeOf(object: any): string {\n  return String(\n    object?.metadata?.type ??\n      object?.subscription_details?.metadata?.type ??\n      object?.parent?.subscription_details?.metadata?.type ??\n      '',\n  )\n}\n\n/**\n * Records one storefront sale's tax, or does nothing when this event is not\n * one. Returns the row written, for the specs — never for control flow.\n */\nexport async function recordStorefrontTax(\n  type: string,\n  object: any,\n): Promise<StorefrontTaxRow | null> {\n  try {\n    const metadataType = metadataTypeOf(object)\n    const hostId = hostIdOf(object)\n    if (!hostId) return null\n\n    let kind: 'session' | 'invoice'\n    let taxSource = object\n    let manualTaxCents = 0\n    if (\n      type === 'checkout.session.completed' &&\n      SESSION_TYPES.has(metadataType) &&\n      object?.payment_status === 'paid'\n    ) {\n      kind = 'session'\n      // The manual tax rides as an ordinary `line_items[1]` Stripe is never\n      // told is tax (AGL-1711), so the session's own metadata snapshot is the\n      // only witness to it. A cart session carries no such line at all.\n      manualTaxCents = Math.max(0, Number(object?.metadata?.taxCents ?? 0)) || 0\n      // Expanded whenever Stripe COMPUTED tax on this session — which since\n      // AGL-1953 includes a `manual`-mode cart or draft order, where the tax\n      // rides a real Tax Rate and Stripe therefore states a `taxable_amount`\n      // for it. Gated on the delivered `amount_tax` rather than done\n      // unconditionally so the buy-now and POS constructions, which report 0\n      // there and answer from metadata, still cost no extra Stripe read.\n      const stripeStatedTax = Number(\n        object?.total_details?.amount_tax ?? 0,\n      )\n      if (\n        object?.automatic_tax?.enabled === true ||\n        (Number.isFinite(stripeStatedTax) && stripeStatedTax > 0)\n      ) {\n        taxSource = (await expandedSession(String(object?.id ?? ''))) ?? object\n      }\n    } else if (\n      (type === 'invoice.paid' || type === 'invoice.payment_succeeded') &&\n      metadataType === 'commerce-subscription'\n    ) {\n      // Every cycle including the opening one. The subscription's own\n      // `checkout.session.completed` is NOT a second source — recording both\n      // would count the opening sale twice (AGL-1811's rule, same reason).\n      kind = 'invoice'\n    } else {\n      return null\n    }\n\n    const row = storefrontTaxRow(taxSource, { kind, hostId, manualTaxCents })\n    if (!row) return null\n    // Nothing to file and nothing to explain: no tax computed, no tax charged.\n    // A `stripe-automatic` row is kept even at zero tax — that a Stripe Tax\n    // sale answered \"not collecting\" is itself the audit answer to why a\n    // jurisdiction is absent from the return.\n    //\n    // EXCEPT where the absence is AGLYN'S decision rather than the merchant's\n    // (AGL-2000). A zero-tax commerce sale means the merchant configured no\n    // tax — their call, their liability, nothing here to explain. A booking or\n    // a reservation is untaxed because THIS CODEBASE decided not to compute a\n    // goods rate on a service or a room (`bookings/server.ts`, `reserve.ts`),\n    // and that is exactly the kind of absence somebody has to be able to find\n    // later: it is the platform answering a tax question on a merchant's\n    // revenue. Dropping those rows made the decision invisible in the one\n    // place anyone would go looking for it.\n    if (row.taxMode === 'none' && !PLATFORM_UNTAXED_TYPES.has(metadataType)) {\n      return null\n    }\n\n    const documentId = String(object?.id ?? '')\n    if (!documentId) return null\n    const orgId = (await getOrgForHost(hostId).catch(() => null))?.orgId ?? null\n    await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('storefrontTaxCollected')\n      .doc(documentId)\n      .set(\n        {\n          ...row,\n          orgId,\n          recordedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp(),\n        },\n        // Keyed by the Stripe object id and merged, so a redelivery — and the\n        // `invoice.paid` / `invoice.payment_succeeded` pair Stripe sends for\n        // ONE payment — restamps a single document instead of duplicating a\n        // taxable sale.\n        { merge: true },\n      )\n    return row\n  } catch (error) {\n    console.error('[AGL-1904] storefront tax recording failed', error)\n    return null\n  }\n}\n"],"names":["firebaseAdmin","getOrgForHost","storefrontTaxRow","SESSION_TYPES","Set","PLATFORM_UNTAXED_TYPES","stripeKey","process","String","env","STRIPE_SECRET_KEY","expandedSession","sessionId","key","response","fetch","encodeURIComponent","headers","Authorization","ok","body","json","catch","id","hostIdOf","object","metadata","hostId","subscription_details","parent","metadataTypeOf","type","recordStorefrontTax","metadataType","kind","taxSource","manualTaxCents","has","payment_status","Math","max","Number","taxCents","stripeStatedTax","total_details","amount_tax","automatic_tax","enabled","isFinite","row","taxMode","documentId","orgId","app","firestore","collection","doc","set","recordedAt","FieldValue","serverTimestamp","merge","error","console"],"mappings":"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"}

package/src/lib/server/storefront-tax.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @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.
+ */
+/**
+ * What a storefront sale's TAX decomposes to (AGL-1904) — the record that
+ * makes tax collected on a merchant's sale visible to Aglyn's own return.
+ *
+ * ## The observation this module exists to record
+ *
+ * Every storefront checkout — cart, buy-now, subscription — creates its
+ * Checkout Session on the PLATFORM account: platform secret key, no
+ * `Stripe-Account` header, no `on_behalf_of`, with
+ * `payment_intent_data[transfer_data][destination]` pointing at the merchant's
+ * connected account. `cart-checkout.ts` and `checkout.ts` then set
+ * `automatic_tax[enabled]` when the store's tax mode is `stripe`.
+ *
+ * That was long suspected to mean Stripe Tax computes the shopper's tax
+ * against AGLYN's registrations rather than the merchant's. It was MEASURED on
+ * 2026-08-18, in test mode, as a two-arm experiment on exactly that session
+ * shape (a $100 line, a Texas shopper address, `transfer_data[destination]`
+ * set):
+ *
+ *   - **Platform unregistered, destination connected account registered in
+ *     TX** → `amount_tax: 0`, one breakdown line with
+ *     `taxability_reason: "not_collecting"`, `taxable_amount: 0`.
+ *   - **Platform registered in TX, everything else byte-identical** →
+ *     `amount_tax: 825`, `taxability_reason: "standard_rated"`,
+ *     `taxable_amount: 10000`, rate 8.25% "Texas".
+ *
+ * Both sessions reported `automatic_tax.liability: { type: "self" }` — Stripe's
+ * own word for "the account this session was created on is the one liable".
+ * `transfer_data[destination]` had no effect on tax in either arm.
+ *
+ * So on a `mode: 'stripe'` store the tax charged to the shopper is computed on
+ * Aglyn's registration footprint, lands in Aglyn's platform balance, and is
+ * Aglyn's to remit. The live platform account has held an ACTIVE Texas state
+ * sales tax registration since 2026-08-17, so this is not hypothetical.
+ *
+ * **This module describes that mechanism and records the money.** Aglyn IS a
+ * marketplace facilitator for storefront sales, and the published Terms say so
+ * at §10.7 (AGL-1956). Facilitator status still attaches by operation of
+ * law rather than by our say-so, and §10.7 is deliberately narrow — Aglyn
+ * collects and remits **where applicable law gives it an obligation**, not
+ * universally — so this module still records the mechanism per sale and does
+ * not stamp a per-merchant or per-jurisdiction verdict on any row.
+ *
+ * ## The two store modes are DIFFERENT FACTS and must never be summed
+ *
+ * `taxMode` is the whole point of this record, and it is derived from
+ * `automatic_tax.enabled` — **never** from whether tax lines are present:
+ *
+ *   - **`stripe-automatic`** — Stripe Tax computed it, against whichever
+ *     account `automatic_tax.liability` names. When that is `platform`, the
+ *     money is held under Aglyn's registration.
+ *   - **`manual`** — the merchant's own configured rate
+ *     (`checkout.ts` / `pos-order.ts`), applied to the merchant's own declared
+ *     origin. Aglyn's registrations never enter into it and the amount is not
+ *     Aglyn's to remit.
+ *
+ * The trap that makes the `automatic_tax.enabled` discriminator load-bearing:
+ * a MANUAL-mode subscription renewal carries a real Stripe Tax Rate (AGL-1751
+ * attaches one so the tax recurs), so its invoice arrives with a populated
+ * `total_taxes[]` — indistinguishable from a Stripe Tax invoice if you look at
+ * the tax lines. Summing tax lines would silently book merchant-configured tax
+ * as Aglyn-collected. **Read the flag, not the lines.**
+ *
+ * ## The taxable base is kept, never inferred
+ *
+ * `taxable_amount` is what a return reports as "taxable sales". Deriving it as
+ * `amount ÷ rate` needs a live read to resolve the rate id and rounds wrong at
+ * the edges, so it is stored when Stripe states it and left `null` when it
+ * does not — and a row whose base cannot be read is COUNTED OUT LOUD by the
+ * return rather than treated as a zero-base sale.
+ *
+ * A Checkout Session's `total_details.breakdown` is not in the webhook payload
+ * and must be re-read with `expand[]=total_details.breakdown`; an invoice
+ * carries `total_taxes[]` inline. Both land in the same `taxLines` shape.
+ *
+ * Pure and total: unreadable input answers `null`, never throws — a recording
+ * failure must never 500 a webhook into redelivery.
+ */
+import { type StorefrontTaxMode } from '../model/commerce-tax-decision';
+/**
+ * Which machinery produced the tax on this sale. See the module note.
+ *
+ * The union and its derivation live in the MODEL since AGL-2451, because the
+ * merchant's order document now carries the same fact (`HostOrder.taxMode`)
+ * and two copies of a rule that must agree are one copy too many. Re-exported
+ * here so this module stays the place the mechanism is documented.
+ */
+export type { StorefrontTaxMode };
+/**
+ * Whose registrations Stripe Tax computed against, from
+ * `automatic_tax.liability.type`: `self` (the account the object lives on,
+ * i.e. Aglyn's platform) or `account` (a named connected account).
+ * Null whenever `taxMode` is not `stripe-automatic`.
+ */
+export type StorefrontTaxLiability = 'platform' | 'connected-account';
+/** One entry of the stored tax breakdown. */
+export interface StorefrontTaxLine {
+    amountCents: number;
+    /** Stripe's stated reason, e.g. `standard_rated`, `not_collecting`. */
+    taxabilityReason: string | null;
+    taxRateId: string | null;
+    /** Stripe's `taxable_amount`; null when the shape did not carry it. */
+    taxableAmountCents: number | null;
+    /** e.g. `Texas` — from the expanded rate, for the working papers. */
+    jurisdiction: string | null;
+    /** The rate's own state code, which is not the shopper's address. */
+    rateState: string | null;
+    percentage: number | null;
+}
+/** The per-transaction record `storefrontTaxCollected/{stripeId}` stores. */
+export interface StorefrontTaxRow {
+    /** `session` for one-time sales, `invoice` for subscription cycles. */
+    kind: 'session' | 'invoice';
+    hostId: string;
+    /** The commerce path — `commerce-cart`, `commerce-order`, … */
+    metadataType: string | null;
+    taxMode: StorefrontTaxMode;
+    taxLiability: StorefrontTaxLiability | null;
+    /** The merchant's connected account, when the object names one. */
+    connectedAccountId: string | null;
+    /** What the shopper actually paid, tax included. */
+    grossCents: number;
+    taxCents: number;
+    /** Gross minus tax. NOT Aglyn's revenue — most of it is the merchant's. */
+    netCents: number;
+    currency: string;
+    /** The jurisdiction input — the shopper's address on the Stripe object. */
+    customerAddress: {
+        country: string | null;
+        state: string | null;
+        city: string | null;
+        postalCode: string | null;
+    } | null;
+    taxLines: StorefrontTaxLine[];
+    paidAt: Date | null;
+}
+export interface StorefrontTaxContext {
+    kind: 'session' | 'invoice';
+    hostId: string;
+    /**
+     * The manual-mode tax `checkout.ts` puts over as an ordinary line item.
+     * Stripe is never told it is tax, so no Stripe field carries it and the
+     * session's own `metadata[taxCents]` is the only witness (AGL-1711).
+     */
+    manualTaxCents?: number;
+}
+/** What one Stripe object says about the tax it carried. */
+export interface ResolvedStorefrontTax {
+    /** `automatic_tax.enabled` — the discriminator, never the tax lines. */
+    automatic: boolean;
+    /** Stripe's own breakdown, present only on a `stripe-automatic` sale. */
+    lines: StorefrontTaxLine[];
+    taxCents: number;
+    taxMode: StorefrontTaxMode;
+}
+/**
+ * Reads the tax off one paid session or invoice — the SINGLE derivation, and
+ * the reason it is its own exported function (AGL-2451).
+ *
+ * `storefrontTaxRow` builds the `storefrontTaxCollected` record from it, and
+ * the four order-writing doors in `billing-webhook.ts` stamp `HostOrder.taxMode`
+ * from it, so an order and the row filed for the same Stripe id cannot state
+ * different regimes. Re-deriving the mode beside a second reading of the same
+ * object is exactly how the two would drift.
+ *
+ * Pure and total: unreadable input answers `taxMode: 'none'`, never throws.
+ */
+export declare function resolveStorefrontTax(object: unknown, manualTaxCents?: number): ResolvedStorefrontTax;
+/**
+ * Just the regime, for the order-writing doors (AGL-2451). Delegates, so this
+ * is the same answer the filed tax record gives for the same object.
+ */
+export declare function storefrontTaxModeOf(object: unknown, manualTaxCents?: number): StorefrontTaxMode;
+/**
+ * Decomposes a paid storefront session or invoice into the stored row, or
+ * `null` when there is no host to attribute it to.
+ *
+ * The caller decides WHICH objects reach this — the commerce webhook
+ * self-selects on `metadata.type`, exactly as every other section does.
+ */
+export declare function storefrontTaxRow(object: unknown, context: StorefrontTaxContext): StorefrontTaxRow | null;