@aglyn/plugins-commerce 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/server/api-v1/orders-and-products.js

@@ -0,0 +1,419 @@
+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 { checkEntitlement, isHostPluginEnabled } from "@aglyn/aglyn/server";
+import { ApiErrors, apiJson, listResponse } from "@aglyn/tenant-data-admin";
+import { paginate, readJsonBody, requireScope, serialize } from "@aglyn/tenant-data-admin/server/api-v1-kit";
+import { BUNDLE_ID } from "../../constants/bundle-common.js";
+import { recordOrderShipment } from "../fulfill-order.js";
+/**
+ * A site's orders and products on the customer REST API,
+ * `/v1/sites/{siteId}/orders/…` and `/v1/sites/{siteId}/products/…`
+ * (AGL-1928, AGL-2461, AGL-3080). Registered from this plugin's console
+ * server declarations; the console's `/v1` router owns the pipeline in
+ * front — the key, the plan's API access, the request quota, the rate limit —
+ * and refuses a site the key's organization does not own before it hands a
+ * request here.
+ */ /**
+ * Commerce resources need the `commerce` entitlement as well as the scope
+ * (AGL-1928). `apiAccess` alone is the wrong gate here: it says the org may
+ * call the API at all, not that it may still use the store. AGL-1873 closed
+ * exactly this class on the write side — two money doors that asked the
+ * plugin switch (`org.enabledPlugins`) instead of the plan, so a lapsed org
+ * kept selling — and the same reasoning applies to a read. `enabledPlugins`
+ * is the customer's own on/off switch and survives a downgrade; the plan does
+ * not, and the published rule is that paid features stop at the door when the
+ * plan no longer includes them.
+ *
+ * Answered as `plan_required` rather than `not_found`, deliberately. Hiding a
+ * store that plainly exists behind a 404 sends an integrator hunting a wrong
+ * site id; the honest answer names the plan.
+ */ function requireCommerce(ctx) {
+    return checkEntitlement(ctx.org, 'commerce') ? null : ApiErrors.planRequired({
+        message: 'Commerce is not included in this organization’s plan',
+        code: 'commerce',
+        headers: ctx.headers
+    });
+}
+function hostRef(ctx, hostId) {
+    return ctx.firestore.collection('hosts').doc(hostId);
+}
+/**
+ * Orders carry a legacy Commerce Starter shape (AGL-90) alongside the modern
+ * one: `amountCents`/`feeCents` at the top level rather than a `totals` map.
+ * The console lifts them through `CommerceModel.liftLegacyOrder` and reads
+ * `lifted.totals?.totalCents ?? order.amountCents`. The API cannot publish two
+ * shapes for one object, so the legacy fields are folded into `totals` here
+ * and a client only ever sees the modern one. `channel` defaults to `online`
+ * for the same reason the console's list does — an absent channel is a
+ * pre-channel order, not an unknown one.
+ */ function orderView(doc) {
+    var _doc_data, _data_totals, _data_amountCents, _data_feeCents, _data_status, _data_channel, _data_customerEmail, _data_customerName, _data_lineItems, _totals_itemsCents, _totals_shippingCents, _totals_taxCents, _totals_discountCents, _data_refundedCents, _serialize, _data_couponCode, _serialize1;
+    const data = (_doc_data = doc.data()) != null ? _doc_data : {};
+    const totals = (_data_totals = data.totals) != null ? _data_totals : {};
+    const legacyTotal = Number((_data_amountCents = data.amountCents) != null ? _data_amountCents : NaN);
+    const totalCents = Number.isFinite(Number(totals.totalCents)) ? Number(totals.totalCents) : Number.isFinite(legacyTotal) ? legacyTotal : null;
+    const legacyFee = Number((_data_feeCents = data.feeCents) != null ? _data_feeCents : NaN);
+    return {
+        id: doc.id,
+        object: 'order',
+        number: typeof data.number === 'number' ? data.number : null,
+        status: (_data_status = data.status) != null ? _data_status : null,
+        channel: (_data_channel = data.channel) != null ? _data_channel : 'online',
+        currency: 'usd',
+        customerEmail: (_data_customerEmail = data.customerEmail) != null ? _data_customerEmail : null,
+        customerName: (_data_customerName = data.customerName) != null ? _data_customerName : null,
+        lineItems: serialize((_data_lineItems = data.lineItems) != null ? _data_lineItems : []),
+        totals: {
+            itemsCents: Number((_totals_itemsCents = totals.itemsCents) != null ? _totals_itemsCents : 0),
+            shippingCents: Number((_totals_shippingCents = totals.shippingCents) != null ? _totals_shippingCents : 0),
+            taxCents: Number((_totals_taxCents = totals.taxCents) != null ? _totals_taxCents : 0),
+            discountCents: Number((_totals_discountCents = totals.discountCents) != null ? _totals_discountCents : 0),
+            totalCents,
+            // The Connect application fee. NOT subtracted from `totalCents` — it is
+            // Aglyn's cut of a total the shopper already paid in full, so a client
+            // that nets it out of revenue would understate what it collected.
+            feeCents: Number.isFinite(Number(totals.feeCents)) ? Number(totals.feeCents) : Number.isFinite(legacyFee) ? legacyFee : 0
+        },
+        // Money already handed back, for any reason. A chargeback lands here too,
+        // so `refundedCents > 0` does not by itself mean the merchant chose it.
+        refundedCents: Number((_data_refundedCents = data.refundedCents) != null ? _data_refundedCents : 0),
+        disputed: Boolean(data.dispute),
+        shippingAddress: (_serialize = serialize(data.shippingAddress)) != null ? _serialize : null,
+        couponCode: (_data_couponCode = data.couponCode) != null ? _data_couponCode : null,
+        // Shipment records — the half of fulfilment an integration can use
+        // without a write (AGL-2460). `status` says an order is `fulfilled`; it
+        // does not say which carrier took it or under what tracking number, so a
+        // 3PL or accounting reconcile could see THAT an order shipped and never
+        // WHICH shipment it was. The console's order dialog shows both, and an
+        // order that has been shipped twice (a split shipment) is indistinguish-
+        // able from one shipped once when only the status is published.
+        //
+        // `atMs` is a number of milliseconds, not a Firestore Timestamp, so
+        // `serialize` passes it through untouched. It is republished as `at` in
+        // ISO 8601 to match `created` and every other time this API emits: one
+        // object publishing two time formats is a bug an integrator finds late,
+        // in their own timezone conversion, and blames on their own code.
+        fulfillments: (Array.isArray(data.fulfillments) ? data.fulfillments : []).map((entry)=>{
+            var _id, _carrier, _trackingNumber, _trackingUrl;
+            const atMs = Number((entry != null ? entry : {}).atMs);
+            return {
+                id: (_id = (entry != null ? entry : {}).id) != null ? _id : null,
+                lineItemIds: Array.isArray((entry != null ? entry : {}).lineItemIds) ? entry.lineItemIds : [],
+                carrier: (_carrier = (entry != null ? entry : {}).carrier) != null ? _carrier : null,
+                trackingNumber: (_trackingNumber = (entry != null ? entry : {}).trackingNumber) != null ? _trackingNumber : null,
+                trackingUrl: (_trackingUrl = (entry != null ? entry : {}).trackingUrl) != null ? _trackingUrl : null,
+                at: Number.isFinite(atMs) ? new Date(atMs).toISOString() : null
+            };
+        }),
+        created: (_serialize1 = serialize(data.createdAt)) != null ? _serialize1 : null
+    };
+}
+export async function handleOrders(request, ctx, segments, url) {
+    const [, hostId, , orderId] = segments;
+    // `orders:write` is checked BEFORE `orders:read`, matching `handleSites`
+    // and `handleScopedMedia` (AGL-900): a fulfilment key that only records
+    // shipments must not be told it lacks a read scope it was never meant to
+    // hold.
+    if (request.method === 'PATCH' && orderId) {
+        const deniedWrite = requireScope(ctx, 'orders:write');
+        if (deniedWrite) return deniedWrite;
+        const unentitledWrite = requireCommerce(ctx);
+        if (unentitledWrite) return unentitledWrite;
+        return updateOrder(request, ctx, hostId, orderId);
+    }
+    const denied = requireScope(ctx, 'orders:read');
+    if (denied) return denied;
+    const unentitled = requireCommerce(ctx);
+    if (unentitled) return unentitled;
+    if (request.method !== 'GET') {
+        return ApiErrors.methodNotAllowed({
+            headers: _extends({}, ctx.headers, {
+                Allow: orderId ? 'GET, PATCH' : 'GET'
+            })
+        });
+    }
+    const collection = hostRef(ctx, hostId).collection('orders');
+    if (orderId) {
+        const snap = await collection.doc(orderId).get();
+        if (!snap.exists) {
+            return ApiErrors.notFound({
+                message: 'No such order',
+                headers: ctx.headers
+            });
+        }
+        return apiJson(orderView(snap), {
+            headers: ctx.headers
+        });
+    }
+    let query = collection;
+    const status = url.searchParams.get('status');
+    if (status) query = query.where('status', '==', status);
+    const channel = url.searchParams.get('channel');
+    // `online` is the DEFAULT, not a stored value on older orders, so filtering
+    // for it in Firestore would silently drop every pre-channel order. Those are
+    // exactly the oldest orders an accounting backfill is reaching for, so this
+    // one value is filtered after the read instead. The page can therefore come
+    // back shorter than `limit` while `has_more` is still true — which the
+    // published pagination contract already tells clients to expect (check
+    // `has_more`, never a page's length).
+    if (channel && channel !== 'online') query = query.where('channel', '==', channel);
+    const { docs, nextCursor } = await paginate(query, url);
+    const data = docs.map(orderView).filter((order)=>channel === 'online' ? order.channel === 'online' : true);
+    return listResponse(data, nextCursor, ctx.headers);
+}
+/**
+ * Statuses this endpoint will move an order TO, and the two it names as
+ * refused. Kept as data so the 400 can list them and the docs can be checked
+ * against the same source the handler branches on.
+ */ const ORDER_WRITE_TARGETS = [
+    'fulfilled',
+    'delivered'
+];
+/**
+ * Transitions that exist in the commerce model and are DELIBERATELY not
+ * reachable here — refused by name with a 400 that says why, never silently
+ * ignored. `cancelled` releases held stock under its own transaction and
+ * `refunded` moves money under another; admitting either here would hand a
+ * caller a door around exactly the specifics those two routes exist to
+ * enforce, and an API key is the credential least able to answer the
+ * questions they ask.
+ */ const ORDER_WRITE_REFUSED = {
+    cancelled: 'Canceling an order releases held stock, so it is not part of this endpoint. Cancel it in the console.',
+    refunded: 'Refunding an order moves money, so it is not part of this endpoint. Refund it in the console.'
+};
+/**
+ * `PATCH /v1/sites/{siteId}/orders/{orderId}` — record a shipment (AGL-2461).
+ *
+ * ## The write is the console's, shared
+ *
+ * The transition rule, the transaction that re-asks it under the write, the
+ * fulfillment append and the timeline entry are `recordOrderShipment`'s,
+ * the one implementation the console's `commerce/fulfill-order` route calls
+ * too. A second copy of `ORDER_TRANSITIONS` here would be the bug rather
+ * than the fix: two tables drift, and drift here means the API writing an
+ * order status the console forbids — `paid → delivered` skipping
+ * fulfilment, or a write onto a `refunded` order. That is the class
+ * AGL-1818/AGL-1819 exist to close, and it is money-adjacent.
+ *
+ * ## What THIS function is responsible for: all of the authorization
+ *
+ * `recordOrderShipment` is pre-authorized by contract — it takes `hostId`
+ * on trust — so every gate is here, and all four are load-bearing:
+ *
+ * 1. `orders:write` on the key (checked by the caller, above).
+ * 2. The `commerce` PLAN entitlement (checked by the caller, above) — the
+ *    plan, never the plugin switch, which is the AGL-1873 distinction.
+ * 3. **Org owns the site** — the console's `handleSites` refuses an unowned
+ *    `hostId` with a 404 before it hands any site resource to its plugin,
+ *    which is what keeps this from being a cross-tenant write primitive
+ *    addressable by anyone who can guess a host id. Deliberately NOT
+ *    re-checked here: a second copy would be a gate no test can redden
+ *    (removing either one alone leaves the other answering), and an unproven
+ *    guard on a cross-tenant write is worse than the one guard a test
+ *    actually holds. `api-v1-order-fulfilment.spec.ts`'s "CANNOT move
+ *    another org's order" case is that test, and it fails when
+ *    `handleSites`' `orgOwnsHost` is removed.
+ * 4. **This plugin is switched on for this site.** The resource is
+ *    registered for every organization the console serves, so its being here
+ *    says nothing about one org's configuration; without this an org that
+ *    switched commerce off for a site would still accept writes into it,
+ *    which is the per-site enablement rule (AGL-1014) the plugin API
+ *    dispatcher applies to every other commerce door.
+ *
+ * ## No `Idempotency-Key`
+ *
+ * None is needed and none is accepted: the write returns without writing when
+ * the order is already in the target status, so a retry lands the same state
+ * AND returns the same `200` with the same order body — the contract
+ * `updateRecord`, `updateContact` and `updateFormSubmission` are held to.
+ */ async function updateOrder(request, ctx, hostId, orderId) {
+    var _body_status, _body_carrier, _body_trackingNumber;
+    const body = await readJsonBody(request);
+    const unknown = Object.keys(body).filter((key)=>key !== 'status' && key !== 'carrier' && key !== 'trackingNumber');
+    if (unknown.length > 0) {
+        // Named, not dropped — the `updateFormSubmission` / `updateContact` rule.
+        // A silently ignored `trackingUrl` here reads as "we recorded your
+        // shipment as you described it" when half of it went nowhere, and the
+        // caller is a warehouse system that will never look again.
+        return ApiErrors.badRequest({
+            message: 'Only `status`, `carrier` and `trackingNumber` can be set on an order',
+            code: 'validation_failed',
+            fields: Object.fromEntries(unknown.map((key)=>[
+                    key,
+                    'Not writable on an order'
+                ])),
+            headers: ctx.headers
+        });
+    }
+    const status = String((_body_status = body.status) != null ? _body_status : '');
+    const refusal = ORDER_WRITE_REFUSED[status];
+    if (refusal) {
+        return ApiErrors.badRequest({
+            message: refusal,
+            code: 'validation_failed',
+            fields: {
+                status: refusal
+            },
+            headers: ctx.headers
+        });
+    }
+    if (!ORDER_WRITE_TARGETS.includes(status)) {
+        return ApiErrors.badRequest({
+            message: 'Order failed validation',
+            code: 'validation_failed',
+            fields: {
+                status: `Must be one of: ${ORDER_WRITE_TARGETS.join(', ')}`
+            },
+            headers: ctx.headers
+        });
+    }
+    // Bounded exactly as the console route bounds them, so one field cannot be
+    // used to stuff an order document through a door the console keeps narrow.
+    const carrier = String((_body_carrier = body.carrier) != null ? _body_carrier : '').slice(0, 40);
+    const trackingNumber = String((_body_trackingNumber = body.trackingNumber) != null ? _body_trackingNumber : '').slice(0, 60);
+    // Gate 4: this plugin, on for this site.
+    const hostSnap = await hostRef(ctx, hostId).get();
+    if (!isHostPluginEnabled(ctx.org, hostSnap.data(), BUNDLE_ID)) {
+        return ApiErrors.notFound({
+            message: 'No such site',
+            headers: ctx.headers
+        });
+    }
+    const outcome = await recordOrderShipment({
+        hostId,
+        orderId,
+        to: status,
+        carrier,
+        trackingNumber
+    });
+    if (outcome.outcome === 'no_such_order') {
+        return ApiErrors.notFound({
+            message: 'No such order',
+            headers: ctx.headers
+        });
+    }
+    if (outcome.outcome === 'blocked') {
+        // A NEW 409 code (`order_transition`), because an integrator has to be
+        // able to tell "the order moved on without me" apart from every other
+        // conflict this API can raise — it is the one a fulfilment poller will
+        // actually hit, and the one it must not retry forever.
+        return ApiErrors.conflict({
+            message: `Orders in "${outcome.from}" cannot be marked ${status}`,
+            code: 'order_transition',
+            headers: ctx.headers
+        });
+    }
+    // The order object, on both `recorded` and `already` — a retry lands the
+    // same state and reads the same 200. Re-read after the write so the body
+    // shows the shipment that was just recorded rather than the one before it.
+    return apiJson(orderView(await hostRef(ctx, hostId).collection('orders').doc(orderId).get()), {
+        headers: ctx.headers
+    });
+}
+/**
+ * Price and stock live on VARIANTS, never on the product — a product-level
+ * `inventory` exists only as a denormalized sum the console rewrites on every
+ * decrement, and a product-level `priceUsd` is the legacy single-variant
+ * shape. Publishing either as the product's price would be wrong the moment a
+ * product has two variants, so the variant array is the contract and the
+ * product carries only the roll-up, clearly named.
+ *
+ * `inventory: null` on a variant means UNTRACKED and `0` means SOLD OUT.
+ * Collapsing them (the `?? 0` an integrator writes on the first day) turns
+ * every untracked product into an out-of-stock one, so the distinction is
+ * carried through verbatim rather than defaulted.
+ */ function variantView(variant) {
+    var _variant_id, _variant_sku, _variant_barcode, _variant_options;
+    const inventory = variant.inventory;
+    return {
+        id: (_variant_id = variant.id) != null ? _variant_id : null,
+        sku: (_variant_sku = variant.sku) != null ? _variant_sku : null,
+        barcode: (_variant_barcode = variant.barcode) != null ? _variant_barcode : null,
+        options: (_variant_options = variant.options) != null ? _variant_options : {},
+        priceUsd: typeof variant.priceUsd === 'number' ? variant.priceUsd : null,
+        compareAtPriceUsd: typeof variant.compareAtPriceUsd === 'number' ? variant.compareAtPriceUsd : null,
+        weightGrams: typeof variant.weightGrams === 'number' ? variant.weightGrams : null,
+        inventory: typeof inventory === 'number' ? inventory : null,
+        inventoryTracked: typeof inventory === 'number'
+    };
+}
+function productView(doc) {
+    var _doc_data, _data_name, _data_slug, _data_description, _data_type, _data_status, _data_tags, _data_categoryIds, _data_mediaUrls, _data_options, _serialize;
+    const data = (_doc_data = doc.data()) != null ? _doc_data : {};
+    const variants = Array.isArray(data.variants) ? data.variants : [];
+    const tracked = variants.filter((v)=>typeof v.inventory === 'number');
+    return {
+        id: doc.id,
+        object: 'product',
+        name: (_data_name = data.name) != null ? _data_name : null,
+        slug: (_data_slug = data.slug) != null ? _data_slug : null,
+        description: (_data_description = data.description) != null ? _data_description : null,
+        type: (_data_type = data.type) != null ? _data_type : null,
+        status: (_data_status = data.status) != null ? _data_status : null,
+        tags: (_data_tags = data.tags) != null ? _data_tags : [],
+        categoryIds: (_data_categoryIds = data.categoryIds) != null ? _data_categoryIds : [],
+        mediaUrls: (_data_mediaUrls = data.mediaUrls) != null ? _data_mediaUrls : [],
+        options: (_data_options = data.options) != null ? _data_options : [],
+        variants: variants.map(variantView),
+        // The sum across TRACKED variants only, and `null` when none of them is
+        // tracked — so an untracked catalogue reads as "we don't count this"
+        // rather than as a store with nothing left to sell.
+        inventory: tracked.length ? tracked.reduce((sum, v)=>{
+            var _v_inventory;
+            return sum + Number((_v_inventory = v.inventory) != null ? _v_inventory : 0);
+        }, 0) : null,
+        subscription: (_serialize = serialize(data.subscription)) != null ? _serialize : null,
+        created: data.createdAtMs ? new Date(Number(data.createdAtMs)).toISOString() : null,
+        updated: data.updatedAtMs ? new Date(Number(data.updatedAtMs)).toISOString() : null
+    };
+}
+export async function handleProducts(request, ctx, segments, url) {
+    const [, hostId, , productId] = segments;
+    const denied = requireScope(ctx, 'products:read');
+    if (denied) return denied;
+    const unentitled = requireCommerce(ctx);
+    if (unentitled) return unentitled;
+    if (request.method !== 'GET') {
+        return ApiErrors.methodNotAllowed({
+            headers: ctx.headers
+        });
+    }
+    const collection = hostRef(ctx, hostId).collection('products');
+    if (productId) {
+        const snap = await collection.doc(productId).get();
+        // A soft-deleted product is gone as far as a customer is concerned. The
+        // console filters `deletedAt` client-side; the API must not hand back a
+        // product the merchant deleted just because the document survives.
+        if (!snap.exists || snap.get('deletedAt')) {
+            return ApiErrors.notFound({
+                message: 'No such product',
+                headers: ctx.headers
+            });
+        }
+        return apiJson(productView(snap), {
+            headers: ctx.headers
+        });
+    }
+    let query = collection;
+    const status = url.searchParams.get('status');
+    if (status) query = query.where('status', '==', status);
+    const { docs, nextCursor } = await paginate(query, url);
+    const data = docs.filter((doc)=>!doc.get('deletedAt')).map(productView);
+    return listResponse(data, nextCursor, ctx.headers);
+}
+
+//# sourceMappingURL=orders-and-products.js.map

package/src/lib/server/api-v1/orders-and-products.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/plugins/commerce/src/lib/server/api-v1/orders-and-products.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 { checkEntitlement, isHostPluginEnabled } from '@aglyn/aglyn/server'\nimport {\n  ApiErrors,\n  apiJson,\n  listResponse,\n} from '@aglyn/tenant-data-admin'\nimport {\n  type ApiV1Context,\n  paginate,\n  readJsonBody,\n  requireScope,\n  serialize,\n} from '@aglyn/tenant-data-admin/server/api-v1-kit'\nimport { BUNDLE_ID } from '../../constants/bundle-common'\nimport { type OrderFulfilmentTarget, recordOrderShipment } from '../fulfill-order'\n\n/**\n * A site's orders and products on the customer REST API,\n * `/v1/sites/{siteId}/orders/…` and `/v1/sites/{siteId}/products/…`\n * (AGL-1928, AGL-2461, AGL-3080). Registered from this plugin's console\n * server declarations; the console's `/v1` router owns the pipeline in\n * front — the key, the plan's API access, the request quota, the rate limit —\n * and refuses a site the key's organization does not own before it hands a\n * request here.\n */\n\n/**\n * Commerce resources need the `commerce` entitlement as well as the scope\n * (AGL-1928). `apiAccess` alone is the wrong gate here: it says the org may\n * call the API at all, not that it may still use the store. AGL-1873 closed\n * exactly this class on the write side — two money doors that asked the\n * plugin switch (`org.enabledPlugins`) instead of the plan, so a lapsed org\n * kept selling — and the same reasoning applies to a read. `enabledPlugins`\n * is the customer's own on/off switch and survives a downgrade; the plan does\n * not, and the published rule is that paid features stop at the door when the\n * plan no longer includes them.\n *\n * Answered as `plan_required` rather than `not_found`, deliberately. Hiding a\n * store that plainly exists behind a 404 sends an integrator hunting a wrong\n * site id; the honest answer names the plan.\n */\nfunction requireCommerce(ctx: ApiV1Context): Response | null {\n  return checkEntitlement(ctx.org, 'commerce')\n    ? null\n    : ApiErrors.planRequired({\n        message: 'Commerce is not included in this organization’s plan',\n        code: 'commerce',\n        headers: ctx.headers,\n      })\n}\n\nfunction hostRef(ctx: ApiV1Context, hostId: string) {\n  return ctx.firestore.collection('hosts').doc(hostId)\n}\n\n/**\n * Orders carry a legacy Commerce Starter shape (AGL-90) alongside the modern\n * one: `amountCents`/`feeCents` at the top level rather than a `totals` map.\n * The console lifts them through `CommerceModel.liftLegacyOrder` and reads\n * `lifted.totals?.totalCents ?? order.amountCents`. The API cannot publish two\n * shapes for one object, so the legacy fields are folded into `totals` here\n * and a client only ever sees the modern one. `channel` defaults to `online`\n * for the same reason the console's list does — an absent channel is a\n * pre-channel order, not an unknown one.\n */\nfunction orderView(doc: FirebaseFirestore.DocumentSnapshot) {\n  const data = doc.data() ?? {}\n  const totals = (data.totals ?? {}) as Record<string, unknown>\n  const legacyTotal = Number(data.amountCents ?? NaN)\n  const totalCents = Number.isFinite(Number(totals.totalCents))\n    ? Number(totals.totalCents)\n    : Number.isFinite(legacyTotal)\n      ? legacyTotal\n      : null\n  const legacyFee = Number(data.feeCents ?? NaN)\n  return {\n    id: doc.id,\n    object: 'order',\n    number: typeof data.number === 'number' ? data.number : null,\n    status: (data.status as string) ?? null,\n    channel: (data.channel as string) ?? 'online',\n    currency: 'usd',\n    customerEmail: data.customerEmail ?? null,\n    customerName: data.customerName ?? null,\n    lineItems: serialize(data.lineItems ?? []),\n    totals: {\n      itemsCents: Number(totals.itemsCents ?? 0),\n      shippingCents: Number(totals.shippingCents ?? 0),\n      taxCents: Number(totals.taxCents ?? 0),\n      discountCents: Number(totals.discountCents ?? 0),\n      totalCents,\n      // The Connect application fee. NOT subtracted from `totalCents` — it is\n      // Aglyn's cut of a total the shopper already paid in full, so a client\n      // that nets it out of revenue would understate what it collected.\n      feeCents: Number.isFinite(Number(totals.feeCents))\n        ? Number(totals.feeCents)\n        : Number.isFinite(legacyFee)\n          ? legacyFee\n          : 0,\n    },\n    // Money already handed back, for any reason. A chargeback lands here too,\n    // so `refundedCents > 0` does not by itself mean the merchant chose it.\n    refundedCents: Number(data.refundedCents ?? 0),\n    disputed: Boolean(data.dispute),\n    shippingAddress: serialize(data.shippingAddress) ?? null,\n    couponCode: data.couponCode ?? null,\n    // Shipment records — the half of fulfilment an integration can use\n    // without a write (AGL-2460). `status` says an order is `fulfilled`; it\n    // does not say which carrier took it or under what tracking number, so a\n    // 3PL or accounting reconcile could see THAT an order shipped and never\n    // WHICH shipment it was. The console's order dialog shows both, and an\n    // order that has been shipped twice (a split shipment) is indistinguish-\n    // able from one shipped once when only the status is published.\n    //\n    // `atMs` is a number of milliseconds, not a Firestore Timestamp, so\n    // `serialize` passes it through untouched. It is republished as `at` in\n    // ISO 8601 to match `created` and every other time this API emits: one\n    // object publishing two time formats is a bug an integrator finds late,\n    // in their own timezone conversion, and blames on their own code.\n    fulfillments: (Array.isArray(data.fulfillments) ? data.fulfillments : []).map(\n      (entry: Record<string, unknown>) => {\n        const atMs = Number((entry ?? {}).atMs)\n        return {\n          id: (entry ?? {}).id ?? null,\n          lineItemIds: Array.isArray((entry ?? {}).lineItemIds)\n            ? (entry as { lineItemIds: unknown[] }).lineItemIds\n            : [],\n          carrier: (entry ?? {}).carrier ?? null,\n          trackingNumber: (entry ?? {}).trackingNumber ?? null,\n          trackingUrl: (entry ?? {}).trackingUrl ?? null,\n          at: Number.isFinite(atMs) ? new Date(atMs).toISOString() : null,\n        }\n      },\n    ),\n    created: serialize(data.createdAt) ?? null,\n  }\n}\n\nexport async function handleOrders(\n  request: Request,\n  ctx: ApiV1Context,\n  segments: string[],\n  url: URL,\n): Promise<Response> {\n  const [, hostId, , orderId] = segments\n  // `orders:write` is checked BEFORE `orders:read`, matching `handleSites`\n  // and `handleScopedMedia` (AGL-900): a fulfilment key that only records\n  // shipments must not be told it lacks a read scope it was never meant to\n  // hold.\n  if (request.method === 'PATCH' && orderId) {\n    const deniedWrite = requireScope(ctx, 'orders:write')\n    if (deniedWrite) return deniedWrite\n    const unentitledWrite = requireCommerce(ctx)\n    if (unentitledWrite) return unentitledWrite\n    return updateOrder(request, ctx, hostId, orderId)\n  }\n  const denied = requireScope(ctx, 'orders:read')\n  if (denied) return denied\n  const unentitled = requireCommerce(ctx)\n  if (unentitled) return unentitled\n  if (request.method !== 'GET') {\n    return ApiErrors.methodNotAllowed({\n      headers: { ...ctx.headers, Allow: orderId ? 'GET, PATCH' : 'GET' },\n    })\n  }\n  const collection = hostRef(ctx, hostId).collection('orders')\n\n  if (orderId) {\n    const snap = await collection.doc(orderId).get()\n    if (!snap.exists) {\n      return ApiErrors.notFound({ message: 'No such order', headers: ctx.headers })\n    }\n    return apiJson(orderView(snap), { headers: ctx.headers })\n  }\n\n  let query: FirebaseFirestore.Query = collection\n  const status = url.searchParams.get('status')\n  if (status) query = query.where('status', '==', status)\n  const channel = url.searchParams.get('channel')\n  // `online` is the DEFAULT, not a stored value on older orders, so filtering\n  // for it in Firestore would silently drop every pre-channel order. Those are\n  // exactly the oldest orders an accounting backfill is reaching for, so this\n  // one value is filtered after the read instead. The page can therefore come\n  // back shorter than `limit` while `has_more` is still true — which the\n  // published pagination contract already tells clients to expect (check\n  // `has_more`, never a page's length).\n  if (channel && channel !== 'online') query = query.where('channel', '==', channel)\n  const { docs, nextCursor } = await paginate(query, url)\n  const data = docs\n    .map(orderView)\n    .filter((order) => (channel === 'online' ? order.channel === 'online' : true))\n  return listResponse(data, nextCursor, ctx.headers)\n}\n\n/**\n * Statuses this endpoint will move an order TO, and the two it names as\n * refused. Kept as data so the 400 can list them and the docs can be checked\n * against the same source the handler branches on.\n */\nconst ORDER_WRITE_TARGETS: OrderFulfilmentTarget[] = ['fulfilled', 'delivered']\n\n/**\n * Transitions that exist in the commerce model and are DELIBERATELY not\n * reachable here — refused by name with a 400 that says why, never silently\n * ignored. `cancelled` releases held stock under its own transaction and\n * `refunded` moves money under another; admitting either here would hand a\n * caller a door around exactly the specifics those two routes exist to\n * enforce, and an API key is the credential least able to answer the\n * questions they ask.\n */\nconst ORDER_WRITE_REFUSED: Record<string, string> = {\n  cancelled:\n    'Canceling an order releases held stock, so it is not part of this endpoint. Cancel it in the console.',\n  refunded:\n    'Refunding an order moves money, so it is not part of this endpoint. Refund it in the console.',\n}\n\n/**\n * `PATCH /v1/sites/{siteId}/orders/{orderId}` — record a shipment (AGL-2461).\n *\n * ## The write is the console's, shared\n *\n * The transition rule, the transaction that re-asks it under the write, the\n * fulfillment append and the timeline entry are `recordOrderShipment`'s,\n * the one implementation the console's `commerce/fulfill-order` route calls\n * too. A second copy of `ORDER_TRANSITIONS` here would be the bug rather\n * than the fix: two tables drift, and drift here means the API writing an\n * order status the console forbids — `paid → delivered` skipping\n * fulfilment, or a write onto a `refunded` order. That is the class\n * AGL-1818/AGL-1819 exist to close, and it is money-adjacent.\n *\n * ## What THIS function is responsible for: all of the authorization\n *\n * `recordOrderShipment` is pre-authorized by contract — it takes `hostId`\n * on trust — so every gate is here, and all four are load-bearing:\n *\n * 1. `orders:write` on the key (checked by the caller, above).\n * 2. The `commerce` PLAN entitlement (checked by the caller, above) — the\n *    plan, never the plugin switch, which is the AGL-1873 distinction.\n * 3. **Org owns the site** — the console's `handleSites` refuses an unowned\n *    `hostId` with a 404 before it hands any site resource to its plugin,\n *    which is what keeps this from being a cross-tenant write primitive\n *    addressable by anyone who can guess a host id. Deliberately NOT\n *    re-checked here: a second copy would be a gate no test can redden\n *    (removing either one alone leaves the other answering), and an unproven\n *    guard on a cross-tenant write is worse than the one guard a test\n *    actually holds. `api-v1-order-fulfilment.spec.ts`'s \"CANNOT move\n *    another org's order\" case is that test, and it fails when\n *    `handleSites`' `orgOwnsHost` is removed.\n * 4. **This plugin is switched on for this site.** The resource is\n *    registered for every organization the console serves, so its being here\n *    says nothing about one org's configuration; without this an org that\n *    switched commerce off for a site would still accept writes into it,\n *    which is the per-site enablement rule (AGL-1014) the plugin API\n *    dispatcher applies to every other commerce door.\n *\n * ## No `Idempotency-Key`\n *\n * None is needed and none is accepted: the write returns without writing when\n * the order is already in the target status, so a retry lands the same state\n * AND returns the same `200` with the same order body — the contract\n * `updateRecord`, `updateContact` and `updateFormSubmission` are held to.\n */\nasync function updateOrder(\n  request: Request,\n  ctx: ApiV1Context,\n  hostId: string,\n  orderId: string,\n): Promise<Response> {\n  const body = await readJsonBody(request)\n  const unknown = Object.keys(body).filter(\n    (key) => key !== 'status' && key !== 'carrier' && key !== 'trackingNumber',\n  )\n  if (unknown.length > 0) {\n    // Named, not dropped — the `updateFormSubmission` / `updateContact` rule.\n    // A silently ignored `trackingUrl` here reads as \"we recorded your\n    // shipment as you described it\" when half of it went nowhere, and the\n    // caller is a warehouse system that will never look again.\n    return ApiErrors.badRequest({\n      message:\n        'Only `status`, `carrier` and `trackingNumber` can be set on an order',\n      code: 'validation_failed',\n      fields: Object.fromEntries(\n        unknown.map((key) => [key, 'Not writable on an order']),\n      ),\n      headers: ctx.headers,\n    })\n  }\n\n  const status = String(body.status ?? '')\n  const refusal = ORDER_WRITE_REFUSED[status]\n  if (refusal) {\n    return ApiErrors.badRequest({\n      message: refusal,\n      code: 'validation_failed',\n      fields: { status: refusal },\n      headers: ctx.headers,\n    })\n  }\n  if (!(ORDER_WRITE_TARGETS as string[]).includes(status)) {\n    return ApiErrors.badRequest({\n      message: 'Order failed validation',\n      code: 'validation_failed',\n      fields: {\n        status: `Must be one of: ${ORDER_WRITE_TARGETS.join(', ')}`,\n      },\n      headers: ctx.headers,\n    })\n  }\n  // Bounded exactly as the console route bounds them, so one field cannot be\n  // used to stuff an order document through a door the console keeps narrow.\n  const carrier = String(body.carrier ?? '').slice(0, 40)\n  const trackingNumber = String(body.trackingNumber ?? '').slice(0, 60)\n\n  // Gate 4: this plugin, on for this site.\n  const hostSnap = await hostRef(ctx, hostId).get()\n  if (!isHostPluginEnabled(ctx.org, hostSnap.data(), BUNDLE_ID)) {\n    return ApiErrors.notFound({\n      message: 'No such site',\n      headers: ctx.headers,\n    })\n  }\n\n  const outcome = await recordOrderShipment({\n    hostId,\n    orderId,\n    to: status as OrderFulfilmentTarget,\n    carrier,\n    trackingNumber,\n  })\n  if (outcome.outcome === 'no_such_order') {\n    return ApiErrors.notFound({\n      message: 'No such order',\n      headers: ctx.headers,\n    })\n  }\n  if (outcome.outcome === 'blocked') {\n    // A NEW 409 code (`order_transition`), because an integrator has to be\n    // able to tell \"the order moved on without me\" apart from every other\n    // conflict this API can raise — it is the one a fulfilment poller will\n    // actually hit, and the one it must not retry forever.\n    return ApiErrors.conflict({\n      message: `Orders in \"${outcome.from}\" cannot be marked ${status}`,\n      code: 'order_transition',\n      headers: ctx.headers,\n    })\n  }\n  // The order object, on both `recorded` and `already` — a retry lands the\n  // same state and reads the same 200. Re-read after the write so the body\n  // shows the shipment that was just recorded rather than the one before it.\n  return apiJson(orderView(await hostRef(ctx, hostId).collection('orders').doc(orderId).get()), {\n    headers: ctx.headers,\n  })\n}\n\n/**\n * Price and stock live on VARIANTS, never on the product — a product-level\n * `inventory` exists only as a denormalized sum the console rewrites on every\n * decrement, and a product-level `priceUsd` is the legacy single-variant\n * shape. Publishing either as the product's price would be wrong the moment a\n * product has two variants, so the variant array is the contract and the\n * product carries only the roll-up, clearly named.\n *\n * `inventory: null` on a variant means UNTRACKED and `0` means SOLD OUT.\n * Collapsing them (the `?? 0` an integrator writes on the first day) turns\n * every untracked product into an out-of-stock one, so the distinction is\n * carried through verbatim rather than defaulted.\n */\nfunction variantView(variant: Record<string, unknown>) {\n  const inventory = variant.inventory\n  return {\n    id: variant.id ?? null,\n    sku: variant.sku ?? null,\n    barcode: variant.barcode ?? null,\n    options: variant.options ?? {},\n    priceUsd: typeof variant.priceUsd === 'number' ? variant.priceUsd : null,\n    compareAtPriceUsd:\n      typeof variant.compareAtPriceUsd === 'number'\n        ? variant.compareAtPriceUsd\n        : null,\n    weightGrams:\n      typeof variant.weightGrams === 'number' ? variant.weightGrams : null,\n    inventory: typeof inventory === 'number' ? inventory : null,\n    inventoryTracked: typeof inventory === 'number',\n  }\n}\n\nfunction productView(doc: FirebaseFirestore.DocumentSnapshot) {\n  const data = doc.data() ?? {}\n  const variants = Array.isArray(data.variants)\n    ? (data.variants as Array<Record<string, unknown>>)\n    : []\n  const tracked = variants.filter((v) => typeof v.inventory === 'number')\n  return {\n    id: doc.id,\n    object: 'product',\n    name: data.name ?? null,\n    slug: data.slug ?? null,\n    description: data.description ?? null,\n    type: data.type ?? null,\n    status: data.status ?? null,\n    tags: data.tags ?? [],\n    categoryIds: data.categoryIds ?? [],\n    mediaUrls: data.mediaUrls ?? [],\n    options: data.options ?? [],\n    variants: variants.map(variantView),\n    // The sum across TRACKED variants only, and `null` when none of them is\n    // tracked — so an untracked catalogue reads as \"we don't count this\"\n    // rather than as a store with nothing left to sell.\n    inventory: tracked.length\n      ? tracked.reduce((sum, v) => sum + Number(v.inventory ?? 0), 0)\n      : null,\n    subscription: serialize(data.subscription) ?? null,\n    created: data.createdAtMs ? new Date(Number(data.createdAtMs)).toISOString() : null,\n    updated: data.updatedAtMs ? new Date(Number(data.updatedAtMs)).toISOString() : null,\n  }\n}\n\nexport async function handleProducts(\n  request: Request,\n  ctx: ApiV1Context,\n  segments: string[],\n  url: URL,\n): Promise<Response> {\n  const [, hostId, , productId] = segments\n  const denied = requireScope(ctx, 'products:read')\n  if (denied) return denied\n  const unentitled = requireCommerce(ctx)\n  if (unentitled) return unentitled\n  if (request.method !== 'GET') {\n    return ApiErrors.methodNotAllowed({ headers: ctx.headers })\n  }\n  const collection = hostRef(ctx, hostId).collection('products')\n\n  if (productId) {\n    const snap = await collection.doc(productId).get()\n    // A soft-deleted product is gone as far as a customer is concerned. The\n    // console filters `deletedAt` client-side; the API must not hand back a\n    // product the merchant deleted just because the document survives.\n    if (!snap.exists || snap.get('deletedAt')) {\n      return ApiErrors.notFound({ message: 'No such product', headers: ctx.headers })\n    }\n    return apiJson(productView(snap), { headers: ctx.headers })\n  }\n\n  let query: FirebaseFirestore.Query = collection\n  const status = url.searchParams.get('status')\n  if (status) query = query.where('status', '==', status)\n  const { docs, nextCursor } = await paginate(query, url)\n  const data = docs.filter((doc) => !doc.get('deletedAt')).map(productView)\n  return listResponse(data, nextCursor, ctx.headers)\n}\n\n"],"names":["checkEntitlement","isHostPluginEnabled","ApiErrors","apiJson","listResponse","paginate","readJsonBody","requireScope","serialize","BUNDLE_ID","recordOrderShipment","requireCommerce","ctx","org","planRequired","message","code","headers","hostRef","hostId","firestore","collection","doc","orderView","data","totals","legacyTotal","Number","amountCents","NaN","totalCents","isFinite","legacyFee","feeCents","id","object","number","status","channel","currency","customerEmail","customerName","lineItems","itemsCents","shippingCents","taxCents","discountCents","refundedCents","disputed","Boolean","dispute","shippingAddress","couponCode","fulfillments","Array","isArray","map","entry","atMs","lineItemIds","carrier","trackingNumber","trackingUrl","at","Date","toISOString","created","createdAt","handleOrders","request","segments","url","orderId","method","deniedWrite","unentitledWrite","updateOrder","denied","unentitled","methodNotAllowed","Allow","snap","get","exists","notFound","query","searchParams","where","docs","nextCursor","filter","order","ORDER_WRITE_TARGETS","ORDER_WRITE_REFUSED","cancelled","refunded","body","unknown","Object","keys","key","length","badRequest","fields","fromEntries","String","refusal","includes","join","slice","hostSnap","outcome","to","conflict","from","variantView","variant","inventory","sku","barcode","options","priceUsd","compareAtPriceUsd","weightGrams","inventoryTracked","productView","variants","tracked","v","name","slug","description","type","tags","categoryIds","mediaUrls","reduce","sum","subscription","createdAtMs","updated","updatedAtMs","handleProducts","productId"],"mappings":"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"}

package/src/lib/server/billing-webhook.js

@@ -25,11 +25,8 @@ import { COMMERCE_CHARGEBACK_UNROUTABLE, COMMERCE_FEE_REPRICE_REFUSED, COMMERCE_
 import { createHmac } from "crypto";
 import { isEmailConfigured, sendEmail } from "@aglyn/shared-util-email";
 import * as CommerceModel from "../model/index.js";
-import { recordContactRefund } from "./contact-refund.js";
-// Leaf import, not the barrel, for the reason `contact-refund.ts` records: the
-// specs in this library mock `@aglyn/tenant-data-admin` wholesale, and a
-// permissive stub would turn a reversal that never happened green.
-import { reverseEmailAttributedRevenue } from "@aglyn/tenant-data-admin/server/email-revenue-attribution";
+import { recordPluginPersonRefund } from "@aglyn/aglyn/plugin-manager/plugin-person-records";
+import { reverseOrderConversion } from "@aglyn/aglyn/plugin-manager/plugin-conversion-credit";
 import { paymentRiskEventFrom } from "@aglyn/aglyn/app-utils/payment-risk";
 import { recordPaymentRiskOnRecord } from "@aglyn/tenant-data-admin/server/payment-risk-record";
 import { isTransientStripeStatus, reverseDestinationTransfer } from "@aglyn/tenant-data-admin/server/stripe-transfer-reversal";
@@ -418,7 +415,7 @@ async function findOrderForDispute(paymentIntentId) {
  * `charge.dispute.created`: FLAG the order, reverse nothing (AGL-1787).
  *
  * A dispute can be WON, and this is the whole reason the reversal waits for
- * `closed`. Nothing here un-writes: `recordContactRefund` is monotonic by
+ * `closed`. Nothing here un-writes: a person's refunds are monotonic by
  * construction (AGL-1754 chose counters over decrements precisely so a reader
  * can never be handed a number that went backwards), so a reversal written on
  * `created` and reversed again on a win would need a decrement the contact
@@ -4371,18 +4368,18 @@ async function findOrderForDispute(paymentIntentId) {
                         link: `/${hostId}/orders`
                     });
                     // The customer's side of the ledger (AGL-1754), through the same
-                    // writer a refund uses and with `kind` set so the contact's timeline
-                    // says "charged back". Skipped when nothing was reversed: a won
+                    // seam a refund uses and with the reason set so the person's
+                    // timeline says "charged back". Skipped when nothing was reversed: a won
                     // dispute moved no money, and a lost one that found nothing left to
                     // reverse would otherwise record a $0 entry against the buyer.
                     if (settled.reversedCents > 0) {
-                        await recordContactRefund({
+                        await recordPluginPersonRefund({
                             hostId,
-                            orderId: snapshot.id,
+                            refId: snapshot.id,
                             email: settled.customerEmail,
                             amountCents: settled.reversedCents,
-                            closedTheOrder: settled.closedTheOrder,
-                            kind: 'chargeback'
+                            closedTheSale: settled.closedTheOrder,
+                            reason: 'chargeback'
                         });
                         // The shelf's side (AGL-1797), the SAME door the admin-initiated
                         // refund writes so the two cannot diverge the way the contact
@@ -4404,7 +4401,7 @@ async function findOrderForDispute(paymentIntentId) {
                         // for it — and the reversal is recorded beside the credit rather
                         // than subtracted from it, exactly as the contact ledger above
                         // records `refundedCents` beside `ltvCents`.
-                        await reverseEmailAttributedRevenue({
+                        await reverseOrderConversion({
                             hostId,
                             orderId: snapshot.id,
                             amountCents: settled.reversedCents,