@aglyn/plugins-commerce 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/server/revenue-source.js

@@ -0,0 +1,286 @@
+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.
+ */ /**
+ * The storefront's take on the operator's revenue report (AGL-2486, AGL-3080).
+ *
+ * Answered through the platform's revenue source contract
+ * (`@aglyn/aglyn/plugin-manager/plugin-revenue-sources`). The report folds the
+ * operator's own invoices; this is what storefront orders earned it — and the
+ * one figure on that page most likely to be reported wrongly.
+ *
+ * An order's `feeCents` is the Connect `application_fee_amount`, which since
+ * AGL-2152 is the advertised take PLUS Stripe's processing cost:
+ *
+ *     fee = take%(goods) + processing%(charge) + 30¢
+ *
+ * Every storefront charge is a DESTINATION charge, so Stripe moves the whole
+ * amount to the merchant and debits its processing fee from the PLATFORM's
+ * balance; the pass-through half of that fee exists purely to recover a cost
+ * the platform has already paid. Reporting `feeCents` as earnings would
+ * overstate the margin on every single storefront sale — and on a small order
+ * it would report the 30¢ Stripe just took as money the platform made.
+ *
+ * So the pass-through is recomputed with the SAME helper the fee was charged
+ * from (`storefrontProcessingCostCents`) and subtracted. Both halves are
+ * reported, because "we collected X of which Y was Stripe's" is the sentence a
+ * margin figure needs.
+ *
+ * The recomputation is an estimate in one direction only: it re-derives the
+ * cost from the stored charge amount rather than reading Stripe's actual
+ * balance-transaction fee, and it prices it at the DEAREST enabled payment
+ * method's rate (BNPL, 6%) because that is the rate the fee was charged at.
+ * A card-family order really costs 2.9%, so on those orders this subtracts
+ * more than Stripe took and the take is UNDERSTATED — the safe direction, and
+ * stated on the page rather than left to be discovered.
+ *
+ * ## Subscription cycles, and the one cycle this understates
+ *
+ * A storefront SUBSCRIPTION cycle carries a `subscriptionId`. Since AGL-2655
+ * its fee carries the same pass-through, folded into
+ * `application_fee_percent` as a rate because a Stripe subscription cannot
+ * express a fixed 30¢ — so it is netted out here exactly as a one-time sale's
+ * is. The percent is sized on the recurring goods and the recomputed cost here
+ * is sized on the whole amount paid, tax included, so a taxed cycle subtracts
+ * slightly more than was recovered: understated, the safe direction.
+ *
+ * A subscription sold before the pass-through existed is carried onto it by
+ * the renewal re-price (AGL-2289) at its next paid invoice — but THAT invoice
+ * was billed at the bare take, so its row's `feeCents` holds no pass-through
+ * and the clamp reports its take as zero. One cycle per legacy subscription,
+ * and the count beside the figure is how a reader sees how much of the book
+ * that is.
+ */ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { storefrontProcessingCostCents } from "@aglyn/aglyn/server";
+import { PLATFORM_BRAND_NAME } from "@aglyn/aglyn/app-utils/platform-brand";
+import { stripeIdIsTestMode } from "@aglyn/aglyn/app-utils/stripe-deployment-mode";
+import { groupRevenueAttribution } from "@aglyn/aglyn/plugin-manager/plugin-revenue-sources";
+/** Cents from anything, defaulting to 0 rather than NaN. */ function cents(value) {
+    const parsed = Number(value != null ? value : 0);
+    return Number.isFinite(parsed) ? Math.round(parsed) : 0;
+}
+/**
+ * Whether this order row was a test-mode rehearsal.
+ *
+ * A recorded `livemode` wins, and the session id's prefix is the fallback for
+ * rows written before anything recorded it. An order with neither signal is
+ * LIVE: a POS cash sale carries no Stripe session at all, and answering "test"
+ * for anything unidentifiable would erase genuine revenue from the report.
+ */ function isTestModeOrderRow(row) {
+    var _row_checkoutSessionId;
+    if (typeof row.livemode === 'boolean') return !row.livemode;
+    return stripeIdIsTestMode((_row_checkoutSessionId = row.checkoutSessionId) != null ? _row_checkoutSessionId : row.id);
+}
+export function commerceSettledSummary(rows, truncated = false) {
+    const out = {
+        transactionCount: 0,
+        grossCents: 0,
+        applicationFeeCents: 0,
+        processingPassThroughCents: 0,
+        commissionCents: 0,
+        commissionRefundedCents: 0,
+        commissionNetCents: 0,
+        subscriptionOrders: 0,
+        truncated: truncated === true
+    };
+    for (const row of rows != null ? rows : []){
+        // A REHEARSAL IS NOT REVENUE. A smoke-test checkout writes a real order
+        // document — Stripe never moved money for it, and its session id says so.
+        // Skipped ENTIRELY rather than counted at zero, because `transactionCount`
+        // is read as "how many sales", and a rehearsal is not one.
+        if (isTestModeOrderRow(row)) continue;
+        const split = commerceOrderTake(row);
+        out.transactionCount += 1;
+        out.grossCents += split.gross;
+        out.applicationFeeCents += split.fee;
+        if (split.isSubscriptionOrder) out.subscriptionOrders += 1;
+        out.processingPassThroughCents += split.passThrough;
+        out.commissionCents += split.take;
+        out.commissionRefundedCents += split.takeRefunded;
+        out.commissionNetCents += split.takeNet;
+    }
+    return out;
+}
+/**
+ * One storefront order's take, in ONE place.
+ *
+ * Shared with the per-host attribution so a host table cannot sum to
+ * something other than the storefront line above it.
+ *
+ * A zero-fee order contributes its gross and its count and nothing else —
+ * there is no take to attribute, and inventing one from the gross would
+ * report a merchant's money as the platform's.
+ */ export function commerceOrderTake(row) {
+    const gross = cents(row == null ? void 0 : row.amountCents);
+    const fee = Math.max(0, cents(row == null ? void 0 : row.feeCents));
+    const isSubscriptionOrder = typeof (row == null ? void 0 : row.subscriptionId) === 'string' && row.subscriptionId.length > 0;
+    if (fee <= 0) {
+        return {
+            gross,
+            fee,
+            isSubscriptionOrder,
+            passThrough: 0,
+            take: 0,
+            takeRefunded: 0,
+            takeNet: 0
+        };
+    }
+    // Every fee bundles the recovery — a one-time sale's in cents, a
+    // subscription cycle's as a rate (AGL-2655). Clamped to the fee itself: the
+    // recomputed cost can exceed a fee charged under an older rate, and a
+    // negative take would subtract from another order's real margin.
+    const passThrough = Math.min(fee, storefrontProcessingCostCents(gross));
+    const take = fee - passThrough;
+    const refunded = Math.min(gross, Math.max(0, cents(row == null ? void 0 : row.refundedCents)));
+    const takeRefunded = gross > 0 ? Math.round(refunded * take / gross) : 0;
+    return {
+        gross,
+        fee,
+        isSubscriptionOrder,
+        passThrough,
+        take,
+        takeRefunded,
+        takeNet: take - takeRefunded
+    };
+}
+/**
+ * Storefront take by HOST.
+ *
+ * By host and not by org on purpose: one org can run several storefronts, and
+ * "which store earns" is the question a per-org roll-up destroys.
+ */ export function commerceHostAttribution(rows, limit = 100) {
+    return groupRevenueAttribution((rows != null ? rows : []).map((row)=>{
+        var _ref;
+        const split = commerceOrderTake(row);
+        return {
+            key: String((_ref = row == null ? void 0 : row.hostId) != null ? _ref : ''),
+            detail: '',
+            gain: split.takeNet,
+            loss: split.takeRefunded
+        };
+    }), limit, 'Host not recorded');
+}
+/**
+ * The storefront's answer for one period, from figures already folded. Pure,
+ * so what the report prints can be proved from fixtures.
+ *
+ * `failed` is a sweep that could not run — a collection-group index this
+ * deployment has not built answers FAILED_PRECONDITION — and it is reported as
+ * a failure with figures of zero, never as a cap: "we read part of it" and "we
+ * read none of it" have different remedies.
+ */ export function commerceRevenueAnswer(read) {
+    var _settled_commissionNetCents, _settled_subscriptionOrders;
+    const brand = PLATFORM_BRAND_NAME;
+    const { settled } = read;
+    return {
+        id: 'commerce',
+        name: 'storefront orders',
+        earned: {
+            label: 'Storefront commission',
+            cents: Number((_settled_commissionNetCents = settled.commissionNetCents) != null ? _settled_commissionNetCents : 0),
+            note: 'The advertised take on merchant storefront sales, net of refunds — ' + 'with Stripe’s card processing removed. The platform fee charged on a ' + 'storefront sale bundles that processing cost and passes it through at ' + 'cost; it is a recovery, not earnings.'
+        },
+        grossToNet: [
+            {
+                label: 'Storefront sales (shopper gross)',
+                cents: settled.grossCents,
+                deduction: false,
+                note: 'The merchant’s. It transfers straight to their connected account ' + 'and is shown only for scale.'
+            },
+            {
+                label: 'Storefront platform fee collected',
+                cents: settled.applicationFeeCents,
+                deduction: false,
+                note: `Not all ${brand}’s — see the next line.`
+            },
+            {
+                label: '— less card processing passed through at cost',
+                cents: settled.processingPassThroughCents,
+                deduction: true,
+                note: `Stripe’s. On a destination charge Stripe debits ${brand}’s balance for processing, and this half of the fee recovers exactly that. It is a recovery, not earnings, and reporting it as revenue would overstate every storefront sale.`
+            }
+        ],
+        notes: Number((_settled_subscriptionOrders = settled.subscriptionOrders) != null ? _settled_subscriptionOrders : 0) > 0 ? [
+            {
+                label: `${settled.subscriptionOrders} storefront subscription cycles — one billed before its re-price reports no take`,
+                tone: 'warning'
+            }
+        ] : [],
+        attribution: [
+            _extends({
+                id: 'byHost',
+                heading: 'Storefront take by host',
+                unit: 'Storefront',
+                countLabel: 'Orders',
+                empty: `No storefront order settled in this period. Note this is ${brand}'s take only — the shopper's spend is the merchant's money and is never counted here.`,
+                chartEmpty: 'No storefront earned a take in this period — nothing to plot yet.'
+            }, read.byHost)
+        ],
+        attributionNote: "Storefront figures above are the advertised take with Stripe's " + 'processing cost already subtracted, on the basis stated in “Gross ' + 'versus net” below. Attribution is by host rather than by org because ' + 'one org can run several storefronts, and rolling them up destroys the ' + 'question.',
+        truncated: settled.truncated,
+        failure: read.failed ? {
+            title: 'Storefront orders could not be read',
+            detail: 'The storefront commission below reads $0 because the query ' + 'failed, not because there were no sales. The sweep needs the ' + 'COLLECTION_GROUP index on orders.createdAtMs — check it is still ' + 'declared in the Firestore index config and actually deployed, ' + 'since indexes ship separately from the app.'
+        } : null,
+        summary: settled
+    };
+}
+/**
+ * The storefront's source, registered on the console's API surface: the
+ * staff revenue report awaits that surface before it asks.
+ */ export const commerceRevenueSource = {
+    async read (request) {
+        var _ref;
+        const firestore = firebaseAdmin.app().firestore();
+        // Storefront orders live per host (`hosts/{hostId}/orders`), so this is a
+        // collection-GROUP range — ranged on `createdAtMs`, the NUMBER, and not on
+        // the `createdAt` Timestamp beside it. A collection-group range needs a
+        // COLLECTION_GROUP-scoped single-field index — Firestore's automatic ones
+        // are COLLECTION scope only — and the index that is declared and deployed
+        // is on `createdAtMs` (AGL-1793). The `createdAt` form answers
+        // FAILED_PRECONDITION on every request, which is how the report once read
+        // $0 for every storefront.
+        let swept;
+        try {
+            swept = await request.sweep(firestore.collectionGroup('orders').where('createdAtMs', '>=', request.start.getTime()).where('createdAtMs', '<', request.end.getTime()), 'createdAtMs');
+        } catch (unused) {
+            swept = null;
+        }
+        const rows = ((_ref = swept == null ? void 0 : swept.docs) != null ? _ref : []).map((doc)=>{
+            var _ref;
+            var _doc_ref_parent_parent;
+            return _extends({
+                id: doc.id,
+                // The storefront that earned the take is in the PATH.
+                hostId: (_ref = (_doc_ref_parent_parent = doc.ref.parent.parent) == null ? void 0 : _doc_ref_parent_parent.id) != null ? _ref : ''
+            }, doc.data());
+        });
+        const settled = commerceSettledSummary(rows, (swept == null ? void 0 : swept.truncated) === true);
+        const byHost = commerceHostAttribution(rows, request.attributionLimit);
+        await request.nameRows(byHost.rows, {
+            collection: 'hosts',
+            nameField: 'displayName',
+            detailField: 'subdomain'
+        });
+        return commerceRevenueAnswer({
+            settled,
+            byHost,
+            failed: swept === null
+        });
+    }
+};
+
+//# sourceMappingURL=revenue-source.js.map

package/src/lib/server/revenue-source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/revenue-source.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The storefront's take on the operator's revenue report (AGL-2486, AGL-3080).\n *\n * Answered through the platform's revenue source contract\n * (`@aglyn/aglyn/plugin-manager/plugin-revenue-sources`). The report folds the\n * operator's own invoices; this is what storefront orders earned it — and the\n * one figure on that page most likely to be reported wrongly.\n *\n * An order's `feeCents` is the Connect `application_fee_amount`, which since\n * AGL-2152 is the advertised take PLUS Stripe's processing cost:\n *\n *     fee = take%(goods) + processing%(charge) + 30¢\n *\n * Every storefront charge is a DESTINATION charge, so Stripe moves the whole\n * amount to the merchant and debits its processing fee from the PLATFORM's\n * balance; the pass-through half of that fee exists purely to recover a cost\n * the platform has already paid. Reporting `feeCents` as earnings would\n * overstate the margin on every single storefront sale — and on a small order\n * it would report the 30¢ Stripe just took as money the platform made.\n *\n * So the pass-through is recomputed with the SAME helper the fee was charged\n * from (`storefrontProcessingCostCents`) and subtracted. Both halves are\n * reported, because \"we collected X of which Y was Stripe's\" is the sentence a\n * margin figure needs.\n *\n * The recomputation is an estimate in one direction only: it re-derives the\n * cost from the stored charge amount rather than reading Stripe's actual\n * balance-transaction fee, and it prices it at the DEAREST enabled payment\n * method's rate (BNPL, 6%) because that is the rate the fee was charged at.\n * A card-family order really costs 2.9%, so on those orders this subtracts\n * more than Stripe took and the take is UNDERSTATED — the safe direction, and\n * stated on the page rather than left to be discovered.\n *\n * ## Subscription cycles, and the one cycle this understates\n *\n * A storefront SUBSCRIPTION cycle carries a `subscriptionId`. Since AGL-2655\n * its fee carries the same pass-through, folded into\n * `application_fee_percent` as a rate because a Stripe subscription cannot\n * express a fixed 30¢ — so it is netted out here exactly as a one-time sale's\n * is. The percent is sized on the recurring goods and the recomputed cost here\n * is sized on the whole amount paid, tax included, so a taxed cycle subtracts\n * slightly more than was recovered: understated, the safe direction.\n *\n * A subscription sold before the pass-through existed is carried onto it by\n * the renewal re-price (AGL-2289) at its next paid invoice — but THAT invoice\n * was billed at the bare take, so its row's `feeCents` holds no pass-through\n * and the clamp reports its take as zero. One cycle per legacy subscription,\n * and the count beside the figure is how a reader sees how much of the book\n * that is.\n */\n\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { storefrontProcessingCostCents } from '@aglyn/aglyn/server'\nimport { PLATFORM_BRAND_NAME } from '@aglyn/aglyn/app-utils/platform-brand'\nimport { stripeIdIsTestMode } from '@aglyn/aglyn/app-utils/stripe-deployment-mode'\nimport {\n  groupRevenueAttribution,\n  type RevenueAttribution,\n  type RevenueSource,\n  type RevenueSourceAnswer,\n} from '@aglyn/aglyn/plugin-manager/plugin-revenue-sources'\n\n/** One `hosts/{hostId}/orders/{orderId}` row — a storefront sale. */\nexport interface CommerceOrderRowInput {\n  id: string\n  /** What the shopper paid, tax and shipping included. */\n  amountCents?: unknown\n  /**\n   * The Connect `application_fee_amount`: the platform's advertised take PLUS\n   * Stripe's processing cost passed through at cost (AGL-2152). NOT margin —\n   * see the module note.\n   */\n  feeCents?: unknown\n  /**\n   * Present ONLY on a storefront SUBSCRIPTION renewal, and it changes how\n   * `feeCents` must be read — see the module note.\n   */\n  subscriptionId?: unknown\n  /** Merchant refunds AND chargebacks both land here (`refund.ts`). */\n  refundedCents?: unknown\n  /**\n   * WHICH storefront the order belongs to — the attribution key.\n   *\n   * Orders live at `hosts/{hostId}/orders/{orderId}`, so this is lifted from\n   * the document PATH by the reader rather than read from a field. It costs no\n   * extra read and cannot disagree with where the document actually is.\n   */\n  hostId?: unknown\n  createdAt?: unknown\n  /**\n   * Whether Stripe moved real money, stamped from `event.livemode` by the\n   * webhook. Authoritative when present, and absent on every order written\n   * before that stamp shipped — which is why {@link isTestModeOrderRow} falls\n   * back to the id below rather than treating absence as an answer.\n   */\n  livemode?: unknown\n  /**\n   * The Checkout Session that produced the order. It carries its own mode\n   * (`cs_test_…`), which a subscription renewal's invoice id does not — so\n   * this is the fallback discriminator for rows predating `livemode`.\n   */\n  checkoutSessionId?: unknown\n}\n\nexport interface CommerceSettled {\n  transactionCount: number\n  /** Shopper spend across storefronts. Overwhelmingly the merchant's. */\n  grossCents: number\n  /** The whole `application_fee_amount` the platform collected. NOT margin. */\n  applicationFeeCents: number\n  /** Stripe's processing cost this recovered, at cost. Subtracted, never earnings. */\n  processingPassThroughCents: number\n  /** Application fee minus the pass-through: the advertised take. */\n  commissionCents: number\n  /** Take handed back with refunds and chargebacks, pro-rata. */\n  commissionRefundedCents: number\n  /** Take net of reversals. */\n  commissionNetCents: number\n  /**\n   * Storefront SUBSCRIPTION cycles in this period. Counted because a cycle\n   * billed before its subscription was re-priced onto the pass-through\n   * reports no take at all — see the module note.\n   */\n  subscriptionOrders: number\n  /**\n   * The sweep hit its ceiling, so every figure above is a LOWER BOUND and must\n   * not be quoted as a total. Narrow the period instead.\n   */\n  truncated: boolean\n}\n\n/** Cents from anything, defaulting to 0 rather than NaN. */\nfunction cents(value: unknown): number {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) ? Math.round(parsed) : 0\n}\n\n/**\n * Whether this order row was a test-mode rehearsal.\n *\n * A recorded `livemode` wins, and the session id's prefix is the fallback for\n * rows written before anything recorded it. An order with neither signal is\n * LIVE: a POS cash sale carries no Stripe session at all, and answering \"test\"\n * for anything unidentifiable would erase genuine revenue from the report.\n */\nfunction isTestModeOrderRow(row: CommerceOrderRowInput): boolean {\n  if (typeof row.livemode === 'boolean') return !row.livemode\n  return stripeIdIsTestMode(row.checkoutSessionId ?? row.id)\n}\n\nexport function commerceSettledSummary(\n  rows: readonly CommerceOrderRowInput[],\n  truncated = false,\n): CommerceSettled {\n  const out: CommerceSettled = {\n    transactionCount: 0,\n    grossCents: 0,\n    applicationFeeCents: 0,\n    processingPassThroughCents: 0,\n    commissionCents: 0,\n    commissionRefundedCents: 0,\n    commissionNetCents: 0,\n    subscriptionOrders: 0,\n    truncated: truncated === true,\n  }\n  for (const row of rows ?? []) {\n    // A REHEARSAL IS NOT REVENUE. A smoke-test checkout writes a real order\n    // document — Stripe never moved money for it, and its session id says so.\n    // Skipped ENTIRELY rather than counted at zero, because `transactionCount`\n    // is read as \"how many sales\", and a rehearsal is not one.\n    if (isTestModeOrderRow(row)) continue\n    const split = commerceOrderTake(row)\n    out.transactionCount += 1\n    out.grossCents += split.gross\n    out.applicationFeeCents += split.fee\n    if (split.isSubscriptionOrder) out.subscriptionOrders += 1\n    out.processingPassThroughCents += split.passThrough\n    out.commissionCents += split.take\n    out.commissionRefundedCents += split.takeRefunded\n    out.commissionNetCents += split.takeNet\n  }\n  return out\n}\n\n/**\n * One storefront order's take, in ONE place.\n *\n * Shared with the per-host attribution so a host table cannot sum to\n * something other than the storefront line above it.\n *\n * A zero-fee order contributes its gross and its count and nothing else —\n * there is no take to attribute, and inventing one from the gross would\n * report a merchant's money as the platform's.\n */\nexport function commerceOrderTake(row: CommerceOrderRowInput | null): {\n  gross: number\n  fee: number\n  isSubscriptionOrder: boolean\n  passThrough: number\n  take: number\n  takeRefunded: number\n  takeNet: number\n} {\n  const gross = cents(row?.amountCents)\n  const fee = Math.max(0, cents(row?.feeCents))\n  const isSubscriptionOrder =\n    typeof row?.subscriptionId === 'string' && row.subscriptionId.length > 0\n  if (fee <= 0) {\n    return {\n      gross,\n      fee,\n      isSubscriptionOrder,\n      passThrough: 0,\n      take: 0,\n      takeRefunded: 0,\n      takeNet: 0,\n    }\n  }\n  // Every fee bundles the recovery — a one-time sale's in cents, a\n  // subscription cycle's as a rate (AGL-2655). Clamped to the fee itself: the\n  // recomputed cost can exceed a fee charged under an older rate, and a\n  // negative take would subtract from another order's real margin.\n  const passThrough = Math.min(fee, storefrontProcessingCostCents(gross))\n  const take = fee - passThrough\n  const refunded = Math.min(gross, Math.max(0, cents(row?.refundedCents)))\n  const takeRefunded = gross > 0 ? Math.round((refunded * take) / gross) : 0\n  return {\n    gross,\n    fee,\n    isSubscriptionOrder,\n    passThrough,\n    take,\n    takeRefunded,\n    takeNet: take - takeRefunded,\n  }\n}\n\n/**\n * Storefront take by HOST.\n *\n * By host and not by org on purpose: one org can run several storefronts, and\n * \"which store earns\" is the question a per-org roll-up destroys.\n */\nexport function commerceHostAttribution(\n  rows: readonly CommerceOrderRowInput[],\n  limit = 100,\n): RevenueAttribution {\n  return groupRevenueAttribution(\n    (rows ?? []).map((row) => {\n      const split = commerceOrderTake(row)\n      return {\n        key: String(row?.hostId ?? ''),\n        detail: '',\n        gain: split.takeNet,\n        loss: split.takeRefunded,\n      }\n    }),\n    limit,\n    'Host not recorded',\n  )\n}\n\n/**\n * The storefront's answer for one period, from figures already folded. Pure,\n * so what the report prints can be proved from fixtures.\n *\n * `failed` is a sweep that could not run — a collection-group index this\n * deployment has not built answers FAILED_PRECONDITION — and it is reported as\n * a failure with figures of zero, never as a cap: \"we read part of it\" and \"we\n * read none of it\" have different remedies.\n */\nexport function commerceRevenueAnswer(read: {\n  settled: CommerceSettled\n  byHost: RevenueAttribution\n  failed: boolean\n}): RevenueSourceAnswer {\n  const brand = PLATFORM_BRAND_NAME\n  const { settled } = read\n  return {\n    id: 'commerce',\n    name: 'storefront orders',\n    earned: {\n      label: 'Storefront commission',\n      cents: Number(settled.commissionNetCents ?? 0),\n      note:\n        'The advertised take on merchant storefront sales, net of refunds — ' +\n        'with Stripe’s card processing removed. The platform fee charged on a ' +\n        'storefront sale bundles that processing cost and passes it through at ' +\n        'cost; it is a recovery, not earnings.',\n    },\n    grossToNet: [\n      {\n        label: 'Storefront sales (shopper gross)',\n        cents: settled.grossCents,\n        deduction: false,\n        note:\n          'The merchant’s. It transfers straight to their connected account ' +\n          'and is shown only for scale.',\n      },\n      {\n        label: 'Storefront platform fee collected',\n        cents: settled.applicationFeeCents,\n        deduction: false,\n        note: `Not all ${brand}’s — see the next line.`,\n      },\n      {\n        label: '— less card processing passed through at cost',\n        cents: settled.processingPassThroughCents,\n        deduction: true,\n        note: `Stripe’s. On a destination charge Stripe debits ${brand}’s balance for processing, and this half of the fee recovers exactly that. It is a recovery, not earnings, and reporting it as revenue would overstate every storefront sale.`,\n      },\n    ],\n    notes:\n      Number(settled.subscriptionOrders ?? 0) > 0\n        ? [\n            {\n              label: `${settled.subscriptionOrders} storefront subscription cycles — one billed before its re-price reports no take`,\n              tone: 'warning',\n            },\n          ]\n        : [],\n    attribution: [\n      {\n        id: 'byHost',\n        heading: 'Storefront take by host',\n        unit: 'Storefront',\n        countLabel: 'Orders',\n        empty: `No storefront order settled in this period. Note this is ${brand}'s take only — the shopper's spend is the merchant's money and is never counted here.`,\n        chartEmpty: 'No storefront earned a take in this period — nothing to plot yet.',\n        ...read.byHost,\n      },\n    ],\n    attributionNote:\n      \"Storefront figures above are the advertised take with Stripe's \" +\n      'processing cost already subtracted, on the basis stated in “Gross ' +\n      'versus net” below. Attribution is by host rather than by org because ' +\n      'one org can run several storefronts, and rolling them up destroys the ' +\n      'question.',\n    truncated: settled.truncated,\n    failure: read.failed\n      ? {\n          title: 'Storefront orders could not be read',\n          detail:\n            'The storefront commission below reads $0 because the query ' +\n            'failed, not because there were no sales. The sweep needs the ' +\n            'COLLECTION_GROUP index on orders.createdAtMs — check it is still ' +\n            'declared in the Firestore index config and actually deployed, ' +\n            'since indexes ship separately from the app.',\n        }\n      : null,\n    summary: settled,\n  }\n}\n\n/**\n * The storefront's source, registered on the console's API surface: the\n * staff revenue report awaits that surface before it asks.\n */\nexport const commerceRevenueSource: RevenueSource = {\n  async read(request) {\n    const firestore = firebaseAdmin.app().firestore()\n    // Storefront orders live per host (`hosts/{hostId}/orders`), so this is a\n    // collection-GROUP range — ranged on `createdAtMs`, the NUMBER, and not on\n    // the `createdAt` Timestamp beside it. A collection-group range needs a\n    // COLLECTION_GROUP-scoped single-field index — Firestore's automatic ones\n    // are COLLECTION scope only — and the index that is declared and deployed\n    // is on `createdAtMs` (AGL-1793). The `createdAt` form answers\n    // FAILED_PRECONDITION on every request, which is how the report once read\n    // $0 for every storefront.\n    let swept: {\n      docs: FirebaseFirestore.QueryDocumentSnapshot[]\n      truncated: boolean\n    } | null\n    try {\n      swept = await request.sweep<FirebaseFirestore.QueryDocumentSnapshot>(\n        firestore\n          .collectionGroup('orders')\n          .where('createdAtMs', '>=', request.start.getTime())\n          .where('createdAtMs', '<', request.end.getTime()),\n        'createdAtMs',\n      )\n    } catch {\n      swept = null\n    }\n    const rows: CommerceOrderRowInput[] = (swept?.docs ?? []).map((doc) => ({\n      id: doc.id,\n      // The storefront that earned the take is in the PATH.\n      hostId: doc.ref.parent.parent?.id ?? '',\n      ...(doc.data() as object),\n    }))\n    const settled = commerceSettledSummary(rows, swept?.truncated === true)\n    const byHost = commerceHostAttribution(rows, request.attributionLimit)\n    await request.nameRows(byHost.rows, {\n      collection: 'hosts',\n      nameField: 'displayName',\n      detailField: 'subdomain',\n    })\n    return commerceRevenueAnswer({ settled, byHost, failed: swept === null })\n  },\n}\n"],"names":["firebaseAdmin","storefrontProcessingCostCents","PLATFORM_BRAND_NAME","stripeIdIsTestMode","groupRevenueAttribution","cents","value","parsed","Number","isFinite","Math","round","isTestModeOrderRow","row","livemode","checkoutSessionId","id","commerceSettledSummary","rows","truncated","out","transactionCount","grossCents","applicationFeeCents","processingPassThroughCents","commissionCents","commissionRefundedCents","commissionNetCents","subscriptionOrders","split","commerceOrderTake","gross","fee","isSubscriptionOrder","passThrough","take","takeRefunded","takeNet","amountCents","max","feeCents","subscriptionId","length","min","refunded","refundedCents","commerceHostAttribution","limit","map","key","String","hostId","detail","gain","loss","commerceRevenueAnswer","read","settled","brand","name","earned","label","note","grossToNet","deduction","notes","tone","attribution","heading","unit","countLabel","empty","chartEmpty","byHost","attributionNote","failure","failed","title","summary","commerceRevenueSource","request","firestore","app","swept","sweep","collectionGroup","where","start","getTime","end","docs","doc","ref","parent","data","attributionLimit","nameRows","collection","nameField","detailField"],"mappings":"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"}

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

@@ -17,13 +17,16 @@
 /**
  * The merchant's tax rule, published for every plugin that charges.
  *
- * A merchant sets tax once, in the store settings this plugin keeps. A plugin
- * that sells something else — an appointment — prices its own charge, and used
- * to import `resolveFlatTaxCents` and `storefrontTaxModeOf` from here to do it.
- * It asks the tax-profile contract now, and gets these same two functions: one
- * rounding rule, one reading of a settled payment, wherever money is taken.
+ * A merchant sets tax once, in the store settings this plugin keeps
+ * (`hosts/{hostId}/settings/store`, under `tax`). A plugin that sells
+ * something else — an appointment — prices its own charge by asking the
+ * tax-profile contract: for the site's rate for that kind of charge, read
+ * here, and for these same two functions over it — one rounding rule, one
+ * reading of a settled payment, wherever money is taken.
  *
  * Registered from BOTH server registrars, because a booking is priced in the
  * tenant app and confirmed by the console's billing webhook.
  */
 export declare function registerCommerceTaxProfile(): void;
+/** One site's stored flat rate for a kind of charge, as stored. */
+export declare function readFlatRate(hostId: string, charge: string): Promise<unknown>;

package/src/lib/server/tax-profile.js

@@ -14,27 +14,44 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ import { registerPluginTaxProfile } from "@aglyn/aglyn/plugin-manager/plugin-tax-profile";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin";
 import { BUNDLE_ID } from "../constants/bundle-common.js";
 import { resolveFlatTaxCents } from "../model/index.js";
 import { storefrontTaxModeOf } from "./storefront-tax.js";
 /**
  * The merchant's tax rule, published for every plugin that charges.
  *
- * A merchant sets tax once, in the store settings this plugin keeps. A plugin
- * that sells something else — an appointment — prices its own charge, and used
- * to import `resolveFlatTaxCents` and `storefrontTaxModeOf` from here to do it.
- * It asks the tax-profile contract now, and gets these same two functions: one
- * rounding rule, one reading of a settled payment, wherever money is taken.
+ * A merchant sets tax once, in the store settings this plugin keeps
+ * (`hosts/{hostId}/settings/store`, under `tax`). A plugin that sells
+ * something else — an appointment — prices its own charge by asking the
+ * tax-profile contract: for the site's rate for that kind of charge, read
+ * here, and for these same two functions over it — one rounding rule, one
+ * reading of a settled payment, wherever money is taken.
  *
  * Registered from BOTH server registrars, because a booking is priced in the
  * tenant app and confirmed by the console's billing webhook.
  */ export function registerCommerceTaxProfile() {
     registerPluginTaxProfile({
+        flatRate: (hostId, charge)=>readFlatRate(hostId, charge),
         flatTax: (rate, chargeCents, fallbackLabel)=>resolveFlatTaxCents(rate, chargeCents, fallbackLabel),
         taxModeOf: (settledPayment, manualTaxCents)=>storefrontTaxModeOf(settledPayment, manualTaxCents)
     }, {
         pluginId: BUNDLE_ID
     });
 }
+/**
+ * The flat rates the store settings keep, by the kind of charge a caller
+ * names. A kind not listed has no rate here, and answers `undefined`.
+ */ const FLAT_RATE_CHARGES = {
+    service: 'service',
+    lodging: 'lodging'
+};
+/** One site's stored flat rate for a kind of charge, as stored. */ export async function readFlatRate(hostId, charge) {
+    const field = FLAT_RATE_CHARGES[charge];
+    if (!hostId || !field) return undefined;
+    const snapshot = await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).collection('settings').doc('store').get();
+    const tax = snapshot.exists ? snapshot.get('tax') : undefined;
+    return tax == null ? void 0 : tax[field];
+}
 
 //# sourceMappingURL=tax-profile.js.map

package/src/lib/server/tax-profile.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/tax-profile.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { registerPluginTaxProfile } from '@aglyn/aglyn/plugin-manager/plugin-tax-profile'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport { type FlatTaxRate, resolveFlatTaxCents } from '../model'\nimport { storefrontTaxModeOf } from './storefront-tax'\n\n/**\n * The merchant's tax rule, published for every plugin that charges.\n *\n * A merchant sets tax once, in the store settings this plugin keeps. A plugin\n * that sells something else — an appointment — prices its own charge, and used\n * to import `resolveFlatTaxCents` and `storefrontTaxModeOf` from here to do it.\n * It asks the tax-profile contract now, and gets these same two functions: one\n * rounding rule, one reading of a settled payment, wherever money is taken.\n *\n * Registered from BOTH server registrars, because a booking is priced in the\n * tenant app and confirmed by the console's billing webhook.\n */\nexport function registerCommerceTaxProfile(): void {\n  registerPluginTaxProfile(\n    {\n      flatTax: (rate, chargeCents, fallbackLabel) =>\n        resolveFlatTaxCents(\n          rate as FlatTaxRate | undefined | null,\n          chargeCents,\n          fallbackLabel,\n        ),\n      taxModeOf: (settledPayment, manualTaxCents) =>\n        storefrontTaxModeOf(settledPayment, manualTaxCents),\n    },\n    { pluginId: BUNDLE_ID },\n  )\n}\n"],"names":["registerPluginTaxProfile","BUNDLE_ID","resolveFlatTaxCents","storefrontTaxModeOf","registerCommerceTaxProfile","flatTax","rate","chargeCents","fallbackLabel","taxModeOf","settledPayment","manualTaxCents","pluginId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,wBAAwB,QAAQ,iDAAgD;AACzF,SAASC,SAAS,QAAQ,gCAA4B;AACtD,SAA2BC,mBAAmB,QAAQ,oBAAU;AAChE,SAASC,mBAAmB,QAAQ,sBAAkB;AAEtD;;;;;;;;;;;CAWC,GACD,OAAO,SAASC;IACdJ,yBACE;QACEK,SAAS,CAACC,MAAMC,aAAaC,gBAC3BN,oBACEI,MACAC,aACAC;QAEJC,WAAW,CAACC,gBAAgBC,iBAC1BR,oBAAoBO,gBAAgBC;IACxC,GACA;QAAEC,UAAUX;IAAU;AAE1B"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/tax-profile.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { registerPluginTaxProfile } from '@aglyn/aglyn/plugin-manager/plugin-tax-profile'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport { type FlatTaxRate, resolveFlatTaxCents, type TaxSettings } from '../model'\nimport { storefrontTaxModeOf } from './storefront-tax'\n\n/**\n * The merchant's tax rule, published for every plugin that charges.\n *\n * A merchant sets tax once, in the store settings this plugin keeps\n * (`hosts/{hostId}/settings/store`, under `tax`). A plugin that sells\n * something else — an appointment — prices its own charge by asking the\n * tax-profile contract: for the site's rate for that kind of charge, read\n * here, and for these same two functions over it — one rounding rule, one\n * reading of a settled payment, wherever money is taken.\n *\n * Registered from BOTH server registrars, because a booking is priced in the\n * tenant app and confirmed by the console's billing webhook.\n */\nexport function registerCommerceTaxProfile(): void {\n  registerPluginTaxProfile(\n    {\n      flatRate: (hostId, charge) => readFlatRate(hostId, charge),\n      flatTax: (rate, chargeCents, fallbackLabel) =>\n        resolveFlatTaxCents(\n          rate as FlatTaxRate | undefined | null,\n          chargeCents,\n          fallbackLabel,\n        ),\n      taxModeOf: (settledPayment, manualTaxCents) =>\n        storefrontTaxModeOf(settledPayment, manualTaxCents),\n    },\n    { pluginId: BUNDLE_ID },\n  )\n}\n\n/**\n * The flat rates the store settings keep, by the kind of charge a caller\n * names. A kind not listed has no rate here, and answers `undefined`.\n */\nconst FLAT_RATE_CHARGES: Readonly<Record<string, keyof TaxSettings>> = {\n  service: 'service',\n  lodging: 'lodging',\n}\n\n/** One site's stored flat rate for a kind of charge, as stored. */\nexport async function readFlatRate(\n  hostId: string,\n  charge: string,\n): Promise<unknown> {\n  const field = FLAT_RATE_CHARGES[charge]\n  if (!hostId || !field) return undefined\n  const snapshot = await firebaseAdmin\n    .app()\n    .firestore()\n    .collection('hosts')\n    .doc(hostId)\n    .collection('settings')\n    .doc('store')\n    .get()\n  const tax = (snapshot.exists ? snapshot.get('tax') : undefined) as\n    | TaxSettings\n    | undefined\n  return tax?.[field]\n}\n"],"names":["registerPluginTaxProfile","firebaseAdmin","BUNDLE_ID","resolveFlatTaxCents","storefrontTaxModeOf","registerCommerceTaxProfile","flatRate","hostId","charge","readFlatRate","flatTax","rate","chargeCents","fallbackLabel","taxModeOf","settledPayment","manualTaxCents","pluginId","FLAT_RATE_CHARGES","service","lodging","field","undefined","snapshot","app","firestore","collection","doc","get","tax","exists"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,wBAAwB,QAAQ,iDAAgD;AACzF,SAASC,aAAa,QAAQ,2BAA0B;AACxD,SAASC,SAAS,QAAQ,gCAA4B;AACtD,SAA2BC,mBAAmB,QAA0B,oBAAU;AAClF,SAASC,mBAAmB,QAAQ,sBAAkB;AAEtD;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC;IACdL,yBACE;QACEM,UAAU,CAACC,QAAQC,SAAWC,aAAaF,QAAQC;QACnDE,SAAS,CAACC,MAAMC,aAAaC,gBAC3BV,oBACEQ,MACAC,aACAC;QAEJC,WAAW,CAACC,gBAAgBC,iBAC1BZ,oBAAoBW,gBAAgBC;IACxC,GACA;QAAEC,UAAUf;IAAU;AAE1B;AAEA;;;CAGC,GACD,MAAMgB,oBAAiE;IACrEC,SAAS;IACTC,SAAS;AACX;AAEA,iEAAiE,GACjE,OAAO,eAAeX,aACpBF,MAAc,EACdC,MAAc;IAEd,MAAMa,QAAQH,iBAAiB,CAACV,OAAO;IACvC,IAAI,CAACD,UAAU,CAACc,OAAO,OAAOC;IAC9B,MAAMC,WAAW,MAAMtB,cACpBuB,GAAG,GACHC,SAAS,GACTC,UAAU,CAAC,SACXC,GAAG,CAACpB,QACJmB,UAAU,CAAC,YACXC,GAAG,CAAC,SACJC,GAAG;IACN,MAAMC,MAAON,SAASO,MAAM,GAAGP,SAASK,GAAG,CAAC,SAASN;IAGrD,OAAOO,uBAAAA,GAAK,CAACR,MAAM;AACrB"}

package/src/lib/server/tax-return-source.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @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 { TaxReturnFiling, TaxReturnFilingLine, TaxReturnFinding, TaxReturnSource, TaxReturnSourceAnswer, TaxReturnSourceRequest } from '@aglyn/aglyn/plugin-manager/plugin-tax-return-sources';
+import { type StorefrontTaxReturnRowInput, type StorefrontTaxSummary } from '../model/storefront-tax-summary';
+/** One row of the storefront listing, as the working papers carry it. */
+export interface StorefrontTaxRow {
+    id: string;
+    hostId: string | null;
+    orgId: string | null;
+    paidAt: string | null;
+    taxMode: string | null;
+    taxLiability: string | null;
+    grossCents: number;
+    taxCents: number;
+    taxableSalesCents: number;
+    state: string | null;
+    country: string | null;
+}
+/** A liability bucket, ready to print. */
+export interface StorefrontTaxBucketRow {
+    id: 'aglynLiable' | 'merchantManual' | 'connectedAccountLiable';
+    label: string;
+    /** Who owes it — the sentence that decides whether it is on this return. */
+    liability: string;
+    transactionCount: number;
+    grossDollars: string;
+    taxableSalesDollars: string;
+    taxCollectedDollars: string;
+    /** True when this row is money in the platform's balance under its registration. */
+    platformLiable: boolean;
+}
+/** One state's facilitated storefront sales, for the nexus question. */
+export interface StorefrontFacilitatedJurisdictionRow {
+    jurisdiction: string;
+    /** True for the one jurisdiction this deployment files a return in. */
+    isFilingJurisdiction: boolean;
+    transactionCount: number;
+    totalSalesDollars: string;
+    taxCollectedDollars: string;
+    /** The part of `taxCollectedDollars` the platform holds and must remit. */
+    platformLiableTaxDollars: string;
+    /** True when NO tax was collected on any sale into this state. */
+    untaxed: boolean;
+}
+/**
+ * Storefront tax in the FILING jurisdiction that Stripe computed against the
+ * platform's own registrations.
+ *
+ * The one figure that decides whether a period can be filed from the filing
+ * lines alone. Deliberately excludes `merchantManual` — a merchant's own
+ * configured rate never touched those registrations. Read against the
+ * configured jurisdiction rather than Texas, because a hard-coded key answers
+ * `0.00` everywhere else — and a zero here reads as "nothing to decide" on
+ * the one finding that blocks filing.
+ */
+export declare function storefrontPlatformLiableCents(summary: StorefrontTaxSummary | null | undefined, filing: TaxReturnFiling): number;
+/** The storefront's findings. The platform raises the non-zero ones. */
+export declare function storefrontTaxFindings(summary: StorefrontTaxSummary, filing: TaxReturnFiling): TaxReturnFinding[];
+/**
+ * The two lines beneath the filing figures: the platform-liable tax and the
+ * merchant's own rate, separately, and outside every form item.
+ */
+export declare function storefrontFilingLines(summary: StorefrontTaxSummary, filing: TaxReturnFiling): TaxReturnFilingLine[];
+/** The three liability buckets, in the order a reader decides them. */
+export declare function storefrontBucketRows(summary: StorefrontTaxSummary): StorefrontTaxBucketRow[];
+/**
+ * FACILITATED SALES BY STATE — the economic-nexus question (AGL-1956).
+ *
+ * The question a state asks a marketplace facilitator is "how much did you
+ * facilitate INTO this state, and in how many transactions" — not "how much
+ * tax did you collect there". A state the operator is not registered in
+ * collects nothing by definition, which is exactly why collection cannot be
+ * the measure: the states worth watching are the ones showing $0 tax and a
+ * rising sales figure.
+ *
+ * So this SUMS the three liability buckets per jurisdiction. The rule that
+ * the operator's own invoices and storefront rows are never summed still
+ * holds — nothing here touches the operator's own sales; within the
+ * storefront collection the buckets differ only in WHO REMITS, and a nexus
+ * threshold counts the sale whoever remits it. Who remits is still carried
+ * per row, because "do we have nexus here" and "what do we owe here" are
+ * answered off the same rows and must not blur.
+ *
+ * ⚠️ A LOWER BOUND, deliberately rather than silently: `storefront-tax-record.ts`
+ * files no row at all for a sale whose `taxMode` resolves to `none`, so a
+ * wholly untaxed storefront sale is invisible here — the population nexus
+ * detection most needs. Closing it is a write-side change recorded on
+ * AGL-1956. The filing jurisdiction does not depend on any of this: a filer
+ * registered where it is established has no in-state threshold left to cross.
+ */
+export declare function storefrontFacilitatedJurisdictionRows(summary: StorefrontTaxSummary | null | undefined, filing: TaxReturnFiling): StorefrontFacilitatedJurisdictionRow[];
+/**
+ * The storefront's answer for one period, from rows already read. Pure, so
+ * the section a preparer reads can be proved from fixtures.
+ */
+export declare function storefrontTaxReturnAnswer(read: {
+    rows: readonly StorefrontTaxReturnRowInput[];
+    truncated: boolean;
+    undatedRows: number;
+}, request: TaxReturnSourceRequest): TaxReturnSourceAnswer;
+/**
+ * The storefront's source, registered on the console's API surface: the
+ * staff return awaits that surface before it asks.
+ *
+ * Two queries, and the second is the honesty check: the period query ranges
+ * on `paidAt`, and a Firestore range query CANNOT match a document whose
+ * field is null — so a row that failed to date itself would be invisible to
+ * every period. The equality probe counts those rows, over all of them, and
+ * the platform blocks the return on any.
+ */
+export declare const commerceTaxReturnSource: TaxReturnSource;