@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/order-analytics.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @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 { PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * The figures a storefront `purchase` needs, for one completed order
+ * (AGL-1641).
+ *
+ * ## Why the client cannot compute this itself
+ *
+ * The obvious cheap design is to stash the cart at `begin_checkout` and replay
+ * it on return, with no endpoint at all. It produces the wrong number: the
+ * shopper picks their SHIPPING and may enter a promotion code on Stripe's
+ * page, after the cart snapshot was taken, so a replayed cart understates
+ * every order that carries shipping. The authoritative totals only exist after
+ * the webhook has written the order, which is why this reads the order.
+ *
+ * ## What authorises the read
+ *
+ * The Stripe Checkout Session id, which is also the order doc id. It is
+ * high-entropy and unguessable, it is handed only to the buyer — Stripe puts
+ * it in the `success_url` — and it is scoped here to the host that owns the
+ * order, so one storefront's id cannot address another's. This is the same
+ * bearer-by-opaque-id shape as the `download` and `subscription-portal`
+ * routes.
+ *
+ * It is still a public read, so the response is a PROJECTION built by
+ * `toStorefrontPurchaseSource`, never the order document: no email, no name,
+ * no shipping or billing address, and not our `feeCents` either. A buyer
+ * learns only what they themselves just bought.
+ *
+ * ## The webhook race
+ *
+ * The shopper can return from Stripe before the `checkout.session.completed`
+ * delivery has been processed, in which case the order does not exist yet.
+ * That is answered with 404 and a `retryable` flag rather than a synthesised
+ * order — the client polls briefly. Reporting a purchase we cannot yet read
+ * would mean inventing the value.
+ *
+ * Never cached: an order that 404s during the race must not have that 404
+ * stored in front of it, which is the AGL negative-cache shape that has bitten
+ * host lookups before.
+ *
+ * ## Subscriptions answer from the INVOICE, not from an order (AGL-1746)
+ *
+ * A subscription sale writes no order document — deliberately, on three
+ * independent pieces of evidence gathered in AGL-1732 — so the lookup above
+ * missed forever on every one of them. The merchant's own GA4 property
+ * therefore showed traffic and `begin_checkout` for the subscription product
+ * and then no `purchase` at all, which does not read as "we do not measure
+ * this": it reads as a 100% checkout abandonment rate on the product, an
+ * authoritative-looking number that is wrong.
+ *
+ * The data to answer with exists now. AGL-1732 records the sale on
+ * `subscriptions/{stripeSubscriptionId}` carrying the originating
+ * `checkoutSessionId`, and AGL-1743 records every paid invoice beneath it,
+ * including the opening one — kept explicitly so the ledger has no hole where
+ * cycle 1 belongs, even though that cycle is deliberately not re-counted into
+ * lifetime value.
+ *
+ * The opening INVOICE is what answers, for two reasons:
+ *
+ * - Its id is a natural `transaction_id`. It is Stripe's own id for the money
+ *   that moved, it is unique per cycle, and it is stable — the same sale
+ *   resolves to the same invoice on every poll, so a shopper who refreshes the
+ *   return page cannot produce a second `purchase` under a different id. GA4
+ *   de-duplicates on `transaction_id`, and that only protects us if the id is
+ *   deterministic.
+ * - Its `lineItems` and `totals` were built by
+ *   `computeSubscriptionInvoiceOrder`, which is the helper that knows an
+ *   invoice is NOT a Checkout Session: AGL-1743 found invoices carry no
+ *   `total_details` whatsoever, that tax is `tax` or `total_taxes` by API
+ *   version, discount is `total_discount_amounts[]`, and the fee is a real
+ *   `application_fee_amount`. Reading the stored figures means this route
+ *   inherits all of that instead of re-deriving it against the wrong shape.
+ *
+ * `value` needs no special-casing here, and that is the point of answering in
+ * the same wire shape: `toStorefrontPurchaseSource` and
+ * `buildStorefrontPurchaseParams` already implement the AGL-1641 storefront
+ * rule, which is the INVERSE of the marketplace one. On a tenant storefront
+ * the MERCHANT is the seller, so Aglyn's fee is their cost of sale rather than
+ * a deduction from it and is NOT subtracted; tax is money held for the state
+ * and is excluded, with no GA4 `tax` param sent beside an ex-tax `value`.
+ * Getting that backwards would show every merchant a figure a few percent of
+ * their real revenue.
+ *
+ * ## Renewals do NOT send a `purchase` — and could not
+ *
+ * A recurring revenue event per cycle is arguable on the merits, and the
+ * argument against it on the merits is real: `purchase` is what GA4's
+ * acquisition and ROAS reporting is terminated by, so firing one every month
+ * would credit a single acquisition to its campaign twelve times over and
+ * inflate return on ad spend by the subscriber's whole lifetime.
+ *
+ * But it does not come down to that, because this seam cannot carry a renewal
+ * at all. This purchase is CLIENT-side by design: the hit is sent by
+ * `use-storefront-purchase-event.ts` through the merchant's own `gtag`, loaded
+ * with `host.analytics.gaMeasurementId`. A renewal happens months later with
+ * no browser anywhere in it. Sending one would require the Measurement
+ * Protocol against the merchant's property, which needs a per-host API secret
+ * that this product does not collect and has nowhere to store — the same
+ * conclusion `use-storefront-purchase-event.ts` reached from the other
+ * direction. `ga4-measurement-protocol.ts` is not that channel: it holds one
+ * global `GA4_MEASUREMENT_ID`/`GA4_API_SECRET` pair, which is AGLYN's property
+ * and reports our revenue, not the merchant's.
+ *
+ * So the storefront reports the subscription's FIRST payment, once, and stops
+ * — mirroring AGL-1743's own decision not to re-count the opening invoice
+ * anywhere the checkout session had already been counted.
+ *
+ * ## Why both lookups run
+ *
+ * A Checkout Session id does not say whether it was a one-time or a
+ * subscription mode session, so a miss on the order genuinely might be either
+ * the webhook race or a subscription. The subscription lookups therefore run
+ * on every order miss. Both are single-field equality queries with `limit(1)`,
+ * which Firestore serves from the automatic single-field indexes it maintains
+ * for every field — there is no composite index here to create, and none to
+ * probe.
+ */
+export declare const orderAnalyticsHandler: PluginApiHandler;

package/src/lib/server/order-analytics.js

@@ -0,0 +1,263 @@
+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 { stripeIdIsTestMode } from "@aglyn/aglyn/app-utils/stripe-deployment-mode";
+import * as CommerceModel from "../model/index.js";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { toStorefrontPurchaseSource } from "../model/purchase-analytics.js";
+/** Stripe Checkout Session ids: `cs_` + live/test prefix + base58-ish body. */ const SESSION_ID = /^cs_[A-Za-z0-9_]{8,255}$/;
+/**
+ * Stripe's `billing_reason` for the invoice a subscription OPENS with, as
+ * opposed to the `subscription_cycle` ones that follow it (AGL-1743 stores
+ * both under the subscription).
+ */ const OPENING_INVOICE_REASON = 'subscription_create';
+/**
+ * The figures a storefront `purchase` needs, for one completed order
+ * (AGL-1641).
+ *
+ * ## Why the client cannot compute this itself
+ *
+ * The obvious cheap design is to stash the cart at `begin_checkout` and replay
+ * it on return, with no endpoint at all. It produces the wrong number: the
+ * shopper picks their SHIPPING and may enter a promotion code on Stripe's
+ * page, after the cart snapshot was taken, so a replayed cart understates
+ * every order that carries shipping. The authoritative totals only exist after
+ * the webhook has written the order, which is why this reads the order.
+ *
+ * ## What authorises the read
+ *
+ * The Stripe Checkout Session id, which is also the order doc id. It is
+ * high-entropy and unguessable, it is handed only to the buyer — Stripe puts
+ * it in the `success_url` — and it is scoped here to the host that owns the
+ * order, so one storefront's id cannot address another's. This is the same
+ * bearer-by-opaque-id shape as the `download` and `subscription-portal`
+ * routes.
+ *
+ * It is still a public read, so the response is a PROJECTION built by
+ * `toStorefrontPurchaseSource`, never the order document: no email, no name,
+ * no shipping or billing address, and not our `feeCents` either. A buyer
+ * learns only what they themselves just bought.
+ *
+ * ## The webhook race
+ *
+ * The shopper can return from Stripe before the `checkout.session.completed`
+ * delivery has been processed, in which case the order does not exist yet.
+ * That is answered with 404 and a `retryable` flag rather than a synthesised
+ * order — the client polls briefly. Reporting a purchase we cannot yet read
+ * would mean inventing the value.
+ *
+ * Never cached: an order that 404s during the race must not have that 404
+ * stored in front of it, which is the AGL negative-cache shape that has bitten
+ * host lookups before.
+ *
+ * ## Subscriptions answer from the INVOICE, not from an order (AGL-1746)
+ *
+ * A subscription sale writes no order document — deliberately, on three
+ * independent pieces of evidence gathered in AGL-1732 — so the lookup above
+ * missed forever on every one of them. The merchant's own GA4 property
+ * therefore showed traffic and `begin_checkout` for the subscription product
+ * and then no `purchase` at all, which does not read as "we do not measure
+ * this": it reads as a 100% checkout abandonment rate on the product, an
+ * authoritative-looking number that is wrong.
+ *
+ * The data to answer with exists now. AGL-1732 records the sale on
+ * `subscriptions/{stripeSubscriptionId}` carrying the originating
+ * `checkoutSessionId`, and AGL-1743 records every paid invoice beneath it,
+ * including the opening one — kept explicitly so the ledger has no hole where
+ * cycle 1 belongs, even though that cycle is deliberately not re-counted into
+ * lifetime value.
+ *
+ * The opening INVOICE is what answers, for two reasons:
+ *
+ * - Its id is a natural `transaction_id`. It is Stripe's own id for the money
+ *   that moved, it is unique per cycle, and it is stable — the same sale
+ *   resolves to the same invoice on every poll, so a shopper who refreshes the
+ *   return page cannot produce a second `purchase` under a different id. GA4
+ *   de-duplicates on `transaction_id`, and that only protects us if the id is
+ *   deterministic.
+ * - Its `lineItems` and `totals` were built by
+ *   `computeSubscriptionInvoiceOrder`, which is the helper that knows an
+ *   invoice is NOT a Checkout Session: AGL-1743 found invoices carry no
+ *   `total_details` whatsoever, that tax is `tax` or `total_taxes` by API
+ *   version, discount is `total_discount_amounts[]`, and the fee is a real
+ *   `application_fee_amount`. Reading the stored figures means this route
+ *   inherits all of that instead of re-deriving it against the wrong shape.
+ *
+ * `value` needs no special-casing here, and that is the point of answering in
+ * the same wire shape: `toStorefrontPurchaseSource` and
+ * `buildStorefrontPurchaseParams` already implement the AGL-1641 storefront
+ * rule, which is the INVERSE of the marketplace one. On a tenant storefront
+ * the MERCHANT is the seller, so Aglyn's fee is their cost of sale rather than
+ * a deduction from it and is NOT subtracted; tax is money held for the state
+ * and is excluded, with no GA4 `tax` param sent beside an ex-tax `value`.
+ * Getting that backwards would show every merchant a figure a few percent of
+ * their real revenue.
+ *
+ * ## Renewals do NOT send a `purchase` — and could not
+ *
+ * A recurring revenue event per cycle is arguable on the merits, and the
+ * argument against it on the merits is real: `purchase` is what GA4's
+ * acquisition and ROAS reporting is terminated by, so firing one every month
+ * would credit a single acquisition to its campaign twelve times over and
+ * inflate return on ad spend by the subscriber's whole lifetime.
+ *
+ * But it does not come down to that, because this seam cannot carry a renewal
+ * at all. This purchase is CLIENT-side by design: the hit is sent by
+ * `use-storefront-purchase-event.ts` through the merchant's own `gtag`, loaded
+ * with `host.analytics.gaMeasurementId`. A renewal happens months later with
+ * no browser anywhere in it. Sending one would require the Measurement
+ * Protocol against the merchant's property, which needs a per-host API secret
+ * that this product does not collect and has nowhere to store — the same
+ * conclusion `use-storefront-purchase-event.ts` reached from the other
+ * direction. `ga4-measurement-protocol.ts` is not that channel: it holds one
+ * global `GA4_MEASUREMENT_ID`/`GA4_API_SECRET` pair, which is AGLYN's property
+ * and reports our revenue, not the merchant's.
+ *
+ * So the storefront reports the subscription's FIRST payment, once, and stops
+ * — mirroring AGL-1743's own decision not to re-count the opening invoice
+ * anywhere the checkout session had already been counted.
+ *
+ * ## Why both lookups run
+ *
+ * A Checkout Session id does not say whether it was a one-time or a
+ * subscription mode session, so a miss on the order genuinely might be either
+ * the webhook race or a subscription. The subscription lookups therefore run
+ * on every order miss. Both are single-field equality queries with `limit(1)`,
+ * which Firestore serves from the automatic single-field indexes it maintains
+ * for every field — there is no composite index here to create, and none to
+ * probe.
+ */ export const orderAnalyticsHandler = async (req, res)=>{
+    var _req_query_hostId, _req_query_sessionId;
+    const hostId = String((_req_query_hostId = req.query.hostId) != null ? _req_query_hostId : '');
+    const sessionId = String((_req_query_sessionId = req.query.sessionId) != null ? _req_query_sessionId : '');
+    if (!hostId || !sessionId) {
+        return res.status(400).json({
+            error: 'Missing hostId or sessionId'
+        });
+    }
+    // Shape-checked before it reaches Firestore: a document id is a path
+    // segment, and an unvalidated one is how a lookup becomes a traversal.
+    if (!SESSION_ID.test(sessionId)) {
+        return res.status(400).json({
+            error: 'Invalid sessionId'
+        });
+    }
+    // A REHEARSAL MUST NOT REACH THE MERCHANT'S OWN ANALYTICS.
+    //
+    // This endpoint hands the browser a `purchase` payload that
+    // `use-storefront-purchase-event.ts` pushes through the MERCHANT's `gtag`,
+    // into the MERCHANT's GA4 property. A smoke-test checkout therefore writes a
+    // fake sale into a real merchant's funnel — the same pollution as the
+    // revenue cards, except it lands somewhere Aglyn does not control and
+    // cannot later correct.
+    //
+    // Refused HERE rather than at the webhook, because this is not a webhook.
+    // The billing route's AGL-2040 livemode gate already refuses cross-mode
+    // events, so every per-sale effect driven by it — the buyer receipt, the
+    // merchant notification, the dropship purchase order — is covered. This
+    // route is a plain GET the storefront calls on its own success page, so it
+    // reads an order that already exists and is reached by no gate at all.
+    //
+    // The SESSION ID is the discriminator and it covers both branches below: a
+    // Checkout Session id states its mode (`cs_test_…`), while the invoice id
+    // the subscription branch reports on does NOT, so checking the invoice
+    // would miss every recurring sale.
+    //
+    // 409, matching the "Not payable" refusals below: the client retries only a
+    // 404 and treats everything else as terminal, so this fires nothing and
+    // polls nothing.
+    //
+    // FAILING TOWARDS FIRING. An unrecognised id is live: suppressing a real
+    // sale would corrupt a merchant's funnel in the one direction they can
+    // never spot, exactly as counting one would corrupt their revenue.
+    if (stripeIdIsTestMode(sessionId)) {
+        return res.status(409).json({
+            error: 'Not payable',
+            reason: 'test-mode'
+        });
+    }
+    try {
+        var _invoice_get, _invoice_data;
+        const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(hostId);
+        const snapshot = await hostRef.collection('orders').doc(sessionId).get();
+        res.setHeader('Cache-Control', 'no-store');
+        if (snapshot.exists) {
+            var _snapshot_data;
+            const order = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+            // Only a PAID order is a purchase. A session can be written in another
+            // state by the draft/POS paths, and reporting one as revenue would put a
+            // sale in the merchant's report that has not happened.
+            if (order.status !== 'paid') {
+                return res.status(409).json({
+                    error: 'Not payable'
+                });
+            }
+            // The RECORDED fact as well as the id. An order the webhook
+            // stamped `livemode: false` is a rehearsal whatever its id looks like,
+            // and this is the stronger of the two signals.
+            if (CommerceModel.orderIsTestMode(_extends({}, order, {
+                $id: snapshot.id
+            }))) {
+                return res.status(409).json({
+                    error: 'Not payable',
+                    reason: 'test-mode'
+                });
+            }
+            return res.status(200).json(toStorefrontPurchaseSource(snapshot.id, order));
+        }
+        // No order. That is either the webhook race above, or a SUBSCRIPTION sale,
+        // which records no order at all (AGL-1746). The subscription carries the
+        // session that created it.
+        const subscriptions = await hostRef.collection('subscriptions').where('checkoutSessionId', '==', sessionId).limit(1).get();
+        const subscription = subscriptions.docs[0];
+        if (!subscription) {
+            // Retryable: the race, or an id that was never ours.
+            return res.status(404).json({
+                error: 'Not found',
+                retryable: true
+            });
+        }
+        // The money, rather than the sale record: the opening invoice is what was
+        // actually collected, and its id is the transaction id.
+        const invoices = await subscription.ref.collection('invoices').where('billingReason', '==', OPENING_INVOICE_REASON).limit(1).get();
+        const invoice = invoices.docs[0];
+        if (!invoice) {
+            // `checkout.session.completed` has landed and `invoice.paid` has not —
+            // still the race, one webhook further along.
+            return res.status(404).json({
+                error: 'Not found',
+                retryable: true
+            });
+        }
+        // A TRIAL opens on a $0 invoice. Nothing was charged, so there is no
+        // revenue to report; this is the subscription's form of "not payable", and
+        // it is terminal rather than retryable because it will never become true
+        // for THIS invoice.
+        if (!(Number((_invoice_get = invoice.get('paidCents')) != null ? _invoice_get : 0) > 0)) {
+            return res.status(409).json({
+                error: 'Not payable'
+            });
+        }
+        return res.status(200).json(toStorefrontPurchaseSource(invoice.id, (_invoice_data = invoice.data()) != null ? _invoice_data : {}));
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Lookup failed'
+        });
+    }
+};
+
+//# sourceMappingURL=order-analytics.js.map

package/src/lib/server/order-analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/order-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 { stripeIdIsTestMode } from '@aglyn/aglyn/app-utils/stripe-deployment-mode'\nimport * as CommerceModel from '../model'\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { toStorefrontPurchaseSource } from '../model/purchase-analytics'\n\n/** Stripe Checkout Session ids: `cs_` + live/test prefix + base58-ish body. */\nconst SESSION_ID = /^cs_[A-Za-z0-9_]{8,255}$/\n\n/**\n * Stripe's `billing_reason` for the invoice a subscription OPENS with, as\n * opposed to the `subscription_cycle` ones that follow it (AGL-1743 stores\n * both under the subscription).\n */\nconst OPENING_INVOICE_REASON = 'subscription_create'\n\n/**\n * The figures a storefront `purchase` needs, for one completed order\n * (AGL-1641).\n *\n * ## Why the client cannot compute this itself\n *\n * The obvious cheap design is to stash the cart at `begin_checkout` and replay\n * it on return, with no endpoint at all. It produces the wrong number: the\n * shopper picks their SHIPPING and may enter a promotion code on Stripe's\n * page, after the cart snapshot was taken, so a replayed cart understates\n * every order that carries shipping. The authoritative totals only exist after\n * the webhook has written the order, which is why this reads the order.\n *\n * ## What authorises the read\n *\n * The Stripe Checkout Session id, which is also the order doc id. It is\n * high-entropy and unguessable, it is handed only to the buyer — Stripe puts\n * it in the `success_url` — and it is scoped here to the host that owns the\n * order, so one storefront's id cannot address another's. This is the same\n * bearer-by-opaque-id shape as the `download` and `subscription-portal`\n * routes.\n *\n * It is still a public read, so the response is a PROJECTION built by\n * `toStorefrontPurchaseSource`, never the order document: no email, no name,\n * no shipping or billing address, and not our `feeCents` either. A buyer\n * learns only what they themselves just bought.\n *\n * ## The webhook race\n *\n * The shopper can return from Stripe before the `checkout.session.completed`\n * delivery has been processed, in which case the order does not exist yet.\n * That is answered with 404 and a `retryable` flag rather than a synthesised\n * order — the client polls briefly. Reporting a purchase we cannot yet read\n * would mean inventing the value.\n *\n * Never cached: an order that 404s during the race must not have that 404\n * stored in front of it, which is the AGL negative-cache shape that has bitten\n * host lookups before.\n *\n * ## Subscriptions answer from the INVOICE, not from an order (AGL-1746)\n *\n * A subscription sale writes no order document — deliberately, on three\n * independent pieces of evidence gathered in AGL-1732 — so the lookup above\n * missed forever on every one of them. The merchant's own GA4 property\n * therefore showed traffic and `begin_checkout` for the subscription product\n * and then no `purchase` at all, which does not read as \"we do not measure\n * this\": it reads as a 100% checkout abandonment rate on the product, an\n * authoritative-looking number that is wrong.\n *\n * The data to answer with exists now. AGL-1732 records the sale on\n * `subscriptions/{stripeSubscriptionId}` carrying the originating\n * `checkoutSessionId`, and AGL-1743 records every paid invoice beneath it,\n * including the opening one — kept explicitly so the ledger has no hole where\n * cycle 1 belongs, even though that cycle is deliberately not re-counted into\n * lifetime value.\n *\n * The opening INVOICE is what answers, for two reasons:\n *\n * - Its id is a natural `transaction_id`. It is Stripe's own id for the money\n *   that moved, it is unique per cycle, and it is stable — the same sale\n *   resolves to the same invoice on every poll, so a shopper who refreshes the\n *   return page cannot produce a second `purchase` under a different id. GA4\n *   de-duplicates on `transaction_id`, and that only protects us if the id is\n *   deterministic.\n * - Its `lineItems` and `totals` were built by\n *   `computeSubscriptionInvoiceOrder`, which is the helper that knows an\n *   invoice is NOT a Checkout Session: AGL-1743 found invoices carry no\n *   `total_details` whatsoever, that tax is `tax` or `total_taxes` by API\n *   version, discount is `total_discount_amounts[]`, and the fee is a real\n *   `application_fee_amount`. Reading the stored figures means this route\n *   inherits all of that instead of re-deriving it against the wrong shape.\n *\n * `value` needs no special-casing here, and that is the point of answering in\n * the same wire shape: `toStorefrontPurchaseSource` and\n * `buildStorefrontPurchaseParams` already implement the AGL-1641 storefront\n * rule, which is the INVERSE of the marketplace one. On a tenant storefront\n * the MERCHANT is the seller, so Aglyn's fee is their cost of sale rather than\n * a deduction from it and is NOT subtracted; tax is money held for the state\n * and is excluded, with no GA4 `tax` param sent beside an ex-tax `value`.\n * Getting that backwards would show every merchant a figure a few percent of\n * their real revenue.\n *\n * ## Renewals do NOT send a `purchase` — and could not\n *\n * A recurring revenue event per cycle is arguable on the merits, and the\n * argument against it on the merits is real: `purchase` is what GA4's\n * acquisition and ROAS reporting is terminated by, so firing one every month\n * would credit a single acquisition to its campaign twelve times over and\n * inflate return on ad spend by the subscriber's whole lifetime.\n *\n * But it does not come down to that, because this seam cannot carry a renewal\n * at all. This purchase is CLIENT-side by design: the hit is sent by\n * `use-storefront-purchase-event.ts` through the merchant's own `gtag`, loaded\n * with `host.analytics.gaMeasurementId`. A renewal happens months later with\n * no browser anywhere in it. Sending one would require the Measurement\n * Protocol against the merchant's property, which needs a per-host API secret\n * that this product does not collect and has nowhere to store — the same\n * conclusion `use-storefront-purchase-event.ts` reached from the other\n * direction. `ga4-measurement-protocol.ts` is not that channel: it holds one\n * global `GA4_MEASUREMENT_ID`/`GA4_API_SECRET` pair, which is AGLYN's property\n * and reports our revenue, not the merchant's.\n *\n * So the storefront reports the subscription's FIRST payment, once, and stops\n * — mirroring AGL-1743's own decision not to re-count the opening invoice\n * anywhere the checkout session had already been counted.\n *\n * ## Why both lookups run\n *\n * A Checkout Session id does not say whether it was a one-time or a\n * subscription mode session, so a miss on the order genuinely might be either\n * the webhook race or a subscription. The subscription lookups therefore run\n * on every order miss. Both are single-field equality queries with `limit(1)`,\n * which Firestore serves from the automatic single-field indexes it maintains\n * for every field — there is no composite index here to create, and none to\n * probe.\n */\nexport const orderAnalyticsHandler: PluginApiHandler = async (req, res) => {\n  const hostId = String(req.query.hostId ?? '')\n  const sessionId = String(req.query.sessionId ?? '')\n  if (!hostId || !sessionId) {\n    return res.status(400).json({ error: 'Missing hostId or sessionId' })\n  }\n  // Shape-checked before it reaches Firestore: a document id is a path\n  // segment, and an unvalidated one is how a lookup becomes a traversal.\n  if (!SESSION_ID.test(sessionId)) {\n    return res.status(400).json({ error: 'Invalid sessionId' })\n  }\n  // A REHEARSAL MUST NOT REACH THE MERCHANT'S OWN ANALYTICS.\n  //\n  // This endpoint hands the browser a `purchase` payload that\n  // `use-storefront-purchase-event.ts` pushes through the MERCHANT's `gtag`,\n  // into the MERCHANT's GA4 property. A smoke-test checkout therefore writes a\n  // fake sale into a real merchant's funnel — the same pollution as the\n  // revenue cards, except it lands somewhere Aglyn does not control and\n  // cannot later correct.\n  //\n  // Refused HERE rather than at the webhook, because this is not a webhook.\n  // The billing route's AGL-2040 livemode gate already refuses cross-mode\n  // events, so every per-sale effect driven by it — the buyer receipt, the\n  // merchant notification, the dropship purchase order — is covered. This\n  // route is a plain GET the storefront calls on its own success page, so it\n  // reads an order that already exists and is reached by no gate at all.\n  //\n  // The SESSION ID is the discriminator and it covers both branches below: a\n  // Checkout Session id states its mode (`cs_test_…`), while the invoice id\n  // the subscription branch reports on does NOT, so checking the invoice\n  // would miss every recurring sale.\n  //\n  // 409, matching the \"Not payable\" refusals below: the client retries only a\n  // 404 and treats everything else as terminal, so this fires nothing and\n  // polls nothing.\n  //\n  // FAILING TOWARDS FIRING. An unrecognised id is live: suppressing a real\n  // sale would corrupt a merchant's funnel in the one direction they can\n  // never spot, exactly as counting one would corrupt their revenue.\n  if (stripeIdIsTestMode(sessionId)) {\n    return res.status(409).json({ error: 'Not payable', reason: 'test-mode' })\n  }\n  try {\n    const hostRef = firebaseAdmin\n      .app()\n      .firestore()\n      .collection('hosts')\n      .doc(hostId)\n    const snapshot = await hostRef.collection('orders').doc(sessionId).get()\n\n    res.setHeader('Cache-Control', 'no-store')\n\n    if (snapshot.exists) {\n      const order = (snapshot.data() ?? {}) as any\n      // Only a PAID order is a purchase. A session can be written in another\n      // state by the draft/POS paths, and reporting one as revenue would put a\n      // sale in the merchant's report that has not happened.\n      if (order.status !== 'paid') {\n        return res.status(409).json({ error: 'Not payable' })\n      }\n      // The RECORDED fact as well as the id. An order the webhook\n      // stamped `livemode: false` is a rehearsal whatever its id looks like,\n      // and this is the stronger of the two signals.\n      if (CommerceModel.orderIsTestMode({ ...order, $id: snapshot.id })) {\n        return res.status(409).json({ error: 'Not payable', reason: 'test-mode' })\n      }\n      return res\n        .status(200)\n        .json(toStorefrontPurchaseSource(snapshot.id, order))\n    }\n\n    // No order. That is either the webhook race above, or a SUBSCRIPTION sale,\n    // which records no order at all (AGL-1746). The subscription carries the\n    // session that created it.\n    const subscriptions = await hostRef\n      .collection('subscriptions')\n      .where('checkoutSessionId', '==', sessionId)\n      .limit(1)\n      .get()\n    const subscription = subscriptions.docs[0]\n    if (!subscription) {\n      // Retryable: the race, or an id that was never ours.\n      return res.status(404).json({ error: 'Not found', retryable: true })\n    }\n    // The money, rather than the sale record: the opening invoice is what was\n    // actually collected, and its id is the transaction id.\n    const invoices = await subscription.ref\n      .collection('invoices')\n      .where('billingReason', '==', OPENING_INVOICE_REASON)\n      .limit(1)\n      .get()\n    const invoice = invoices.docs[0]\n    if (!invoice) {\n      // `checkout.session.completed` has landed and `invoice.paid` has not —\n      // still the race, one webhook further along.\n      return res.status(404).json({ error: 'Not found', retryable: true })\n    }\n    // A TRIAL opens on a $0 invoice. Nothing was charged, so there is no\n    // revenue to report; this is the subscription's form of \"not payable\", and\n    // it is terminal rather than retryable because it will never become true\n    // for THIS invoice.\n    if (!(Number(invoice.get('paidCents') ?? 0) > 0)) {\n      return res.status(409).json({ error: 'Not payable' })\n    }\n    return res\n      .status(200)\n      .json(\n        toStorefrontPurchaseSource(invoice.id, (invoice.data() ?? {}) as any),\n      )\n  } catch (error) {\n    console.error(error)\n    return res.status(500).json({ error: 'Lookup failed' })\n  }\n}\n"],"names":["stripeIdIsTestMode","CommerceModel","firebaseAdmin","toStorefrontPurchaseSource","SESSION_ID","OPENING_INVOICE_REASON","orderAnalyticsHandler","req","res","hostId","String","query","sessionId","status","json","error","test","reason","invoice","hostRef","app","firestore","collection","doc","snapshot","get","setHeader","exists","order","data","orderIsTestMode","$id","id","subscriptions","where","limit","subscription","docs","retryable","invoices","ref","Number","console"],"mappings":"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"}

package/src/lib/server/order-figures.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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 PluginFigureReader } from '@aglyn/aglyn/plugin-manager/plugin-figures';
+/**
+ * The store's sales figures for another plugin to read (AGL-2915): what the
+ * Analytics tab's card shows, as tables on the `plugin-figures` seam. The
+ * insight job reads them by id and never reads an order.
+ *
+ * A table carries sums and counts and product names — never a buyer, an
+ * address or an order. Sold under `commerceAnalytics`, the entitlement the
+ * card is sold under.
+ */
+type Firestore = FirebaseFirestore.Firestore;
+/** Orders one window reads; a store past it is told its figures read low. */
+export declare const ORDER_FIGURES_WINDOW_CEILING = 1000;
+export declare function orderFigureReaders(firestore: () => Firestore): PluginFigureReader[];
+/** Registers the sales readers from the console surface, where insight jobs run. */
+export declare function registerOrderFigureReaders(firestore: () => Firestore): void;
+export {};