@aglyn/plugins-commerce 1.0.0-beta.143

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/reserve.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 { AttemptClaim, PluginApiHandler } from '@aglyn/aglyn/server'\nimport * as Aglyn from '@aglyn/aglyn/server'\nimport * as CommerceModel from '../model'\nimport { claimAttempt } from '@aglyn/aglyn/server'\nimport { firebaseAdmin, getOrgForHost } from '@aglyn/tenant-data-admin'\nimport { connectLinkageIsReady } from '@aglyn/tenant-data-admin/server/stripe-account-mode'\n\n/**\n * Reserve a stay (AGL-310): server-side quote + availability check,\n * pending reservation doc, then a Stripe session for the deposit (or\n * full amount) on the merchant's account. Webhook completion confirms\n * the reservation; abandoned pending holds expire after 30 minutes and\n * stop blocking the calendar.\n */\nexport const reserveHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  if (!process.env.STRIPE_SECRET_KEY) {\n    return res.status(501).json({ error: 'Payments are not configured.' })\n  }\n  const body =\n    typeof req.body === 'string' ? JSON.parse(req.body) : (req.body ?? {})\n  const hostId = String(body.hostId ?? '')\n  const resourceId = String(body.resourceId ?? '')\n  const checkInDayMs = CommerceModel.toDayMs(Number(body.checkInDayMs ?? 0))\n  const checkOutDayMs = CommerceModel.toDayMs(Number(body.checkOutDayMs ?? 0))\n  const guestName = String(body.guestName ?? '').trim().slice(0, 120)\n  const guestEmail = String(body.guestEmail ?? '').trim().toLowerCase().slice(0, 120)\n  // One reservation attempt, minted by the widget (AGL-1697). Node lowercases\n  // incoming headers, but read both spellings — the plugin API request type\n  // makes no promise about casing.\n  const idempotencyKey = String(\n    req.headers['idempotency-key'] ?? req.headers['Idempotency-Key'] ?? '',\n  ).trim().slice(0, 200)\n  if (!hostId || !resourceId || !checkInDayMs || !checkOutDayMs) {\n    return res.status(400).json({ error: 'Missing reservation details' })\n  }\n\n  let claim: AttemptClaim | null = null\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    // Owner + payment readiness, HOISTED above the claim (AGL-1697): both are\n    // deterministic refusals a merchant fixes out of band, and neither should\n    // burn the guest's attempt key.\n    const ownerOrg = await getOrgForHost(hostId)\n    // Plan gate, re-asked per request exactly as the storefront checkout\n    // asks it (AGL-1873, the AGL-481 pattern): a lapsed org's storefront\n    // must not keep taking reservation deposits — at the free plan's 0%\n    // transaction fee — through the one shopper-facing commerce door that\n    // skipped the entitlement. Deterministic and merchant-side, so it sits\n    // here above the claim with the readiness check.\n    if (!Aglyn.checkEntitlement(ownerOrg?.org as any, 'commerce')) {\n      return res.status(403).json({ error: 'Reservations are not enabled' })\n    }\n    const ownerId = ownerOrg?.org?.ownerUid\n    const ownerProfile = ownerId\n      ? await firestore.collection('profiles').doc(String(ownerId)).get()\n      : null\n    const accountId = ownerProfile?.get('stripeAccountId')\n    if (\n      !connectLinkageIsReady(\n        {\n          accountId,\n          chargesEnabled: ownerProfile?.get('stripeChargesEnabled'),\n          accountLivemode: ownerProfile?.get('stripeAccountLivemode'),\n        },\n        { subject: `reserve host ${hostId}` },\n      )\n    ) {\n      return res.status(409).json({ error: 'Payments are not set up yet' })\n    }\n\n    // The claim sits ABOVE the availability read, and that placement is the\n    // fix for this handler's particular lie (AGL-1697): a retried attempt used\n    // to collide with its OWN 30-minute pending hold and be told \"Those dates\n    // just sold out\" — about dates the guest was holding — where the correct\n    // answer was the original session URL. Replaying here means the retry\n    // never reaches the availability check at all. Every refusal below the\n    // claim releases it, because each is deterministic and retryable.\n    const claimed = await claimAttempt(firestore, {\n      kind: 'commerce-reserve',\n      scopeId: hostId,\n      orgId: String(ownerOrg?.org?.id ?? ''),\n      key: idempotencyKey,\n      busyMessage: 'This reservation is already being processed',\n    })\n    if ('replay' in claimed) {\n      return res.status(claimed.replay.status).json(claimed.replay.body)\n    }\n    claim = claimed.claim\n\n    // ONLY STAYS THAT COULD STILL OVERLAP, NEAREST FIRST (AGL-2159).\n    //\n    // This was `.where('resourceId','==',resourceId).limit(500)` with no\n    // ordering, so Firestore returned 500 documents in `__name__` order — an\n    // arbitrary slice of the resource's ENTIRE booking history. Every stay the\n    // resource has ever had competed for those 500 slots on equal terms with\n    // the ones that matter, so a cottage that had taken 500 bookings began\n    // silently dropping LIVE reservations out of its own availability check\n    // and confirming a second guest into an occupied room. Nothing about that\n    // failure is visible: `isRangeAvailable` is handed a short list and\n    // answers, correctly, that the range is free.\n    //\n    // `checkOutDayMs > checkInDayMs` is the one inequality that removes the\n    // whole of the past — a stay that ended before the requested arrival\n    // cannot overlap it — and ordering by the same field puts the stays\n    // nearest the requested window at the front of the limit rather than\n    // whichever ones happen to sort early by id. Needs the composite index\n    // `reservations (resourceId ASC, checkOutDayMs ASC)`, added to\n    // `cloud/firebase-firestore.indexes.json` and pinned by\n    // `reserve-availability-indexes.spec.ts` — an equality plus an `orderBy`\n    // on a second field is exactly the shape that reads as free and is not\n    // (AGL-1793), and here a missing index throws rather than under-reporting.\n    //\n    // RESIDUAL, stated: the cap can still bite when a single resource holds\n    // more than 500 stays that all end between the requested arrival and the\n    // end of a genuinely overlapping one. That is a far narrower window than\n    // \"500 bookings in this resource's lifetime\", but it is not zero, and the\n    // sweep that would keep expired `pending` holds from filling those slots\n    // is a scheduled job this change does not add (see the commit).\n    const availabilityQuery = hostRef\n      .collection('reservations')\n      .where('resourceId', '==', resourceId)\n      .where('checkOutDayMs', '>', checkInDayMs)\n      .orderBy('checkOutDayMs')\n      .limit(500)\n    const [resourceSnapshot, reservationsSnapshot, storeSnapshot] =\n      await Promise.all([\n        hostRef.collection('resources').doc(resourceId).get(),\n        availabilityQuery.get(),\n        // The merchant's own lodging rate (AGL-1969). Read in the SAME round\n        // trip as the availability query rather than as a fourth sequential\n        // await — this path already runs three reads before it can answer, and\n        // a tax lookup is not a reason to make a guest wait for a fourth.\n        hostRef.collection('settings').doc('store').get(),\n      ])\n    const resource = resourceSnapshot.data() as CommerceModel.HostResource | undefined\n    if (!resource) {\n      await claim.release()\n      return res.status(404).json({ error: 'Unknown resource' })\n    }\n\n    // Pending holds block for 30 minutes only, so abandoned checkouts\n    // release the dates. The lapse itself lives in\n    // `reservationHoldsDates`, which `isRangeAvailable` applies — this reads\n    // the fields that rule needs and leaves the rule to the model, so the\n    // storefront's date-picker cannot answer a different question from the\n    // door that takes the money.\n    //\n    // Extracted so the pre-read below and the re-read inside the booking\n    // transaction cannot drift apart (AGL-2450). Two copies of a filter that\n    // decides whether a room is free is exactly the shape where one of them\n    // quietly stops matching the other.\n    const readLive = (snapshot: {\n      docs: any[]\n    }): CommerceModel.HostReservation[] =>\n      snapshot.docs.map((docSnapshot) => ({\n        checkInDayMs: Number(docSnapshot.get('checkInDayMs')),\n        checkOutDayMs: Number(docSnapshot.get('checkOutDayMs')),\n        status: String(\n          docSnapshot.get('status'),\n        ) as CommerceModel.ReservationStatus,\n        createdAtMs: Number(docSnapshot.get('createdAtMs') ?? 0),\n      })) as CommerceModel.HostReservation[]\n    const now = Date.now()\n    const live = readLive(reservationsSnapshot)\n    if (\n      !CommerceModel.isRangeAvailable(\n        resource,\n        live,\n        checkInDayMs,\n        checkOutDayMs,\n        now,\n      )\n    ) {\n      // A GENUINE sold-out (a keyed retry replayed before reaching here). The\n      // guest picks other dates or the blocking stay is cancelled; either way\n      // the key must survive the refusal.\n      await claim.release()\n      return res.status(409).json({ error: 'Those dates just sold out' })\n    }\n    const quote = CommerceModel.computeReservationQuote(\n      resource,\n      checkInDayMs,\n      checkOutDayMs,\n    )\n    if (quote.problem) {\n      await claim.release()\n      return res.status(400).json({ error: quote.problem })\n    }\n\n    const chargeCents = quote.depositCents || quote.totalCents\n\n    // NO DISCOUNT IS APPLIED HERE, AND THAT IS AN OPEN QUESTION RATHER THAN AN\n    // OVERSIGHT (AGL-305).\n    //\n    // `hosts/{hostId}/discounts` reaches the cart, buy-now, the draft-order\n    // payment link and the register. This door was deliberately left out,\n    // because unlike those four it does not take a payment for goods — it takes\n    // a DEPOSIT against a stay that is settled later, and \"apply 10% off\" has\n    // three different meanings against that shape:\n    //\n    //   1. Discount the STAY. `quote.totalCents` falls, the deposit falls with\n    //      it because it is a percentage of the subtotal, and the balance falls\n    //      too. This is the only reading that is actually a discount on the\n    //      booking — and it reprices a merchant's lodging inventory from a\n    //      storefront promo code, which is a larger claim than any of the four\n    //      goods doors makes.\n    //   2. Discount the DEPOSIT only. Strictly worse than doing nothing: the\n    //      balance is computed downstream as `totalCents - paidCents`, so every\n    //      cent taken off at booking is billed straight back at check-out. The\n    //      guest would be shown a discount and then charged for it, which is\n    //      the silent-reversal shape this codebase refuses elsewhere.\n    //   3. Discount the BALANCE. Nothing visible at booking; the guest finds\n    //      out at the register. A promotion nobody can see when they buy is not\n    //      a promotion.\n    //\n    // What makes this a product decision and not an implementation one is that\n    // the balance is not collected by any door this repo can teach. It is read\n    // off the console's reservations card as `totalCents - paidCents` and\n    // collected BY A HUMAN at the till, so option 1 is the only one that\n    // survives the hand-off — and it survives it by changing the stay's stored\n    // price, which is the merchant's revenue basis and what their analytics,\n    // their folio and their register all read.\n    //\n    // The tax makes it sharper still. `lodgingTax` below is an occupancy rate,\n    // not a sales rate, and its basis here is already a STATED LIMITATION — it\n    // is charged on what is collected (the deposit) rather than on the stay.\n    // Layering a discount on top asks whether occupancy tax is owed on the\n    // discounted room rate or the gross one, which differs by jurisdiction, is\n    // the merchant's own regime to answer, and is not a question this handler\n    // can decide from a promo code.\n    //\n    // So: refusing to guess. A shopper who types a code here is not told it\n    // worked — this path never reads one, so there is nothing to fall through\n    // silently, which is the failure mode that mattered. When the owner picks\n    // a reading, option 1 is the one the machinery already supports: reduce\n    // `quote.subtotalCents` before the deposit is derived from it, and the\n    // deposit, the balance, the fee and the tax all follow without further\n    // change.\n\n    // LODGING TAX: the MERCHANT'S OWN RATE, off unless they set one\n    // (AGL-1969, answering the decision AGL-1953 recorded here).\n    //\n    // What this path used to do, and why it was only ever a holding position:\n    // it computed no tax in either store mode, on two stated grounds. The\n    // first is still true and is the reason for the shape below — a stay is\n    // not goods. The AGL-285 zone editor configures a SALES rate, lodging is\n    // an occupancy/hotel regime with its own rates, its own registration and\n    // its own return, and reading `rates[]` for a night would be confidently\n    // wrong rather than merely absent. Stripe Tax has the mirror problem: it\n    // needs a lodging tax code this handler does not send, so\n    // `automatic_tax` here would compute a goods rate on a room. Neither of\n    // those changes, and neither is used.\n    //\n    // What DID change is that the merchant now has a field of their own to\n    // answer in (`tax.lodging`), so \"Aglyn does not know the right number\"\n    // stops being a reason to collect nothing. They type the rate, we compute\n    // it, charge it, record it and stamp the regime; the settings card states\n    // plainly that determining what is owed and to whom is theirs. Aglyn\n    // takes no tax position here — this is the manual LODGING rate, which\n    // never touches Aglyn's registrations.\n    //\n    // ⚠️ This comment used to say \"Terms §10.3 ... untouched by this\". §10.3\n    // CHANGED on 2026-08-24 (AGL-1956): Aglyn accepts marketplace-facilitator\n    // status and new §10.7 makes storefront sales tax Aglyn's where it has a\n    // collection obligation. Lodging tax is still the merchant's, so this\n    // handler is unaffected — but §10.3 is no longer the authority for that.\n    //\n    // DEFAULT OFF, and that is load-bearing: `resolveFlatTaxCents` answers\n    // zero for an absent, zero, negative or out-of-range rate, so no existing\n    // reservation's charge moves because this shipped.\n    //\n    // THE BASIS IS WHAT IS CHARGED, AND THAT IS A STATED LIMITATION RATHER\n    // THAN AN ANSWER. `chargeCents` is `depositCents || totalCents`, so on a\n    // deposit-taking resource the tax collected here is the rate on the\n    // DEPOSIT, not on the stay. Whether a given jurisdiction wants occupancy\n    // tax on the full stay at booking, on the deposit only, or on redemption\n    // at check-out is a tax question, it differs by jurisdiction, and this\n    // code deliberately does NOT decide it — the amount the platform actually\n    // moves is the only basis available to it, the settings card says so in\n    // the merchant's own view, and the residual is on AGL-1969.\n    const taxSettings = ((storeSnapshot.data() as any)?.tax ??\n      {}) as CommerceModel.TaxSettings\n    const lodgingTax = CommerceModel.resolveFlatTaxCents(\n      taxSettings.lodging,\n      chargeCents,\n      'Lodging tax',\n    )\n\n    // Platform take PLUS Stripe's card cost at cost (AGL-2152). This is a\n    // destination charge, so Stripe debits its percentage plus 30¢ from the\n    // PLATFORM's balance; with the old take-only figure every tier carrying a\n    // 0% service rate paid Aglyn nothing and cost it that fee on each\n    // reservation.\n    //\n    // THE TWO BASES ARE NOW DIFFERENT NUMBERS (AGL-1969), and the split is\n    // AGL-2317's rule: the platform take is computed on the ITEMS — the stay\n    // — while Stripe's cost is passed through on the WHOLE charge, because\n    // that is what Stripe actually debits. Taking a percentage of the lodging\n    // tax would be taking a cut of the state's money, which no storefront\n    // path does. The previous single-argument form is what made this a real\n    // risk: it read as \"the fee base is the charge\" and would have silently\n    // started taxing the tax the moment a tax line appeared.\n    const feeCents = Aglyn.resolveTransactionFeeCents(\n      ownerOrg?.org as any,\n      'service',\n      chargeCents,\n      chargeCents + lodgingTax.taxCents,\n    )\n\n    // THE HOLD IS TAKEN IN A TRANSACTION (AGL-2450).\n    //\n    // The check above is a fast refusal on a stale read, and on its own that is\n    // all it ever was: the availability query ran, the quote and the fee were\n    // computed, and only then did the hold land — so two guests requesting the\n    // same dates both read a reservation set that lacked the other's booking,\n    // both passed, and both got a `pending` row and a real payment. Nothing\n    // downstream caught it. The webhook's transaction guards double-CONFIRMATION\n    // of one booking against Stripe redelivery; it never re-asks availability,\n    // so both holds confirmed cleanly into two guests in one room.\n    //\n    // `claimAttempt` does not help either, and it is worth being explicit about\n    // why: it is keyed on the guest's own `Idempotency-Key`, so it dedupes\n    // retries of ONE attempt. Two different guests carry two different keys and\n    // never contend.\n    //\n    // Re-asking inside the transaction that writes is the whole guard — the\n    // same shape as `decrementVariantStock` (AGL-2320), and easier to justify\n    // here: the conflicting write lands BEFORE Stripe is contacted, so this\n    // door can legitimately refuse rather than take the money and withhold the\n    // room.\n    const reservationRef = hostRef.collection('reservations').doc()\n    const booked = await firestore.runTransaction(async (transaction: any) => {\n      const fresh = await transaction.get(availabilityQuery)\n      // Re-timed, not reusing `now`: a transaction that retries under\n      // contention may run appreciably later, and the 30-minute pending window\n      // has to be measured from when this attempt actually commits.\n      if (\n        !CommerceModel.isRangeAvailable(\n          resource,\n          readLive(fresh),\n          checkInDayMs,\n          checkOutDayMs,\n          Date.now(),\n        )\n      ) {\n        return false\n      }\n      // `create()`, not `set()`: the ref is freshly minted, so an id collision\n      // is a bug rather than an overwrite to absorb silently.\n      transaction.create(reservationRef, {\n        resourceId,\n        status: 'pending',\n        checkInDayMs,\n        checkOutDayMs,\n        guestName: guestName || null,\n        guestEmail: guestEmail || null,\n        nights: quote.nights,\n        totalCents: quote.totalCents,\n        depositCents: quote.depositCents,\n        paidCents: 0,\n        createdAtMs: now,\n      } satisfies CommerceModel.HostReservation)\n      return true\n    })\n    if (!booked) {\n      // Lost the race for these dates. Same refusal as the pre-read's, and the\n      // key survives it for the same reason: the guest picks other dates or the\n      // blocking stay is cancelled.\n      await claim.release()\n      return res.status(409).json({ error: 'Those dates just sold out' })\n    }\n\n    const referer = String(req.headers.referer ?? '')\n    const origin = `https://${req.headers.host}`\n    const backUrl = referer.startsWith('http') ? referer : origin\n    const separator = backUrl.includes('?') ? '&' : '?'\n    const params = new URLSearchParams({\n      mode: 'payment',\n      'line_items[0][quantity]': '1',\n      'line_items[0][price_data][currency]': 'usd',\n      'line_items[0][price_data][unit_amount]': String(chargeCents),\n      'line_items[0][price_data][product_data][name]': `${resource.name} — ${\n        quote.nights\n      } night${quote.nights === 1 ? '' : 's'}${\n        quote.depositCents && quote.depositCents < quote.totalCents\n          ? ' (deposit)'\n          : ''\n      }`.slice(0, 120),\n      // The merchant's lodging tax as an ORDINARY product line Stripe is\n      // never told is tax — the AGL-1711 construction every other manual rate\n      // rides. That is what makes the derived `taxMode` read `manual`: the\n      // figure is the merchant's own, computed from their own rate, and never\n      // against Aglyn's registrations the way `automatic_tax` would be\n      // (AGL-1904). Absent entirely when no rate is set, so a default store's\n      // session carries no tax parameter of any kind.\n      ...(lodgingTax.taxCents > 0\n        ? {\n            'line_items[1][quantity]': '1',\n            'line_items[1][price_data][currency]': 'usd',\n            'line_items[1][price_data][unit_amount]': String(\n              lodgingTax.taxCents,\n            ),\n            'line_items[1][price_data][product_data][name]': lodgingTax.label,\n          }\n        : {}),\n      ...(feeCents > 0\n        ? { 'payment_intent_data[application_fee_amount]': String(feeCents) }\n        : {}),\n      'payment_intent_data[transfer_data][destination]': String(accountId),\n      ...(guestEmail ? { customer_email: guestEmail } : {}),\n      success_url: `${backUrl}${separator}reserved=1`,\n      cancel_url: `${backUrl}${separator}reserved=0`,\n      'metadata[type]': 'commerce-reservation',\n      'metadata[hostId]': hostId,\n      'metadata[reservationId]': reservationRef.id,\n      'metadata[feeCents]': String(feeCents),\n      // The only witness to the tax (AGL-1969). By the construction above\n      // Stripe does not know the second line is tax, so it reports\n      // `total_details.amount_tax: 0` — the session's own metadata is what\n      // `storefront-tax-record.ts` and the confirmation branch read to record\n      // the figure and derive the regime, exactly as `checkout.ts` stamps it\n      // for a buy-now sale. Absent when there is no tax, never a reassuring\n      // `'0'`: absent and zero are different facts on a back-book question.\n      ...(lodgingTax.taxCents > 0\n        ? {\n            'metadata[taxCents]': String(lodgingTax.taxCents),\n            'metadata[taxPct]': String(lodgingTax.pct),\n          }\n        : {}),\n    })\n    const response = await fetch(\n      'https://api.stripe.com/v1/checkout/sessions',\n      {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,\n          'Content-Type': 'application/x-www-form-urlencoded',\n          // The half that costs real money (AGL-1697). Stripe replays the\n          // existing session for a repeated key instead of opening a second\n          // one, covering the window where the claim is written but the\n          // response never arrives.\n          ...(claim.stripeKey ? { 'Idempotency-Key': claim.stripeKey } : {}),\n        },\n        body: params.toString(),\n      },\n    )\n    const session = (await response.json()) as { url?: string; error?: any }\n    if (!response.ok || !session.url) {\n      console.error('Stripe reservation error', session.error)\n      await reservationRef.delete().catch(() => undefined)\n      // The hold is rolled back, so the key must come back too — the guest\n      // presses the same button and the retry re-derives the same digest,\n      // which Stripe replays if the session did get created.\n      await claim.release()\n      return res.status(502).json({ error: 'Payment setup failed' })\n    }\n    const payload = { url: session.url }\n    await claim.record(200, payload)\n    return res.status(200).json(payload)\n  } catch (error) {\n    console.error(error)\n    // Release on the way out so a transient failure does not strand the key\n    // (AGL-1691's rule): the hold may or may not have landed, and it expires\n    // in 30 minutes either way.\n    await claim?.release()\n    return res.status(500).json({ error: 'Reservation failed' })\n  }\n}\n"],"names":["Aglyn","CommerceModel","claimAttempt","firebaseAdmin","getOrgForHost","connectLinkageIsReady","reserveHandler","req","res","body","method","status","json","error","process","env","STRIPE_SECRET_KEY","JSON","parse","hostId","String","resourceId","checkInDayMs","toDayMs","Number","checkOutDayMs","guestName","trim","slice","guestEmail","toLowerCase","idempotencyKey","headers","claim","ownerOrg","storeSnapshot","firestore","app","hostRef","collection","doc","checkEntitlement","org","ownerId","ownerUid","ownerProfile","get","accountId","chargesEnabled","accountLivemode","subject","claimed","kind","scopeId","orgId","id","key","busyMessage","replay","availabilityQuery","where","orderBy","limit","resourceSnapshot","reservationsSnapshot","Promise","all","resource","data","release","readLive","snapshot","docs","map","docSnapshot","createdAtMs","now","Date","live","isRangeAvailable","quote","computeReservationQuote","problem","chargeCents","depositCents","totalCents","taxSettings","tax","lodgingTax","resolveFlatTaxCents","lodging","feeCents","resolveTransactionFeeCents","taxCents","reservationRef","booked","runTransaction","transaction","fresh","create","nights","paidCents","referer","origin","host","backUrl","startsWith","separator","includes","params","URLSearchParams","mode","name","label","customer_email","success_url","cancel_url","pct","response","fetch","Authorization","stripeKey","toString","session","ok","url","console","delete","catch","undefined","payload","record"],"mappings":"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"}

package/src/lib/server/restock-flag.d.ts

@@ -0,0 +1,202 @@
+/**
+ * @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';
+/**
+ * Stock left off the shelf by a reversed order (AGL-1797).
+ *
+ * The checkout webhook decrements variant inventory on a sale and NOTHING put
+ * it back — not `refund.ts`, not the lost-dispute handler (AGL-1787) — so a
+ * fully reversed order left the merchant's count permanently one lower than
+ * their shelf, compounding with every return.
+ *
+ * THIS FLAGS. IT DOES NOT RELEASE, and that is the decision.
+ *
+ * "Increment on reversal" is the obvious fix and it is wrong in two of the
+ * three cases it would fire on:
+ *
+ *  - a **returned** item does come back, but only once it is RECEIVED, and no
+ *    fulfilment event records receipt — `OrderFulfillment` has no returned
+ *    state, so the moment an automatic increment would need does not exist;
+ *  - a **refund with no return** (goodwill, damaged, lost in post) leaves the
+ *    goods gone. Incrementing there invents inventory the merchant does not
+ *    have, and that is strictly worse than the bug it replaces: the bug
+ *    under-counts and refuses a sale that could have been made, while the
+ *    "fix" over-counts and TAKES a sale that cannot be filled;
+ *  - a **chargeback** is the clearest do-not-restock case there is. The shopper
+ *    kept the item and took the money, and `product_not_received` — the most
+ *    common reason code — asserts the goods shipped.
+ *
+ * The quantities are not always knowable on a partial. A refund requested as an
+ * AMOUNT selects no line — "$17 of a $62 order" names nothing — and that is
+ * recorded rather than papered over: `quantity` is at most the units the line
+ * sold, capped to what the count actually gave up, and `fullyReversed` says
+ * whether that bound is a tight one.
+ *
+ * A refund that NAMES ITS LINES is scoped to them (AGL-2325). When this was
+ * written no reversal recorded which lines it covered; AGL-2454 changed that,
+ * and `refund.ts` commits `refundedLineItemIds` with the money, before this
+ * flag re-reads the order. A one-line refund on a three-line order that still
+ * asked about all three was the same over-statement this module already fixed
+ * on the units axis, arriving by a door that opened afterwards. See
+ * `reversalLineScope` for the three cases that stay whole-order.
+ *
+ * So the merchant is asked. They are the only party who knows whether the
+ * goods came back, and by the time they read this they know it.
+ *
+ * WHAT IS DELIBERATELY NOT BUILT HERE. No stock writer and no
+ * `InventoryAdjustment` row: the products hub's "Adjust stock" already writes
+ * the variant counts and logs the adjustment with a reason, so a second writer
+ * for one number would be a re-implementation, not an extension. And an
+ * adjustment row for stock that has NOT moved would corrupt the very ledger
+ * that hub renders as history. This writes the question; the existing action
+ * answers it.
+ *
+ * WHERE THE MERCHANT SEES IT. The order timeline, which the console order
+ * dialog already renders, so this needs no UI change to be visible at all. The
+ * `restockCheck` record beside it is the structured half a badge and a
+ * one-click action read; that console work is filed, not smuggled in.
+ *
+ * NO NOTIFICATION. A refund is initiated BY an admin in the console, so telling
+ * them about their own click is noise, and the chargeback door already sends a
+ * manager notification for the dispute itself — a second one for the same event
+ * would train them to ignore both.
+ *
+ * ONLY WHAT THE SALE DECREMENTED IS FLAGGED. Tracking lives on the product
+ * variant, not the order line, so this reads the products and applies the sale
+ * path's own test (`variant.inventory != null`). A store that tracks no stock
+ * therefore gets NO flag rather than a prompt it can never act on, which is the
+ * difference between a signal and noise. It costs a handful of reads on an
+ * event as rare as a reversal.
+ *
+ * The `inventoryAdjustments` ledger was the tempting shortcut for SELECTING the
+ * lines and it is not usable for that: the buy-now/subscription sale path
+ * decrements stock without writing a row (`billing-webhook.ts`, the
+ * `productId` branch), so the ledger has holes the order's own line items do
+ * not. The lines are still chosen from the order.
+ *
+ * IT IS READ TO BOUND THE NUMBER, THOUGH (AGL-2325), and the holes are exactly
+ * why that is safe in this direction. `line.quantity` is the units the line
+ * SOLD, and on a backorder product the inventory floor absorbed part or all of
+ * the decrement, so the prompt named units the count never gave up. The sale
+ * rows' `appliedDelta` says how many it did, and only pairs the ledger
+ * DESCRIBES are capped — a line it is silent about keeps the upper bound, so a
+ * hole costs an over-stated question rather than stock stranded off the shelf.
+ * `saleReleaseCaps` and `capRestockLines` are shared with the cancellation
+ * writer, so what this ASKS and what that RETURNS cannot drift apart.
+ *
+ * FAILURES ARE SWALLOWED, like `recordContactRefund`'s. The money has already
+ * moved and the order already records it; a flag that cannot be written must
+ * not fail a refund that has left the merchant's account.
+ */
+export declare function flagOrderRestock(options: {
+    hostId: string;
+    orderId: string;
+    /** Which door the money left by. Only the wording differs. */
+    kind: 'refund' | 'chargeback';
+    /**
+     * True only for the write that moved the order INTO `refunded` — the same
+     * signal `recordContactRefund` takes, decided by the caller from the status
+     * transition it made rather than from the total it read, because
+     * `fullyRefunded` is not a once-only signal (AGL-1754).
+     */
+    closedTheOrder: boolean;
+}): Promise<void>;
+/**
+ * Key for one product+variant pair in a release-cap map.
+ *
+ * The separator is U+0000 written as an ESCAPE, not as a raw byte (AGL-2355).
+ * Emitted literally it made `file(1)` call the source `data`, so grep skipped
+ * the whole file as binary and an AGL-2320 sweep missed a call site in it.
+ * Same character at runtime. NUL is still the right separator: it cannot occur
+ * in a Firestore document id, so no pair can collide.
+ */
+export declare const restockCapKey: (productId: string, variantId: string) => string;
+/**
+ * How many units of each product+variant a sale ACTUALLY took off the shelf,
+ * read from that order's `reason: 'sale'` ledger rows (AGL-2149).
+ *
+ * The variant inventory writer floors at zero, and that floor silently absorbs
+ * the overshoot on a BACKORDER product: stock 0, `canPurchase` admits the sale
+ * because the policy says to, three units sell, `Math.max(0, 0 + -3)` leaves
+ * the count at 0. The rows carry both numbers for exactly this — `delta` stays
+ * the units SOLD, which is the merchant's history, and `appliedDelta` says how
+ * many the count could give up.
+ *
+ * The writer is deliberately NOT named here: `stock-decrement-race.spec.ts`
+ * sweeps every server source for that identifier to prove no file outside its
+ * allowlist hand-rolls a stock write, and it matches the bare name, so even a
+ * comment mentioning it would read as a call site. This module writes no stock
+ * at all — it writes the question.
+ *
+ * Shared by the cancellation writer, which uses it to bound how much stock
+ * goes back, and by the restock flag, which uses it to bound what it CLAIMS
+ * went missing (AGL-2325). Extracted rather than copied: the two must not
+ * drift, because a flag that names more units than the cancellation would
+ * return is the double-count both of them exist to avoid.
+ */
+export declare function saleReleaseCaps(saleRows: readonly {
+    get: (field: string) => unknown;
+}[]): Map<string, number>;
+/**
+ * Lines narrowed to what the count actually gave up, dropping any that gave up
+ * nothing (AGL-2149, AGL-2325).
+ *
+ * ONLY PAIRS THE LEDGER DESCRIBES ARE CAPPED, and that asymmetry is the whole
+ * safety argument. A pair with no row is left at the units it sold, which is
+ * what keeps the pre-AGL-1807 draft links — decremented with no row at all —
+ * and the buy-now path from being silently zeroed by a ledger that has holes
+ * in it. So an absent ledger degrades to the old upper bound rather than to
+ * saying nothing moved.
+ *
+ * The budget is consumed as it is spent, so two lines of the same
+ * product+variant share one rather than each claiming it whole. Takes a COPY,
+ * so a caller may reuse the map it passed.
+ */
+export declare function capRestockLines(lines: readonly CommerceModel.OrderRestockLine[], caps: ReadonlyMap<string, number>): CommerceModel.OrderRestockLine[];
+/** What an order's tracked lines resolved to, with the products behind them. */
+export interface TrackedRestockLines {
+    lines: CommerceModel.OrderRestockLine[];
+    /**
+     * The product doc behind each line, by product id — read once each, and
+     * handed back so a caller that WRITES stock (AGL-1808) does not read them a
+     * second time. Only products that contributed a line appear.
+     */
+    products: Map<string, CommerceModel.HostProduct>;
+}
+/**
+ * The order's lines whose stock the sale actually took off the shelf.
+ *
+ * The test is the sale path's own — `variant.inventory != null` on the variant
+ * that sold — read from the product as it stands NOW, because that is the
+ * count a restock would be applied to. A product deleted since the sale, or a
+ * variant removed from it, therefore drops out: there is no number left to put
+ * anything back into.
+ *
+ * Products are read once each, so a three-line order of the same product costs
+ * one read rather than three.
+ *
+ * `read` is the caller's, and the choice is not cosmetic (AGL-1808): the flag
+ * passes a swallowing `get()` because a product it cannot read must not fail a
+ * refund that already moved, while the cancellation writer passes its
+ * TRANSACTION's `get` so every product it is about to increment is read under
+ * the same transaction that writes it — and so a read failure aborts rather
+ * than quietly shortening the list.
+ */
+export declare function resolveTrackedRestockLines(hostRef: FirebaseFirestore.DocumentReference, order: CommerceModel.HostOrder, read: (ref: FirebaseFirestore.DocumentReference) => Promise<{
+    exists?: boolean;
+    data?: () => unknown;
+} | null>): Promise<TrackedRestockLines>;