@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/gate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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';
+/**
+ * Is the HOST's org on a plan that includes the content paywall (AGL-481)?
+ * `contentGating` is a Business+ feature, but the member paywall used to be
+ * enforced on the visitor's purchase alone — so any plan (or a lapsed
+ * Business org) could run members-only content. This gates the feature at
+ * the org level; a plan-less/lapsed org resolves as `free` and fails
+ * closed (gated content is refused, never served open). Re-resolved per
+ * request, so a downgrade takes effect within the revalidate window.
+ */
+export declare function hostHasContentGating(hostId: string): Promise<boolean>;
+/**
+ * Entitlement check (AGL-309): is the signed-in member entitled to
+ * gated content? Entitled = a paid (non-refunded) order containing the
+ * product, or a live subscription to it ('any' matches any live
+ * subscription). Server-enforced — the gated media endpoints (video
+ * AGL-315, downloads AGL-302) call the same logic.
+ */
+export declare function checkMemberEntitlement(hostId: string, memberEmail: string, productId: string | 'any'): Promise<boolean>;
+export declare const gateHandler: PluginApiHandler;

package/src/lib/server/gate.js

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import * as Aglyn from "@aglyn/aglyn/server";
+import * as CommerceModel from "../model/index.js";
+import { firebaseAdmin, getOrgForHost } from "@aglyn/tenant-data-admin";
+import { readActiveMemberSession, setMemberCookie } from "./membership.js";
+// Subscription statuses that grant access (trialing pays later). The list
+// moved to the model as `isTenantSubscriptionLive` (AGL-1849), where the
+// checkout duplicate guard reads the same one rather than transcribing it a
+// third time; the reasoning for keeping it apart from the org-side
+// `isLiveSubscriptionStatus` travels with it.
+/**
+ * Is the HOST's org on a plan that includes the content paywall (AGL-481)?
+ * `contentGating` is a Business+ feature, but the member paywall used to be
+ * enforced on the visitor's purchase alone — so any plan (or a lapsed
+ * Business org) could run members-only content. This gates the feature at
+ * the org level; a plan-less/lapsed org resolves as `free` and fails
+ * closed (gated content is refused, never served open). Re-resolved per
+ * request, so a downgrade takes effect within the revalidate window.
+ */ export async function hostHasContentGating(hostId) {
+    var _this;
+    const org = (_this = await getOrgForHost(hostId)) == null ? void 0 : _this.org;
+    return Aglyn.checkEntitlement(org, 'contentGating');
+}
+/**
+ * Entitlement check (AGL-309): is the signed-in member entitled to
+ * gated content? Entitled = a paid (non-refunded) order containing the
+ * product, or a live subscription to it ('any' matches any live
+ * subscription). Server-enforced — the gated media endpoints (video
+ * AGL-315, downloads AGL-302) call the same logic.
+ */ export async function checkMemberEntitlement(hostId, memberEmail, productId) {
+    // Org-level gate (AGL-481): the paywall feature itself is Business+. If
+    // the host's plan doesn't include it, no visitor is "entitled" — fail
+    // closed rather than serve gated content on a plan that didn't pay for
+    // gating.
+    if (!await hostHasContentGating(hostId)) return false;
+    const firestore = firebaseAdmin.app().firestore();
+    const hostRef = firestore.collection('hosts').doc(hostId);
+    const subscriptions = await hostRef.collection('subscriptions').where('customerEmail', '==', memberEmail).limit(10).get();
+    for (const docSnapshot of subscriptions.docs){
+        if (!CommerceModel.isTenantSubscriptionLive(docSnapshot.get('status'))) continue;
+        if (productId === 'any' || docSnapshot.get('productId') === productId) {
+            return true;
+        }
+    }
+    if (productId === 'any') return false;
+    const orders = await hostRef.collection('orders').where('customerEmail', '==', memberEmail).limit(50).get();
+    for (const docSnapshot of orders.docs){
+        const order = CommerceModel.liftLegacyOrder(docSnapshot.data());
+        // The shared entitlement test (AGL-2454), which is where the partial-refund
+        // case lives. The inline status literal this replaced only ever moved on a
+        // FULL refund, so a buyer refunded for the gated product kept their access.
+        if (CommerceModel.orderEntitlesProduct(order, productId)) return true;
+    }
+    return false;
+}
+export const gateHandler = async (req, res)=>{
+    var _req_query_hostId, _req_query_productId;
+    const hostId = String((_req_query_hostId = req.query.hostId) != null ? _req_query_hostId : '');
+    const productId = String((_req_query_productId = req.query.productId) != null ? _req_query_productId : 'any');
+    if (!hostId) return res.status(400).json({
+        error: 'Missing hostId'
+    });
+    try {
+        var _session_member_get;
+        // This probe answers 200 either way, so the suspension gate
+        // (AGL-546/550) maps a suspended member to the signed-out shape —
+        // never entitled — and drops the stale cookie so the signed-in
+        // shell unwinds on the next paint.
+        const session = await readActiveMemberSession(req, hostId);
+        if (session.status !== 'active') {
+            if (session.status === 'suspended') setMemberCookie(res, hostId, null);
+            return res.status(200).json({
+                entitled: false,
+                signedIn: false
+            });
+        }
+        const email = String((_session_member_get = session.member.get('email')) != null ? _session_member_get : '');
+        if (!email) {
+            return res.status(200).json({
+                entitled: false,
+                signedIn: false
+            });
+        }
+        const entitled = await checkMemberEntitlement(hostId, email, productId);
+        res.setHeader('Cache-Control', 'private, no-store');
+        return res.status(200).json({
+            entitled,
+            signedIn: true
+        });
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Check failed'
+        });
+    }
+};
+
+//# sourceMappingURL=gate.js.map

package/src/lib/server/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/gate.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport * as Aglyn from '@aglyn/aglyn/server'\nimport * as CommerceModel from '../model'\nimport { firebaseAdmin, getOrgForHost } from '@aglyn/tenant-data-admin'\nimport { readActiveMemberSession, setMemberCookie } from './membership'\n\n// Subscription statuses that grant access (trialing pays later). The list\n// moved to the model as `isTenantSubscriptionLive` (AGL-1849), where the\n// checkout duplicate guard reads the same one rather than transcribing it a\n// third time; the reasoning for keeping it apart from the org-side\n// `isLiveSubscriptionStatus` travels with it.\n\n/**\n * Is the HOST's org on a plan that includes the content paywall (AGL-481)?\n * `contentGating` is a Business+ feature, but the member paywall used to be\n * enforced on the visitor's purchase alone — so any plan (or a lapsed\n * Business org) could run members-only content. This gates the feature at\n * the org level; a plan-less/lapsed org resolves as `free` and fails\n * closed (gated content is refused, never served open). Re-resolved per\n * request, so a downgrade takes effect within the revalidate window.\n */\nexport async function hostHasContentGating(hostId: string): Promise<boolean> {\n  const org = (await getOrgForHost(hostId))?.org\n  return Aglyn.checkEntitlement(org as any, 'contentGating')\n}\n\n/**\n * Entitlement check (AGL-309): is the signed-in member entitled to\n * gated content? Entitled = a paid (non-refunded) order containing the\n * product, or a live subscription to it ('any' matches any live\n * subscription). Server-enforced — the gated media endpoints (video\n * AGL-315, downloads AGL-302) call the same logic.\n */\nexport async function checkMemberEntitlement(\n  hostId: string,\n  memberEmail: string,\n  productId: string | 'any',\n): Promise<boolean> {\n  // Org-level gate (AGL-481): the paywall feature itself is Business+. If\n  // the host's plan doesn't include it, no visitor is \"entitled\" — fail\n  // closed rather than serve gated content on a plan that didn't pay for\n  // gating.\n  if (!(await hostHasContentGating(hostId))) return false\n  const firestore = firebaseAdmin.app().firestore()\n  const hostRef = firestore.collection('hosts').doc(hostId)\n  const subscriptions = await hostRef\n    .collection('subscriptions')\n    .where('customerEmail', '==', memberEmail)\n    .limit(10)\n    .get()\n  for (const docSnapshot of subscriptions.docs) {\n    if (!CommerceModel.isTenantSubscriptionLive(docSnapshot.get('status')))\n      continue\n    if (productId === 'any' || docSnapshot.get('productId') === productId) {\n      return true\n    }\n  }\n  if (productId === 'any') return false\n  const orders = await hostRef\n    .collection('orders')\n    .where('customerEmail', '==', memberEmail)\n    .limit(50)\n    .get()\n  for (const docSnapshot of orders.docs) {\n    const order = CommerceModel.liftLegacyOrder(docSnapshot.data() as any)\n    // The shared entitlement test (AGL-2454), which is where the partial-refund\n    // case lives. The inline status literal this replaced only ever moved on a\n    // FULL refund, so a buyer refunded for the gated product kept their access.\n    if (CommerceModel.orderEntitlesProduct(order, productId)) return true\n  }\n  return false\n}\n\nexport const gateHandler: PluginApiHandler = async (req, res) => {\n  const hostId = String(req.query.hostId ?? '')\n  const productId = String(req.query.productId ?? 'any')\n  if (!hostId) return res.status(400).json({ error: 'Missing hostId' })\n  try {\n    // This probe answers 200 either way, so the suspension gate\n    // (AGL-546/550) maps a suspended member to the signed-out shape —\n    // never entitled — and drops the stale cookie so the signed-in\n    // shell unwinds on the next paint.\n    const session = await readActiveMemberSession(req, hostId)\n    if (session.status !== 'active') {\n      if (session.status === 'suspended') setMemberCookie(res, hostId, null)\n      return res.status(200).json({ entitled: false, signedIn: false })\n    }\n    const email = String(session.member.get('email') ?? '')\n    if (!email) {\n      return res.status(200).json({ entitled: false, signedIn: false })\n    }\n    const entitled = await checkMemberEntitlement(hostId, email, productId)\n    res.setHeader('Cache-Control', 'private, no-store')\n    return res.status(200).json({ entitled, signedIn: true })\n  } catch (error) {\n    console.error(error)\n    return res.status(500).json({ error: 'Check failed' })\n  }\n}\n"],"names":["Aglyn","CommerceModel","firebaseAdmin","getOrgForHost","readActiveMemberSession","setMemberCookie","hostHasContentGating","hostId","org","checkEntitlement","checkMemberEntitlement","memberEmail","productId","firestore","app","hostRef","collection","doc","subscriptions","where","limit","get","docSnapshot","docs","isTenantSubscriptionLive","orders","order","liftLegacyOrder","data","orderEntitlesProduct","gateHandler","req","res","String","query","status","json","error","session","entitled","signedIn","email","member","setHeader","console"],"mappings":"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"}

package/src/lib/server/gift-cards.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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';
+/**
+ * Gift-card issue / void (AGL-2226).
+ *
+ * The `giftCards` subcollection has existed since AGL-322 — minted by
+ * `billing-webhook.ts` when a gift-card product is bought, decremented by
+ * `cart-checkout.ts` at redemption. Neither end had a console: grepping for
+ * that collection returned exactly those two server files, so a
+ * merchant on Business (the tier that carries `giftCards`) could sell store
+ * credit and then not see one cent of the liability they had taken on, help
+ * a customer who lost a code, or void a leaked one.
+ *
+ * WRITES ARE SERVER-SIDE, and that is not a style preference. The Firestore
+ * rules' host catch-all would happily grant an admin `create`/`update` on
+ * `giftCards` — it is not in any exclusion list. A client-writable
+ * `balanceCents` is a self-service discount machine: set it to any number,
+ * redeem it at checkout, and `cart-checkout.ts` applies it as amount-off
+ * against a Stripe coupon. The reads stay client-side (the catch-all's
+ * `allow read` already grants them, and the card wants live updates), so
+ * only the two operations that move money come through here.
+ *
+ * Re-checks the entitlement server-side for the same reason
+ * `billing-webhook.ts:2285` does: a card issued while the plan was live is
+ * honoured, but a lapsed plan must not mint new ones.
+ */
+export declare const giftCardsHandler: PluginApiHandler;

package/src/lib/server/gift-cards.js

@@ -0,0 +1,219 @@
+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 * as Aglyn from "@aglyn/aglyn/server";
+import { randomBytes } from "crypto";
+import { firebaseAdmin, getOrgForHost, hostSendingIdentity, meterHostEmail, renderHostEmailWithTokens } from "@aglyn/tenant-data-admin";
+import { isEmailConfigured, sendEmail } from "@aglyn/shared-util-email";
+/** A merchant may not mint more than this in one card. */ const MAX_ISSUE_CENTS = 100000;
+/** `GC-` + 12 uppercase hex, the shape `billing-webhook.ts` already mints. */ function mintCode() {
+    return `GC-${randomBytes(6).toString('hex').toUpperCase()}`;
+}
+/**
+ * Gift-card issue / void (AGL-2226).
+ *
+ * The `giftCards` subcollection has existed since AGL-322 — minted by
+ * `billing-webhook.ts` when a gift-card product is bought, decremented by
+ * `cart-checkout.ts` at redemption. Neither end had a console: grepping for
+ * that collection returned exactly those two server files, so a
+ * merchant on Business (the tier that carries `giftCards`) could sell store
+ * credit and then not see one cent of the liability they had taken on, help
+ * a customer who lost a code, or void a leaked one.
+ *
+ * WRITES ARE SERVER-SIDE, and that is not a style preference. The Firestore
+ * rules' host catch-all would happily grant an admin `create`/`update` on
+ * `giftCards` — it is not in any exclusion list. A client-writable
+ * `balanceCents` is a self-service discount machine: set it to any number,
+ * redeem it at checkout, and `cart-checkout.ts` applies it as amount-off
+ * against a Stripe coupon. The reads stay client-side (the catch-all's
+ * `allow read` already grants them, and the card wants live updates), so
+ * only the two operations that move money come through here.
+ *
+ * Re-checks the entitlement server-side for the same reason
+ * `billing-webhook.ts:2285` does: a card issued while the plan was live is
+ * honoured, but a lapsed plan must not mint new ones.
+ */ export const giftCardsHandler = async (req, res)=>{
+    var _req_headers_authorization, _req_body, _body_hostId, _body_action;
+    if (req.method !== 'POST') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const authorization = String((_req_headers_authorization = req.headers.authorization) != null ? _req_headers_authorization : '');
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return res.status(401).json({
+        error: 'Unauthenticated'
+    });
+    const body = typeof req.body === 'string' ? JSON.parse(req.body || '{}') : (_req_body = req.body) != null ? _req_body : {};
+    const hostId = String((_body_hostId = body.hostId) != null ? _body_hostId : '');
+    const action = String((_body_action = body.action) != null ? _body_action : '');
+    if (!hostId) return res.status(400).json({
+        error: 'Missing hostId'
+    });
+    if (action !== 'issue' && action !== 'void') {
+        return res.status(400).json({
+            error: 'Unknown action'
+        });
+    }
+    try {
+        var _hostSnapshot_get, _body_amountCents, _body_recipientEmail, _body_note;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const hostSnapshot = await hostRef.get();
+        if (!hostSnapshot.exists) {
+            return res.status(404).json({
+                error: 'Unknown site'
+            });
+        }
+        // AN ALLOWLIST (AGL-2372), not the `!role || role === 'viewer'` denylist
+        // this route used to carry — the same correction AGL-2262 made to
+        // `pos-order.ts` and `draft-order.ts` and did not reach here.
+        //
+        // A denylist silently WIDENS every time the role union grows. It did:
+        // `HostAccessRole` is `admin | editor | author | viewer` since AGL-2334,
+        // and `author` is grantable on any host through `/api/hosts/members`. So
+        // "not literally viewer" started admitting authors — a role that exists to
+        // edit content — to a route that mints and destroys store credit.
+        //
+        // `admin | editor` is the bar this route always meant (the comment here
+        // said "owner/admin/editor, not viewer"); the difference is that a role
+        // added tomorrow is now refused until someone decides otherwise, rather
+        // than admitted by silence. Absent stays refused: `undefined` is not in
+        // the set, which matters with `strictNullChecks` off.
+        const memberRole = ((_hostSnapshot_get = hostSnapshot.get('memberRoles')) != null ? _hostSnapshot_get : {})[decoded.uid];
+        if (memberRole !== 'admin' && memberRole !== 'editor') {
+            return res.status(403).json({
+                error: 'Not permitted'
+            });
+        }
+        const owner = await getOrgForHost(hostId).catch(()=>null);
+        if (!Aglyn.checkEntitlement(owner == null ? void 0 : owner.org, 'giftCards')) {
+            return res.status(402).json({
+                error: 'Gift cards are not included on this plan'
+            });
+        }
+        if (action === 'void') {
+            var _body_code;
+            const code = String((_body_code = body.code) != null ? _body_code : '').trim();
+            if (!code) return res.status(400).json({
+                error: 'Missing code'
+            });
+            const cardRef = hostRef.collection('giftCards').doc(code);
+            // Zero the balance rather than delete the document. AGL-1767 is the
+            // reason: a deleted card that a checkout still had in flight was
+            // RESURRECTED by the webhook's `increment(-cents)` into a NEGATIVE
+            // balance, which then read as a card with money on it and understated
+            // the outstanding total. A zeroed card decrements to a negative number
+            // that no redemption path will ever accept, and the row stays
+            // auditable.
+            const existing = await cardRef.get();
+            if (!existing.exists) {
+                return res.status(404).json({
+                    error: 'Unknown gift card'
+                });
+            }
+            await cardRef.set({
+                balanceCents: 0,
+                voidedAtMs: Date.now(),
+                voidedBy: decoded.uid
+            }, {
+                merge: true
+            });
+            return res.status(200).json({
+                ok: true,
+                code
+            });
+        }
+        const amountCents = Math.round(Number((_body_amountCents = body.amountCents) != null ? _body_amountCents : 0));
+        if (!Number.isFinite(amountCents) || amountCents <= 0) {
+            return res.status(400).json({
+                error: 'Amount must be above zero'
+            });
+        }
+        if (amountCents > MAX_ISSUE_CENTS) {
+            return res.status(400).json({
+                error: `Amount may not exceed $${MAX_ISSUE_CENTS / 100}`
+            });
+        }
+        const recipientEmail = String((_body_recipientEmail = body.recipientEmail) != null ? _body_recipientEmail : '').trim().slice(0, 200);
+        const note = String((_body_note = body.note) != null ? _body_note : '').trim().slice(0, 200);
+        const code = mintCode();
+        await hostRef.collection('giftCards').doc(code).set(_extends({
+            initialCents: amountCents,
+            balanceCents: amountCents,
+            recipientEmail: recipientEmail || null,
+            // Null rather than absent: the field is what tells a reader whether a
+            // card came from a sale or from the console, and `undefined` would
+            // make an issued-by-hand card indistinguishable from a legacy row.
+            orderId: null,
+            issuedBy: decoded.uid
+        }, note ? {
+            note
+        } : {}, {
+            createdAtMs: Date.now()
+        }));
+        let emailed = false;
+        if (recipientEmail && isEmailConfigured()) {
+            var _ref;
+            const value = `$${(amountCents / 100).toFixed(2)}`;
+            // The same site-designed template the purchase path uses (AGL-771), so
+            // a hand-issued card arrives looking like a bought one.
+            const designed = await renderHostEmailWithTokens(firestore, hostId, 'gift-card', {
+                'giftcard.code': code,
+                'giftcard.value': value
+            });
+            const sent = await sendEmail(_extends({
+                to: recipientEmail,
+                subject: (_ref = designed == null ? void 0 : designed.subject) != null ? _ref : 'Your gift card',
+                text: (designed == null ? void 0 : designed.text) || `Gift card code: ${code}\nValue: ${value}\n\n` + 'Enter it at checkout to apply the balance.'
+            }, (designed == null ? void 0 : designed.html) ? {
+                html: designed.html
+            } : {}, {
+                fromName: Aglyn.resolveBrandingProfile(owner == null ? void 0 : owner.org).fromName,
+                sendingIdentity: await hostSendingIdentity(hostId),
+                audience: 'tenant',
+                context: 'gift card'
+            })).then(()=>true).catch(()=>false);
+            if (sent) {
+                // Cost meter (AGL-1438). Transactional: the card has already been
+                // minted and the recipient is owed the code, so a quota may count
+                // this send but never refuse it. Metered on the SUCCESS path only,
+                // matching every other sender — a send the provider rejected costs
+                // nothing, and a meter that counted it would inflate the COGS figure
+                // exactly when mail was broken.
+                await meterHostEmail(hostId);
+            }
+            // The truth, not the intent: the console shows this back to whoever
+            // issued the card, and reporting a delivered email for a send that
+            // threw is how a customer ends up waiting for a code that is not
+            // coming.
+            emailed = sent;
+        }
+        return res.status(200).json({
+            ok: true,
+            code,
+            emailed
+        });
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Gift card operation failed'
+        });
+    }
+};
+
+//# sourceMappingURL=gift-cards.js.map

package/src/lib/server/gift-cards.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/gift-cards.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport * as Aglyn from '@aglyn/aglyn/server'\nimport { randomBytes } from 'crypto'\nimport {\n  firebaseAdmin,\n  getOrgForHost,\n  hostSendingIdentity,\n  meterHostEmail,\n  renderHostEmailWithTokens,\n} from '@aglyn/tenant-data-admin'\nimport { isEmailConfigured, sendEmail } from '@aglyn/shared-util-email'\nimport { type PluginApiHandler } from '@aglyn/aglyn/server'\n\n/** A merchant may not mint more than this in one card. */\nconst MAX_ISSUE_CENTS = 100_000\n\n/** `GC-` + 12 uppercase hex, the shape `billing-webhook.ts` already mints. */\nfunction mintCode(): string {\n  return `GC-${randomBytes(6).toString('hex').toUpperCase()}`\n}\n\n/**\n * Gift-card issue / void (AGL-2226).\n *\n * The `giftCards` subcollection has existed since AGL-322 — minted by\n * `billing-webhook.ts` when a gift-card product is bought, decremented by\n * `cart-checkout.ts` at redemption. Neither end had a console: grepping for\n * that collection returned exactly those two server files, so a\n * merchant on Business (the tier that carries `giftCards`) could sell store\n * credit and then not see one cent of the liability they had taken on, help\n * a customer who lost a code, or void a leaked one.\n *\n * WRITES ARE SERVER-SIDE, and that is not a style preference. The Firestore\n * rules' host catch-all would happily grant an admin `create`/`update` on\n * `giftCards` — it is not in any exclusion list. A client-writable\n * `balanceCents` is a self-service discount machine: set it to any number,\n * redeem it at checkout, and `cart-checkout.ts` applies it as amount-off\n * against a Stripe coupon. The reads stay client-side (the catch-all's\n * `allow read` already grants them, and the card wants live updates), so\n * only the two operations that move money come through here.\n *\n * Re-checks the entitlement server-side for the same reason\n * `billing-webhook.ts:2285` does: a card issued while the plan was live is\n * honoured, but a lapsed plan must not mint new ones.\n */\nexport const giftCardsHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const authorization = String(req.headers.authorization ?? '')\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return res.status(401).json({ error: 'Unauthenticated' })\n\n  const body =\n    typeof req.body === 'string' ? JSON.parse(req.body || '{}') : (req.body ?? {})\n  const hostId = String(body.hostId ?? '')\n  const action = String(body.action ?? '')\n  if (!hostId) return res.status(400).json({ error: 'Missing hostId' })\n  if (action !== 'issue' && action !== 'void') {\n    return res.status(400).json({ error: 'Unknown action' })\n  }\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const hostSnapshot = await hostRef.get()\n    if (!hostSnapshot.exists) {\n      return res.status(404).json({ error: 'Unknown site' })\n    }\n    // AN ALLOWLIST (AGL-2372), not the `!role || role === 'viewer'` denylist\n    // this route used to carry — the same correction AGL-2262 made to\n    // `pos-order.ts` and `draft-order.ts` and did not reach here.\n    //\n    // A denylist silently WIDENS every time the role union grows. It did:\n    // `HostAccessRole` is `admin | editor | author | viewer` since AGL-2334,\n    // and `author` is grantable on any host through `/api/hosts/members`. So\n    // \"not literally viewer\" started admitting authors — a role that exists to\n    // edit content — to a route that mints and destroys store credit.\n    //\n    // `admin | editor` is the bar this route always meant (the comment here\n    // said \"owner/admin/editor, not viewer\"); the difference is that a role\n    // added tomorrow is now refused until someone decides otherwise, rather\n    // than admitted by silence. Absent stays refused: `undefined` is not in\n    // the set, which matters with `strictNullChecks` off.\n    const memberRole = (hostSnapshot.get('memberRoles') ?? {})[decoded.uid]\n    if (memberRole !== 'admin' && memberRole !== 'editor') {\n      return res.status(403).json({ error: 'Not permitted' })\n    }\n    const owner = await getOrgForHost(hostId).catch(() => null)\n    if (!Aglyn.checkEntitlement(owner?.org as never, 'giftCards')) {\n      return res\n        .status(402)\n        .json({ error: 'Gift cards are not included on this plan' })\n    }\n\n    if (action === 'void') {\n      const code = String(body.code ?? '').trim()\n      if (!code) return res.status(400).json({ error: 'Missing code' })\n      const cardRef = hostRef.collection('giftCards').doc(code)\n      // Zero the balance rather than delete the document. AGL-1767 is the\n      // reason: a deleted card that a checkout still had in flight was\n      // RESURRECTED by the webhook's `increment(-cents)` into a NEGATIVE\n      // balance, which then read as a card with money on it and understated\n      // the outstanding total. A zeroed card decrements to a negative number\n      // that no redemption path will ever accept, and the row stays\n      // auditable.\n      const existing = await cardRef.get()\n      if (!existing.exists) {\n        return res.status(404).json({ error: 'Unknown gift card' })\n      }\n      await cardRef.set(\n        {\n          balanceCents: 0,\n          voidedAtMs: Date.now(),\n          voidedBy: decoded.uid,\n        },\n        { merge: true },\n      )\n      return res.status(200).json({ ok: true, code })\n    }\n\n    const amountCents = Math.round(Number(body.amountCents ?? 0))\n    if (!Number.isFinite(amountCents) || amountCents <= 0) {\n      return res.status(400).json({ error: 'Amount must be above zero' })\n    }\n    if (amountCents > MAX_ISSUE_CENTS) {\n      return res\n        .status(400)\n        .json({ error: `Amount may not exceed $${MAX_ISSUE_CENTS / 100}` })\n    }\n    const recipientEmail = String(body.recipientEmail ?? '').trim().slice(0, 200)\n    const note = String(body.note ?? '').trim().slice(0, 200)\n    const code = mintCode()\n    await hostRef.collection('giftCards').doc(code).set({\n      initialCents: amountCents,\n      balanceCents: amountCents,\n      recipientEmail: recipientEmail || null,\n      // Null rather than absent: the field is what tells a reader whether a\n      // card came from a sale or from the console, and `undefined` would\n      // make an issued-by-hand card indistinguishable from a legacy row.\n      orderId: null,\n      issuedBy: decoded.uid,\n      ...(note ? { note } : {}),\n      createdAtMs: Date.now(),\n    })\n\n    let emailed = false\n    if (recipientEmail && isEmailConfigured()) {\n      const value = `$${(amountCents / 100).toFixed(2)}`\n      // The same site-designed template the purchase path uses (AGL-771), so\n      // a hand-issued card arrives looking like a bought one.\n      const designed = await renderHostEmailWithTokens(\n        firestore,\n        hostId,\n        'gift-card',\n        { 'giftcard.code': code, 'giftcard.value': value },\n      )\n      const sent = await sendEmail({\n        to: recipientEmail,\n        subject: designed?.subject ?? 'Your gift card',\n        text:\n          designed?.text ||\n          `Gift card code: ${code}\\nValue: ${value}\\n\\n` +\n            'Enter it at checkout to apply the balance.',\n        ...(designed?.html ? { html: designed.html } : {}),\n        fromName: Aglyn.resolveBrandingProfile(owner?.org as never).fromName,\n        sendingIdentity: await hostSendingIdentity(hostId),\n        audience: 'tenant',\n        context: 'gift card',\n      })\n        .then(() => true)\n        .catch(() => false)\n      if (sent) {\n        // Cost meter (AGL-1438). Transactional: the card has already been\n        // minted and the recipient is owed the code, so a quota may count\n        // this send but never refuse it. Metered on the SUCCESS path only,\n        // matching every other sender — a send the provider rejected costs\n        // nothing, and a meter that counted it would inflate the COGS figure\n        // exactly when mail was broken.\n        await meterHostEmail(hostId)\n      }\n      // The truth, not the intent: the console shows this back to whoever\n      // issued the card, and reporting a delivered email for a send that\n      // threw is how a customer ends up waiting for a code that is not\n      // coming.\n      emailed = sent\n    }\n\n    return res.status(200).json({ ok: true, code, emailed })\n  } catch (error) {\n    console.error(error)\n    return res.status(500).json({ error: 'Gift card operation failed' })\n  }\n}\n"],"names":["Aglyn","randomBytes","firebaseAdmin","getOrgForHost","hostSendingIdentity","meterHostEmail","renderHostEmailWithTokens","isEmailConfigured","sendEmail","MAX_ISSUE_CENTS","mintCode","toString","toUpperCase","giftCardsHandler","req","res","body","method","status","json","error","authorization","String","headers","idToken","startsWith","slice","length","undefined","JSON","parse","hostId","action","hostSnapshot","decoded","app","auth","verifyIdToken","firestore","hostRef","collection","doc","get","exists","memberRole","uid","owner","catch","checkEntitlement","org","code","trim","cardRef","existing","set","balanceCents","voidedAtMs","Date","now","voidedBy","merge","ok","amountCents","Math","round","Number","isFinite","recipientEmail","note","initialCents","orderId","issuedBy","createdAtMs","emailed","value","toFixed","designed","sent","to","subject","text","html","fromName","resolveBrandingProfile","sendingIdentity","audience","context","then","console"],"mappings":"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"}

package/src/lib/server/low-stock.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as CommerceModel from '../model';
+/**
+ * The AGL-281 low-stock crossing alert, extracted so every stock decrement
+ * fires it (AGL-1826). It used to live inline on the buy-now branch only, so
+ * whether a merchant was told they were running out depended on which door the
+ * sale came through: the single-product storefront button alerted, while the
+ * cart, a merchant-sent draft link and the register crossed the same threshold
+ * silently.
+ *
+ * SEMANTICS ARE THE BUY-NOW BRANCH'S, UNCHANGED:
+ *
+ * - The threshold is the product's own `lowStockThreshold`, compared against
+ *   the flat total across TRACKED variants (`isLowStock` /
+ *   `productInventory`). No threshold configured means no alert, ever.
+ * - It fires on the CROSSING adjustment only — low after, not low before — so
+ *   managers get one nudge per threshold breach, not one per order after it.
+ * - Redelivery safety is the CALLER's replay guard, not re-checked here:
+ *   every call site sits behind its branch's own gate (the cart and buy-now
+ *   `created` transactions, the draft branch's pending-to-paid flip, the
+ *   POS handler's `claimAttempt`), so a redelivered event never recomputes the
+ *   pair this compares.
+ *
+ * Takes the PRE- and POST-decrement product states the caller just computed —
+ * never a re-read, which could see its own write (no crossing observed) or a
+ * concurrent one (somebody else's crossing attributed here). Callers looping
+ * over lines must hand in the compounded pair (AGL-1828/AGL-1825): each line's
+ * `lifted` is the previous line's `updated`, so two lines of one product cross
+ * exactly once, on the line that actually breaches.
+ *
+ * Fire-and-forget like the sibling notifications on every branch —
+ * `notifyHostManagers` never throws, and an alert must never fail a webhook.
+ */
+export declare function alertLowStockCrossing(hostId: string, lifted: Pick<CommerceModel.HostProduct, 'name' | 'variants' | 'lowStockThreshold'>, updated: Pick<CommerceModel.HostProduct, 'name' | 'variants' | 'lowStockThreshold'>): void;

package/src/lib/server/low-stock.js

@@ -0,0 +1,60 @@
+/**
+ * @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 { notifyHostManagers } from "@aglyn/tenant-data-admin";
+import * as CommerceModel from "../model/index.js";
+/**
+ * The AGL-281 low-stock crossing alert, extracted so every stock decrement
+ * fires it (AGL-1826). It used to live inline on the buy-now branch only, so
+ * whether a merchant was told they were running out depended on which door the
+ * sale came through: the single-product storefront button alerted, while the
+ * cart, a merchant-sent draft link and the register crossed the same threshold
+ * silently.
+ *
+ * SEMANTICS ARE THE BUY-NOW BRANCH'S, UNCHANGED:
+ *
+ * - The threshold is the product's own `lowStockThreshold`, compared against
+ *   the flat total across TRACKED variants (`isLowStock` /
+ *   `productInventory`). No threshold configured means no alert, ever.
+ * - It fires on the CROSSING adjustment only — low after, not low before — so
+ *   managers get one nudge per threshold breach, not one per order after it.
+ * - Redelivery safety is the CALLER's replay guard, not re-checked here:
+ *   every call site sits behind its branch's own gate (the cart and buy-now
+ *   `created` transactions, the draft branch's pending-to-paid flip, the
+ *   POS handler's `claimAttempt`), so a redelivered event never recomputes the
+ *   pair this compares.
+ *
+ * Takes the PRE- and POST-decrement product states the caller just computed —
+ * never a re-read, which could see its own write (no crossing observed) or a
+ * concurrent one (somebody else's crossing attributed here). Callers looping
+ * over lines must hand in the compounded pair (AGL-1828/AGL-1825): each line's
+ * `lifted` is the previous line's `updated`, so two lines of one product cross
+ * exactly once, on the line that actually breaches.
+ *
+ * Fire-and-forget like the sibling notifications on every branch —
+ * `notifyHostManagers` never throws, and an alert must never fail a webhook.
+ */ export function alertLowStockCrossing(hostId, lifted, updated) {
+    if (CommerceModel.isLowStock(updated) && !CommerceModel.isLowStock(lifted)) {
+        var _CommerceModel_productInventory;
+        void notifyHostManagers(hostId, {
+            type: 'content.lowStock',
+            title: `Low stock — ${updated.name}`,
+            body: `${(_CommerceModel_productInventory = CommerceModel.productInventory(updated)) != null ? _CommerceModel_productInventory : 0} left across tracked variants`,
+            link: `/${hostId}/products`
+        });
+    }
+}
+
+//# sourceMappingURL=low-stock.js.map

package/src/lib/server/low-stock.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/low-stock.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 { notifyHostManagers } from '@aglyn/tenant-data-admin'\nimport * as CommerceModel from '../model'\n\n/**\n * The AGL-281 low-stock crossing alert, extracted so every stock decrement\n * fires it (AGL-1826). It used to live inline on the buy-now branch only, so\n * whether a merchant was told they were running out depended on which door the\n * sale came through: the single-product storefront button alerted, while the\n * cart, a merchant-sent draft link and the register crossed the same threshold\n * silently.\n *\n * SEMANTICS ARE THE BUY-NOW BRANCH'S, UNCHANGED:\n *\n * - The threshold is the product's own `lowStockThreshold`, compared against\n *   the flat total across TRACKED variants (`isLowStock` /\n *   `productInventory`). No threshold configured means no alert, ever.\n * - It fires on the CROSSING adjustment only — low after, not low before — so\n *   managers get one nudge per threshold breach, not one per order after it.\n * - Redelivery safety is the CALLER's replay guard, not re-checked here:\n *   every call site sits behind its branch's own gate (the cart and buy-now\n *   `created` transactions, the draft branch's pending-to-paid flip, the\n *   POS handler's `claimAttempt`), so a redelivered event never recomputes the\n *   pair this compares.\n *\n * Takes the PRE- and POST-decrement product states the caller just computed —\n * never a re-read, which could see its own write (no crossing observed) or a\n * concurrent one (somebody else's crossing attributed here). Callers looping\n * over lines must hand in the compounded pair (AGL-1828/AGL-1825): each line's\n * `lifted` is the previous line's `updated`, so two lines of one product cross\n * exactly once, on the line that actually breaches.\n *\n * Fire-and-forget like the sibling notifications on every branch —\n * `notifyHostManagers` never throws, and an alert must never fail a webhook.\n */\nexport function alertLowStockCrossing(\n  hostId: string,\n  lifted: Pick<\n    CommerceModel.HostProduct,\n    'name' | 'variants' | 'lowStockThreshold'\n  >,\n  updated: Pick<\n    CommerceModel.HostProduct,\n    'name' | 'variants' | 'lowStockThreshold'\n  >,\n): void {\n  if (\n    CommerceModel.isLowStock(updated) &&\n    !CommerceModel.isLowStock(lifted)\n  ) {\n    void notifyHostManagers(hostId, {\n      type: 'content.lowStock',\n      title: `Low stock — ${updated.name}`,\n      body: `${CommerceModel.productInventory(updated) ?? 0} left across tracked variants`,\n      link: `/${hostId}/products`,\n    })\n  }\n}\n"],"names":["notifyHostManagers","CommerceModel","alertLowStockCrossing","hostId","lifted","updated","isLowStock","type","title","name","body","productInventory","link"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,kBAAkB,QAAQ,2BAA0B;AAC7D,YAAYC,mBAAmB,oBAAU;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASC,sBACdC,MAAc,EACdC,MAGC,EACDC,OAGC;IAED,IACEJ,cAAcK,UAAU,CAACD,YACzB,CAACJ,cAAcK,UAAU,CAACF,SAC1B;YAIWH;QAHX,KAAKD,mBAAmBG,QAAQ;YAC9BI,MAAM;YACNC,OAAO,CAAC,YAAY,EAAEH,QAAQI,IAAI,EAAE;YACpCC,MAAM,IAAGT,kCAAAA,cAAcU,gBAAgB,CAACN,oBAA/BJ,kCAA2C,EAAE,6BAA6B,CAAC;YACpFW,MAAM,CAAC,CAAC,EAAET,OAAO,SAAS,CAAC;QAC7B;IACF;AACF"}