@aglyn/tenant-data-admin 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/server/{connect-payout-failure.d.ts → payment-provider-stripe-connect-payouts.d.ts}

@@ -55,6 +55,9 @@
  * the document the merchant and publisher surfaces already read. A card that
  * had to open a second collection would be a second, disagreeing read of the
  * same fact.
+ *
+ * Part of the Stripe Connect payment provider: a plugin reaches it through
+ * the contract's `applyAccountEvent`, never by importing it.
  */
 /** Which leg of the money movement failed. */
 export type ConnectPayoutFailureKind = 'payout' | 'transfer';

package/src/lib/server/{connect-payout-failure.js → payment-provider-stripe-connect-payouts.js}

@@ -139,4 +139,4 @@ function text(value) {
     return cleared;
 }
 
-//# sourceMappingURL=connect-payout-failure.js.map
+//# sourceMappingURL=payment-provider-stripe-connect-payouts.js.map

package/src/lib/server/payment-provider-stripe-connect-payouts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/payment-provider-stripe-connect-payouts.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 { formatOperatorAlertAmount } from '@aglyn/aglyn/app-utils/operator-alerts'\nimport { firebaseAdmin } from './firebase-admin'\nimport { updateExisting } from './update-existing'\n\n/**\n * A PAYOUT THAT NEVER LANDED, RECORDED.\n *\n * ## What was invisible, and to whom\n *\n * Nothing in this codebase handled `payout.failed` or `transfer.failed`. The\n * consequences ran in opposite directions on the two sides of the same money:\n *\n *   - **The merchant** saw a storefront that looked healthy — orders settling,\n *     the payments card reporting enabled — while the funds accumulated in a\n *     Connect account that could not release them. Aglyn stored no balance and\n *     no payout schedule, so nothing in the console could contradict that.\n *   - **The publisher** saw a seller ledger whose payout figure is derived from\n *     `transferCents`, which is what Stripe was ASKED to move. A failed payout\n *     leaves that number untouched, so the ledger actively asserted money had\n *     arrived when it had not.\n *\n * And Aglyn held no record at all, so there was nothing to reconcile against,\n * no history, and no way to answer \"has this happened to this account before\".\n *\n * ## Recorded, surfaced — never retried\n *\n * This module only writes things down. It does NOT re-issue a payout or a\n * transfer, deliberately: Stripe runs its own retry schedule, and a second\n * transfer against an account that has just refused one is how a duplicate\n * lands. A human decides what happens next, which is the same posture the\n * refund-reversal recovery queue takes for the money Stripe refuses to pull\n * back — the sibling family of problem.\n *\n * ## Two records, because they answer different questions\n *\n * `connectPayoutFailures/{stripeId}` is the durable HISTORY, keyed by the\n * Stripe id so a redelivery converges rather than duplicating. It is written\n * even when no profile in the named collection binds the account, because\n * \"money did not arrive and we cannot say whose\" is precisely the state that\n * must not be silent.\n *\n * The profile documents get a MIRROR of the latest failure, because that is\n * the document the merchant and publisher surfaces already read. A card that\n * had to open a second collection would be a second, disagreeing read of the\n * same fact.\n *\n * Part of the Stripe Connect payment provider: a plugin reaches it through\n * the contract's `applyAccountEvent`, never by importing it.\n */\n\n/** Which leg of the money movement failed. */\nexport type ConnectPayoutFailureKind = 'payout' | 'transfer'\n\nexport interface ConnectPayoutFailureInput {\n  /**\n   * `payout` is the connected account's balance reaching its bank, and its\n   * account id comes from `event.account` — the Payout object's own\n   * `destination` is the BANK, not the Connect account. `transfer` is the\n   * platform's balance reaching the connected account, a platform event whose\n   * `destination` IS the account.\n   */\n  kind: ConnectPayoutFailureKind\n  /** `event.data.object` — the Payout or Transfer. */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  object: any\n  /** The connected account the money was headed for. */\n  accountId: string\n  /** `event.livemode`. */\n  livemode?: unknown\n}\n\nfunction cents(value: unknown): number {\n  const amount = Math.round(Number(value ?? 0))\n  return Number.isFinite(amount) ? amount : 0\n}\n\nfunction text(value: unknown): string | null {\n  return typeof value === 'string' && value.trim() ? value.trim() : null\n}\n\n/**\n * The sentence a merchant reads. Stripe's `failure_message` is written for a\n * developer and is often absent, so the code is kept beside it and a missing\n * pair still produces something a human can act on rather than an empty\n * warning that looks like a rendering fault.\n */\nexport function payoutFailureReason(object: unknown): string {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const source = object as any\n  return (\n    text(source?.failure_message) ??\n    text(source?.failure_code) ??\n    'Stripe did not say why'\n  )\n}\n\n/**\n * Records one failed payout or transfer, and mirrors it onto the profiles in\n * `collection` that bind the account.\n *\n * @returns how many profile documents were mirrored onto. `0` is an ordinary\n *   answer — the other plugin's collection binds this account, or nothing\n *   does — and never means the failure went unrecorded.\n */\nexport async function recordConnectPayoutFailure(\n  collection: string,\n  input: ConnectPayoutFailureInput,\n): Promise<number> {\n  const accountId = String(input?.accountId ?? '').trim()\n  const stripeId = text(input?.object?.id)\n  if (!accountId || !stripeId) return 0\n  const firestore = firebaseAdmin.app().firestore()\n  const amountCents = cents(input.object?.amount)\n  const reason = payoutFailureReason(input.object)\n  const failedAtMs = Date.now()\n\n  const matches = await firestore\n    .collection(collection)\n    .where('stripeAccountId', '==', accountId)\n    .get()\n\n  // The durable record FIRST, and unconditionally. An account no profile binds\n  // is the case with the least visibility and the most need of a written\n  // trace; making the history conditional on a successful join would lose\n  // exactly the failures nobody could otherwise explain.\n  await firestore\n    .collection('connectPayoutFailures')\n    .doc(stripeId)\n    .set(\n      {\n        kind: input.kind,\n        accountId,\n        amountCents,\n        currency: text(input.object?.currency) ?? 'usd',\n        failureCode: text(input.object?.failure_code),\n        failureMessage: text(input.object?.failure_message),\n        reason,\n        failedAtMs,\n        ...(typeof input.livemode === 'boolean'\n          ? { livemode: input.livemode }\n          : {}),\n        // A lead a human can search, accumulated across both plugins: the same\n        // account can be bound by a storefront profile and a publisher profile,\n        // and each plugin records only its own.\n        ...(matches.docs.length\n          ? {\n              boundProfiles: firebaseAdmin.firestore.FieldValue.arrayUnion(\n                ...matches.docs.map((doc) => `${collection}/${doc.id}`),\n              ),\n            }\n          : {}),\n        recordedAt: firebaseAdmin.firestore.FieldValue.serverTimestamp(),\n      },\n      { merge: true },\n    )\n\n  // Money due to a merchant or seller did not arrive, and a human decides\n  // what happens next (AGL-3377). Loaded lazily, like everything this module\n  // only needs once a failure is real.\n  const { raiseOperatorAlert } = await import('./operator-alerts')\n  await raiseOperatorAlert('billing.connectPayoutFailed', {\n    dedupeKey: stripeId,\n    context: {\n      kind: input.kind,\n      stripeId,\n      account: accountId,\n      reason,\n      amount: formatOperatorAlertAmount(amountCents, text(input.object?.currency) ?? 'usd'),\n    },\n  })\n\n  // `updateExisting` rather than a merge-set, for the reason its sibling\n  // states: the refs come from a query, and a merge-set would resurrect a\n  // profile erased in between as a stub holding nothing but a payout warning.\n  let mirrored = 0\n  for (const doc of matches.docs) {\n    if (\n      await updateExisting(doc.ref, {\n        lastPayoutFailureId: stripeId,\n        lastPayoutFailureKind: input.kind,\n        lastPayoutFailureAtMs: failedAtMs,\n        lastPayoutFailureCents: amountCents,\n        lastPayoutFailureReason: reason,\n      })\n    ) {\n      mirrored += 1\n    }\n  }\n  return mirrored\n}\n\n/**\n * Clears the mirrored warning when a later payout to the same account\n * succeeds.\n *\n * NOT a retry and not a correction of the history: `connectPayoutFailures`\n * keeps every failure, because \"has this account failed before\" is a question\n * the record exists to answer. This only stops the merchant's card asserting a\n * problem that has since resolved — a stale warning trains people to ignore\n * the surface, which costs more than it saves.\n */\nexport async function clearConnectPayoutFailure(\n  collection: string,\n  accountId: string,\n): Promise<number> {\n  const id = String(accountId ?? '').trim()\n  if (!id) return 0\n  const firestore = firebaseAdmin.app().firestore()\n  const matches = await firestore\n    .collection(collection)\n    .where('stripeAccountId', '==', id)\n    .get()\n  let cleared = 0\n  for (const doc of matches.docs) {\n    // Only touch a profile that actually carries a warning, so an ordinary\n    // successful payout does not write to every profile on every event.\n    if (doc.get('lastPayoutFailureAtMs') == null) continue\n    const remove = firebaseAdmin.firestore.FieldValue.delete()\n    if (\n      await updateExisting(doc.ref, {\n        lastPayoutFailureId: remove,\n        lastPayoutFailureKind: remove,\n        lastPayoutFailureAtMs: remove,\n        lastPayoutFailureCents: remove,\n        lastPayoutFailureReason: remove,\n      })\n    ) {\n      cleared += 1\n    }\n  }\n  return cleared\n}\n"],"names":["formatOperatorAlertAmount","firebaseAdmin","updateExisting","cents","value","amount","Math","round","Number","isFinite","text","trim","payoutFailureReason","object","source","failure_message","failure_code","recordConnectPayoutFailure","collection","input","accountId","String","stripeId","id","firestore","app","amountCents","reason","failedAtMs","Date","now","matches","where","get","doc","set","kind","currency","failureCode","failureMessage","livemode","docs","length","boundProfiles","FieldValue","arrayUnion","map","recordedAt","serverTimestamp","merge","raiseOperatorAlert","dedupeKey","context","account","mirrored","ref","lastPayoutFailureId","lastPayoutFailureKind","lastPayoutFailureAtMs","lastPayoutFailureCents","lastPayoutFailureReason","clearConnectPayoutFailure","cleared","remove","delete"],"mappings":"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"}

package/src/lib/server/{connect-account-status.d.ts → payment-provider-stripe-connect-status.d.ts}

@@ -47,6 +47,9 @@
  * IDEMPOTENT AND ORDER-INDEPENDENT by construction — it mirrors current state,
  * never a delta — so a Stripe redelivery and an out-of-order pair both
  * converge.
+ *
+ * Part of the Stripe Connect payment provider: a plugin reaches it through
+ * the contract's `applyAccountEvent`, never by importing it.
  */
 export interface ConnectAccountStatusEvent {
     /** `event.data.object` for `account.updated` — the Stripe Account. */

package/src/lib/server/{connect-account-status.js → payment-provider-stripe-connect-status.js}

@@ -91,4 +91,4 @@ import { updateExisting } from "./update-existing.js";
     return updated;
 }
 
-//# sourceMappingURL=connect-account-status.js.map
+//# sourceMappingURL=payment-provider-stripe-connect-status.js.map

package/src/lib/server/payment-provider-stripe-connect-status.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/payment-provider-stripe-connect-status.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 { firebaseAdmin } from './firebase-admin'\nimport { sendGa4StripeConnected } from './ga4-measurement-protocol'\nimport { updateExisting } from './update-existing'\n\n/**\n * Connect readiness, refreshed from Stripe rather than from a cached flag\n * (AGL-1997).\n *\n * `stripeChargesEnabled` is the field every money route gates on — commerce\n * checkout, cart checkout, draft orders, reservations, POS — and until this it\n * was refreshed ONLY when the merchant happened to reopen the Connect route.\n * So an account Stripe later restricts (a verification deadline passing, a\n * capability revoked, documents going stale) kept a cached `true`, the store\n * kept selling, and the failure surfaced to the SHOPPER at payment time. The\n * merchant, who could have fixed it, was the last to know.\n *\n * `account.updated` is the event that carries this. Stripe sends it on every\n * change to a connected account, which is why the fix is a subscription and\n * not a poll.\n *\n * WHY IT WRITES ONLY WHAT STRIPE ACTUALLY SAID. Both flags are written only\n * when the payload states them as booleans. Coercing an absent field with\n * `Boolean(...)` would manufacture a `false` and lock out a merchant who is\n * fine — the over-restrictive direction, but still a wrong answer invented\n * from no evidence — and defaulting the other way would re-create the very\n * fail-open this closes. An event that states neither flag writes nothing at\n * all; it is not an Account payload.\n *\n * WHY `updateExisting` AND NOT A MERGE-SET. The refs come from a query, so the\n * documents existed a moment ago — but a merge-set would resurrect one erased\n * in between as a stub holding two payout booleans and nothing else, the\n * AGL-1763 phantom shape. `update()` rejects instead, and a rejection here\n * costs nothing: the next `account.updated` re-delivers the same state.\n *\n * IDEMPOTENT AND ORDER-INDEPENDENT by construction — it mirrors current state,\n * never a delta — so a Stripe redelivery and an out-of-order pair both\n * converge.\n *\n * Part of the Stripe Connect payment provider: a plugin reaches it through\n * the contract's `applyAccountEvent`, never by importing it.\n */\nexport interface ConnectAccountStatusEvent {\n  /** `event.data.object` for `account.updated` — the Stripe Account. */\n  id?: unknown\n  charges_enabled?: unknown\n  payouts_enabled?: unknown\n}\n\n/**\n * Mirrors a connected account's charge/payout readiness onto whichever\n * documents in `collection` name it in `stripeAccountId`.\n *\n * @param eventLivemode `event.livemode` from the enclosing `account.updated`\n *   event (AGL-2471) — NOT `event.data.object.livemode`, which Stripe's\n *   Account object does not have. Anything other than a boolean writes\n *   nothing, leaving the field absent, which every money gate reads as\n *   unverified and refuses.\n * @param collection Firestore collection holding the payout binding —\n *   `profiles` for storefront merchants, `publisherProfiles` for marketplace\n *   publishers. Each plugin syncs its own; a non-matching account updates\n *   nothing.\n * @returns the number of documents updated. 0 is the ordinary answer for an\n *   account this collection does not bind, and the caller should not treat it\n *   as a failure.\n */\nexport async function syncConnectAccountStatus(\n  collection: string,\n  account: ConnectAccountStatusEvent | null | undefined,\n  eventLivemode?: unknown,\n): Promise<number> {\n  const accountId = typeof account?.id === 'string' ? account.id.trim() : ''\n  if (!accountId) return 0\n  const patch: Record<string, boolean> = {}\n  if (typeof account?.charges_enabled === 'boolean') {\n    patch['stripeChargesEnabled'] = account.charges_enabled\n  }\n  if (typeof account?.payouts_enabled === 'boolean') {\n    patch['stripePayoutsEnabled'] = account.payouts_enabled\n  }\n  // WHICH STRIPE WORLD (AGL-2471). The Account object has no `livemode`, but\n  // the EVENT carrying it does, and it is Stripe's own statement about the\n  // account being described — the strongest evidence available, and it\n  // arrives on every change. This is what heals a linkage whose mode was\n  // never recorded, without anyone touching the database by hand.\n  //\n  // Same doctrine as the two flags above: only a literal boolean is written.\n  if (typeof eventLivemode === 'boolean') {\n    patch['stripeAccountLivemode'] = eventLivemode\n  }\n  // Nothing stated, nothing written — see the doc comment.\n  if (!Object.keys(patch).length) return 0\n\n  const matches = await firebaseAdmin\n    .app()\n    .firestore()\n    .collection(collection)\n    .where('stripeAccountId', '==', accountId)\n    .get()\n  let updated = 0\n  for (const doc of matches.docs) {\n    // THE ACTIVATION TRANSITION, read BEFORE the write (AGL-1580).\n    //\n    // `stripe_connected` is one of the launch key events, and its two\n    // client-side emitters are gated on the merchant's profile still reading\n    // \"not connected\" when they click. This webhook is what makes that false:\n    // it lands while the merchant is still on Stripe's hosted onboarding, so\n    // the flag has already flipped by the time they get back and the browser\n    // event can never fire. See `sendGa4StripeConnected` for why the two\n    // guards cannot both open for the same account.\n    //\n    // `!== true` and not `=== false`: a profile that has never been asked has\n    // the field ABSENT, and that is the commonest first-connect shape of all.\n    const becameConnected =\n      patch['stripeChargesEnabled'] === true &&\n      doc.get('stripeChargesEnabled') !== true\n    // `updateExisting` rethrows anything that is not \"the document is gone\",\n    // so a permission or transport failure still reaches the webhook and gets\n    // the redelivery it needs.\n    if (await updateExisting(doc.ref, patch)) {\n      updated += 1\n      // Reported only after the write LANDED. A document erased between the\n      // query and the update is not an activation, and reporting one would\n      // put a merchant in the metric who no longer exists.\n      //\n      // Awaited, not floated: this runs inside the Stripe webhook's claim on\n      // the event, and a floated promise in a serverless handler is frozen at\n      // response and never runs — the AGL-2346 shape. The sender swallows\n      // everything and cannot un-claim the event by throwing.\n      if (becameConnected) await sendGa4StripeConnected({ accountId })\n    }\n  }\n  return updated\n}\n"],"names":["firebaseAdmin","sendGa4StripeConnected","updateExisting","syncConnectAccountStatus","collection","account","eventLivemode","accountId","id","trim","patch","charges_enabled","payouts_enabled","Object","keys","length","matches","app","firestore","where","get","updated","doc","docs","becameConnected","ref"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,aAAa,QAAQ,sBAAkB;AAChD,SAASC,sBAAsB,QAAQ,gCAA4B;AACnE,SAASC,cAAc,QAAQ,uBAAmB;AA8ClD;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,eAAeC,yBACpBC,UAAkB,EAClBC,OAAqD,EACrDC,aAAuB;IAEvB,MAAMC,YAAY,QAAOF,2BAAAA,QAASG,EAAE,MAAK,WAAWH,QAAQG,EAAE,CAACC,IAAI,KAAK;IACxE,IAAI,CAACF,WAAW,OAAO;IACvB,MAAMG,QAAiC,CAAC;IACxC,IAAI,QAAOL,2BAAAA,QAASM,eAAe,MAAK,WAAW;QACjDD,KAAK,CAAC,uBAAuB,GAAGL,QAAQM,eAAe;IACzD;IACA,IAAI,QAAON,2BAAAA,QAASO,eAAe,MAAK,WAAW;QACjDF,KAAK,CAAC,uBAAuB,GAAGL,QAAQO,eAAe;IACzD;IACA,2EAA2E;IAC3E,yEAAyE;IACzE,qEAAqE;IACrE,uEAAuE;IACvE,gEAAgE;IAChE,EAAE;IACF,2EAA2E;IAC3E,IAAI,OAAON,kBAAkB,WAAW;QACtCI,KAAK,CAAC,wBAAwB,GAAGJ;IACnC;IACA,yDAAyD;IACzD,IAAI,CAACO,OAAOC,IAAI,CAACJ,OAAOK,MAAM,EAAE,OAAO;IAEvC,MAAMC,UAAU,MAAMhB,cACnBiB,GAAG,GACHC,SAAS,GACTd,UAAU,CAACA,YACXe,KAAK,CAAC,mBAAmB,MAAMZ,WAC/Ba,GAAG;IACN,IAAIC,UAAU;IACd,KAAK,MAAMC,OAAON,QAAQO,IAAI,CAAE;QAC9B,+DAA+D;QAC/D,EAAE;QACF,kEAAkE;QAClE,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,yEAAyE;QACzE,qEAAqE;QACrE,gDAAgD;QAChD,EAAE;QACF,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAMC,kBACJd,KAAK,CAAC,uBAAuB,KAAK,QAClCY,IAAIF,GAAG,CAAC,4BAA4B;QACtC,yEAAyE;QACzE,0EAA0E;QAC1E,2BAA2B;QAC3B,IAAI,MAAMlB,eAAeoB,IAAIG,GAAG,EAAEf,QAAQ;YACxCW,WAAW;YACX,sEAAsE;YACtE,qEAAqE;YACrE,qDAAqD;YACrD,EAAE;YACF,uEAAuE;YACvE,wEAAwE;YACxE,oEAAoE;YACpE,wDAAwD;YACxD,IAAIG,iBAAiB,MAAMvB,uBAAuB;gBAAEM;YAAU;QAChE;IACF;IACA,OAAOc;AACT"}

package/src/lib/server/{stripe-account-mode.d.ts → payment-provider-stripe-connect.d.ts}

@@ -14,8 +14,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { PaymentMode, PaymentProvider, PaymentProviderEvent } from './payment-provider';
 /**
- * Whether a stored Connect linkage can actually take money HERE (AGL-2471).
+ * The Stripe Connect adapter behind the payment-provider contract
+ * (`payment-provider.ts`): a tenant's merchant account is a Stripe Connect
+ * account, charged and paid out through the platform's Stripe key.
+ *
+ * This module is the part that is Stripe's — which mode a key states, how the
+ * API is asked, which webhook events describe a connected account and where
+ * each one keeps the account id. What an event WRITES lives in the two modules
+ * it dispatches to, loaded only when such an event arrives, so the money doors
+ * that import the contract for its readiness rule load no Firebase.
+ *
+ * ## Whether a stored Connect linkage can actually take money HERE (AGL-2471)
  *
  * THE DEFECT. Production Firestore held three Connect linkages and all three
  * named TEST-mode accounts. One — `profiles/7AVEMtDa…`, `stripeAccountId:
@@ -50,20 +61,10 @@
  *      (above), so the account's mode IS the key's mode; the key's mode is
  *      then confirmed against the API via `resolvePlatformStripeMode`.
  *
- * WHY THE RULE IS ASYMMETRIC, AND NOT "REFUSE ANYTHING UNPROVEN". An absent
- * `stripeAccountLivemode` refuses only on a LIVE deployment. That is where
- * real money moves and where the defect was found, and a live deployment can
- * always re-establish the field: the merchant reconnects, or Stripe sends one
- * `account.updated`. Everywhere else — a test-key deployment, a developer
- * machine, a self-hosted install still in sandbox, the whole test suite — an
- * unverified linkage keeps the behaviour it had before, because no real money
- * can move there and Stripe enforces the mode boundary itself. Refusing
- * everywhere would have bought production nothing extra and broken every
- * non-production deployment.
- *
- * A PROVEN mismatch (`stripeAccountLivemode` recorded and disagreeing) is
- * refused in BOTH directions, because that costs nothing to detect and is
- * never right.
+ * The profile field is `stripeAccountLivemode`, and the rule that reads it —
+ * refused on a live deployment when absent, refused in both directions when
+ * it disagrees — is the contract's `merchantAccountReadiness`, which says why
+ * it is asymmetric.
  *
  * WHAT IS SNIFFED, AND WHY THAT ONE IS FAIR. The SECRET KEY states its own
  * mode — `sk_live_`, `sk_test_`, `rk_live_`, `rk_test_` — and that is a
@@ -80,40 +81,6 @@
  * change — the split key is the right call — so the gate has to be the thing
  * that notices.
  */
-/** Which Stripe world a key or an account belongs to. */
-export type StripeMode = 'live' | 'test';
-/**
- * Why a stored linkage may not be charged against. Every value other than
- * `'ready'` is a refusal, and the mode ones are refusals the old two-field
- * test could not make.
- */
-export type ConnectReadiness = 
-/** Charge away. */
-'ready'
-/** No Connect account is stored at all — the onboarding call to action. */
- | 'not-connected'
-/** Stripe will not let this account take charges. */
- | 'charges-disabled'
-/**
- * The linkage predates AGL-2471 (or was written by something that did not
- * record mode), so its mode was never established — AND this deployment is
- * LIVE. This is the shape all three poisoned production records have.
- * The connect route and the `account.updated` sync both write the field, so
- * a genuine merchant self-heals on the next of either.
- */
- | 'mode-unverified'
-/** The account belongs to the OTHER Stripe world. The AGL-2471 defect. */
- | 'mode-mismatch';
-export interface ConnectReadinessInput {
-    /** `stripeAccountId` off the profile, whatever shape the document has. */
-    accountId?: unknown;
-    /** `stripeChargesEnabled` off the profile. */
-    chargesEnabled?: unknown;
-    /** `stripeAccountLivemode` off the profile — absent before AGL-2471. */
-    accountLivemode?: unknown;
-    /** Defaults to the mode of `STRIPE_SECRET_KEY`. */
-    platformMode?: StripeMode | undefined;
-}
 /**
  * The mode a Stripe secret key states about itself, or `undefined` when the
  * string is not a Stripe secret key.
@@ -122,7 +89,7 @@ export interface ConnectReadinessInput {
  * refuses everything else rather than guessing. Handing it an `acct_…` id
  * returns `undefined` — the whole point is that account ids say nothing.
  */
-export declare function platformStripeMode(key?: string | undefined): StripeMode | undefined;
+export declare function platformStripeMode(key?: string | undefined): PaymentMode | undefined;
 /**
  * The platform's mode, asked of Stripe and only then of the key.
  *
@@ -132,25 +99,33 @@ export declare function platformStripeMode(key?: string | undefined): StripeMode
  * balance; without it, a self-hosted install with a scoped key could not
  * finish onboarding at all.
  */
-export declare function resolvePlatformStripeMode(key?: string | undefined, fetchImpl?: typeof fetch): Promise<StripeMode | undefined>;
+export declare function resolvePlatformStripeMode(key?: string | undefined, fetchImpl?: typeof fetch): Promise<PaymentMode | undefined>;
 /**
- * Decides whether a stored Connect linkage may be charged against.
- *
- * Order matters: the two refusals that existed before AGL-2471 are asked
- * first, so an unconnected or restricted merchant still gets the answer they
- * always got, and only a linkage that WOULD have passed reaches the mode
- * question.
- */
-export declare function connectReadiness(input: ConnectReadinessInput): ConnectReadiness;
-/**
- * The form every money door calls: `true` only when the linkage may be
- * charged, with the two mode refusals reported to the server log.
- *
- * The log line is the part the shopper's generic 409 cannot carry. Before
- * this, a mode mismatch surfaced as a 502 from Stripe with nothing anywhere
- * naming the cause; the sale is still refused the same way, but now somebody
- * can find out why.
+ * A Stripe webhook event about a connected account, applied to the profiles in
+ * `collection` that store it — the contract's `applyAccountEvent`.
+ *
+ * Three events describe a connected account, and each keeps the account id
+ * somewhere different:
+ *
+ *  - `account.updated` — its readiness changed (AGL-1997). The object IS the
+ *    Account, and the EVENT carries `livemode` (AGL-2471): the Account object
+ *    has no such field, and the event's is what lets a linkage whose mode was
+ *    never recorded heal itself instead of staying refused forever.
+ *  - `payout.failed` / `transfer.failed` — money headed for the account never
+ *    landed. A payout is the connected account's balance failing to reach its
+ *    bank, so its account id is `event.account`: the Payout's own
+ *    `destination` names the BANK. A transfer is the platform's balance
+ *    failing to reach the connected account, a platform event whose
+ *    `destination` IS the account. Recorded and surfaced, never retried:
+ *    Stripe runs its own retry schedule, and a second transfer against an
+ *    account that has just refused one is how a duplicate lands.
+ *  - `payout.paid` — a later payout landed, which retires the warning the
+ *    failure left on the profile. The history is kept.
+ *
+ * Every other event answers `false` without loading anything. A write that
+ * fails throws, and the webhook's 500 earns the redelivery; every write
+ * mirrors current state or is keyed by Stripe's id, so a redelivery converges.
  */
-export declare function connectLinkageIsReady(input: ConnectReadinessInput, context?: {
-    subject?: string;
-}): boolean;
+export declare function applyStripeConnectAccountEvent(collection: string, delivered: PaymentProviderEvent): Promise<boolean>;
+/** The adapter the contract returns. */
+export declare const STRIPE_CONNECT_PAYMENT_PROVIDER: PaymentProvider;

package/src/lib/server/{stripe-account-mode.js → payment-provider-stripe-connect.js}

@@ -14,7 +14,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ /**
- * Whether a stored Connect linkage can actually take money HERE (AGL-2471).
+ * The Stripe Connect adapter behind the payment-provider contract
+ * (`payment-provider.ts`): a tenant's merchant account is a Stripe Connect
+ * account, charged and paid out through the platform's Stripe key.
+ *
+ * This module is the part that is Stripe's — which mode a key states, how the
+ * API is asked, which webhook events describe a connected account and where
+ * each one keeps the account id. What an event WRITES lives in the two modules
+ * it dispatches to, loaded only when such an event arrives, so the money doors
+ * that import the contract for its readiness rule load no Firebase.
+ *
+ * ## Whether a stored Connect linkage can actually take money HERE (AGL-2471)
  *
  * THE DEFECT. Production Firestore held three Connect linkages and all three
  * named TEST-mode accounts. One — `profiles/7AVEMtDa…`, `stripeAccountId:
@@ -49,20 +59,10 @@
  *      (above), so the account's mode IS the key's mode; the key's mode is
  *      then confirmed against the API via `resolvePlatformStripeMode`.
  *
- * WHY THE RULE IS ASYMMETRIC, AND NOT "REFUSE ANYTHING UNPROVEN". An absent
- * `stripeAccountLivemode` refuses only on a LIVE deployment. That is where
- * real money moves and where the defect was found, and a live deployment can
- * always re-establish the field: the merchant reconnects, or Stripe sends one
- * `account.updated`. Everywhere else — a test-key deployment, a developer
- * machine, a self-hosted install still in sandbox, the whole test suite — an
- * unverified linkage keeps the behaviour it had before, because no real money
- * can move there and Stripe enforces the mode boundary itself. Refusing
- * everywhere would have bought production nothing extra and broken every
- * non-production deployment.
- *
- * A PROVEN mismatch (`stripeAccountLivemode` recorded and disagreeing) is
- * refused in BOTH directions, because that costs nothing to detect and is
- * never right.
+ * The profile field is `stripeAccountLivemode`, and the rule that reads it —
+ * refused on a live deployment when absent, refused in both directions when
+ * it disagrees — is the contract's `merchantAccountReadiness`, which says why
+ * it is asymmetric.
  *
  * WHAT IS SNIFFED, AND WHY THAT ONE IS FAIR. The SECRET KEY states its own
  * mode — `sk_live_`, `sk_test_`, `rk_live_`, `rk_test_` — and that is a
@@ -78,7 +78,7 @@
  * and writes it into the production database. Nothing about that is going to
  * change — the split key is the right call — so the gate has to be the thing
  * that notices.
- */ /** Which Stripe world a key or an account belongs to. */ /**
+ */ /**
  * The mode a Stripe secret key states about itself, or `undefined` when the
  * string is not a Stripe secret key.
  *
@@ -120,43 +120,69 @@
     return fromKey;
 }
 /**
- * Decides whether a stored Connect linkage may be charged against.
- *
- * Order matters: the two refusals that existed before AGL-2471 are asked
- * first, so an unconnected or restricted merchant still gets the answer they
- * always got, and only a linkage that WOULD have passed reaches the mode
- * question.
- */ export function connectReadiness(input) {
-    const accountId = typeof input.accountId === 'string' ? input.accountId.trim() : '';
-    if (!accountId) return 'not-connected';
-    if (input.chargesEnabled !== true) return 'charges-disabled';
-    const platformMode = 'platformMode' in input ? input.platformMode : platformStripeMode();
-    // Three-valued on purpose, exactly as AGL-1997 reads `payoutsEnabled`: only
-    // a literal boolean is a recorded answer. A string `'true'` or a `1` is a
-    // field somebody else wrote, and inventing `true` from it would re-open the
-    // hole this closes.
-    if (typeof input.accountLivemode === 'boolean') {
-        // A PROVEN mismatch is refused in either direction. It costs nothing to
-        // detect and it is always wrong.
-        if (!platformMode) return 'ready';
-        return input.accountLivemode === (platformMode === 'live') ? 'ready' : 'mode-mismatch';
+ * A Stripe webhook event about a connected account, applied to the profiles in
+ * `collection` that store it — the contract's `applyAccountEvent`.
+ *
+ * Three events describe a connected account, and each keeps the account id
+ * somewhere different:
+ *
+ *  - `account.updated` — its readiness changed (AGL-1997). The object IS the
+ *    Account, and the EVENT carries `livemode` (AGL-2471): the Account object
+ *    has no such field, and the event's is what lets a linkage whose mode was
+ *    never recorded heal itself instead of staying refused forever.
+ *  - `payout.failed` / `transfer.failed` — money headed for the account never
+ *    landed. A payout is the connected account's balance failing to reach its
+ *    bank, so its account id is `event.account`: the Payout's own
+ *    `destination` names the BANK. A transfer is the platform's balance
+ *    failing to reach the connected account, a platform event whose
+ *    `destination` IS the account. Recorded and surfaced, never retried:
+ *    Stripe runs its own retry schedule, and a second transfer against an
+ *    account that has just refused one is how a duplicate lands.
+ *  - `payout.paid` — a later payout landed, which retires the warning the
+ *    failure left on the profile. The history is kept.
+ *
+ * Every other event answers `false` without loading anything. A write that
+ * fails throws, and the webhook's 500 earns the redelivery; every write
+ * mirrors current state or is keyed by Stripe's id, so a redelivery converges.
+ */ export async function applyStripeConnectAccountEvent(collection, delivered) {
+    const type = delivered == null ? void 0 : delivered.type;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const object = delivered == null ? void 0 : delivered.object;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const event = delivered == null ? void 0 : delivered.event;
+    if (type === 'account.updated') {
+        const { syncConnectAccountStatus } = await import("./payment-provider-stripe-connect-status.js");
+        await syncConnectAccountStatus(collection, object, event == null ? void 0 : event.livemode);
+        return true;
     }
-    return platformMode === 'live' ? 'mode-unverified' : 'ready';
-}
-/**
- * The form every money door calls: `true` only when the linkage may be
- * charged, with the two mode refusals reported to the server log.
- *
- * The log line is the part the shopper's generic 409 cannot carry. Before
- * this, a mode mismatch surfaced as a 502 from Stripe with nothing anywhere
- * naming the cause; the sale is still refused the same way, but now somebody
- * can find out why.
- */ export function connectLinkageIsReady(input, context) {
-    const readiness = connectReadiness(input);
-    if (readiness === 'mode-mismatch' || readiness === 'mode-unverified') {
-        console.error(`[AGL-2471] Refusing a charge against Connect account ` + `${String(input.accountId)}${(context == null ? void 0 : context.subject) ? ` (${context.subject})` : ''}: ${readiness}. The stored linkage is not verified for this ` + `deployment's Stripe mode; the merchant must re-onboard.`);
+    if (type === 'payout.failed' || type === 'transfer.failed') {
+        var _ref, _ref1, _ref2;
+        var _object_destination;
+        const failedAccountId = type === 'payout.failed' ? String((_ref = event == null ? void 0 : event.account) != null ? _ref : '') : String((_ref1 = (_ref2 = object == null ? void 0 : (_object_destination = object.destination) == null ? void 0 : _object_destination.id) != null ? _ref2 : object == null ? void 0 : object.destination) != null ? _ref1 : '');
+        const { recordConnectPayoutFailure } = await import("./payment-provider-stripe-connect-payouts.js");
+        await recordConnectPayoutFailure(collection, {
+            kind: type === 'payout.failed' ? 'payout' : 'transfer',
+            object,
+            accountId: failedAccountId,
+            livemode: event == null ? void 0 : event.livemode
+        });
+        return true;
+    }
+    if (type === 'payout.paid') {
+        var _ref3;
+        const { clearConnectPayoutFailure } = await import("./payment-provider-stripe-connect-payouts.js");
+        await clearConnectPayoutFailure(collection, String((_ref3 = event == null ? void 0 : event.account) != null ? _ref3 : ''));
+        return true;
     }
-    return readiness === 'ready';
+    return false;
 }
+/** The adapter the contract returns. */ export const STRIPE_CONNECT_PAYMENT_PROVIDER = {
+    id: 'stripe-connect',
+    // Called with no argument, so the key is read when asked — not when this
+    // module was first evaluated.
+    platformMode: ()=>platformStripeMode(),
+    resolvePlatformMode: ()=>resolvePlatformStripeMode(),
+    applyAccountEvent: applyStripeConnectAccountEvent
+};
 
-//# sourceMappingURL=stripe-account-mode.js.map
+//# sourceMappingURL=payment-provider-stripe-connect.js.map

package/src/lib/server/payment-provider-stripe-connect.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/payment-provider-stripe-connect.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 { PaymentMode, PaymentProvider, PaymentProviderEvent } from './payment-provider'\n\n/**\n * The Stripe Connect adapter behind the payment-provider contract\n * (`payment-provider.ts`): a tenant's merchant account is a Stripe Connect\n * account, charged and paid out through the platform's Stripe key.\n *\n * This module is the part that is Stripe's — which mode a key states, how the\n * API is asked, which webhook events describe a connected account and where\n * each one keeps the account id. What an event WRITES lives in the two modules\n * it dispatches to, loaded only when such an event arrives, so the money doors\n * that import the contract for its readiness rule load no Firebase.\n *\n * ## Whether a stored Connect linkage can actually take money HERE (AGL-2471)\n *\n * THE DEFECT. Production Firestore held three Connect linkages and all three\n * named TEST-mode accounts. One — `profiles/7AVEMtDa…`, `stripeAccountId:\n * acct_1TulDeRbL3B9Ioqz` — also carried `stripeChargesEnabled: true`, which\n * was the entire payments-readiness test every money door made:\n *\n *     if (!accountId || !ownerProfile.get('stripeChargesEnabled')) …\n *\n * So three storefronts presented as payments-ready, minted a LIVE Checkout\n * session with a TEST-mode `payment_intent_data[transfer_data][destination]`,\n * and were refused by Stripe as a generic 502 at the shopper's checkout. A\n * merchant told they are ready to take money, who silently cannot.\n *\n * WHY THE ACCOUNT ID IS NOT THE EVIDENCE. `acct_1TulDeRbL3B9Ioqz` is a real\n * production value naming a TEST account. Stripe's account ids carry no mode\n * marker — live and test ids are the same shape — so no amount of reading the\n * string can tell them apart. What DOES tell them apart is Stripe itself:\n * retrieving that id with the live key answers\n *\n *     400 The account acct_1TulDeRbL3B9Ioqz was a test account created with a\n *         testmode key, and therefore can only be used with testmode keys.\n *\n * The Account object, notably, has NO `livemode` field of its own (verified\n * against the live API: the payload carries `charges_enabled`,\n * `payouts_enabled`, `capabilities` and no `livemode`). So the mode is\n * recorded at the two moments Stripe does state it:\n *\n *   1. `account.updated` — the EVENT carries `livemode`, and it is Stripe's\n *      own statement about the account the event is describing;\n *   2. onboarding — the account was just created or retrieved successfully\n *      with the platform key, and Stripe hard-refuses cross-mode retrieval\n *      (above), so the account's mode IS the key's mode; the key's mode is\n *      then confirmed against the API via `resolvePlatformStripeMode`.\n *\n * The profile field is `stripeAccountLivemode`, and the rule that reads it —\n * refused on a live deployment when absent, refused in both directions when\n * it disagrees — is the contract's `merchantAccountReadiness`, which says why\n * it is asymmetric.\n *\n * WHAT IS SNIFFED, AND WHY THAT ONE IS FAIR. The SECRET KEY states its own\n * mode — `sk_live_`, `sk_test_`, `rk_live_`, `rk_test_` — and that is a\n * documented, stable Stripe invariant, unlike the account id. It is used only\n * to answer \"which mode is this deployment\", never \"which mode is this\n * account\", and even there `resolvePlatformStripeMode` prefers the API.\n *\n * HOW IT GOT THERE. A developer machine runs against PRODUCTION Firestore\n * (`FIREBASE_PROJECT_ID=aglyn-main` in every dev env file) while\n * `apps/console/.env.development.local` sets `STRIPE_SECRET_KEY` to the\n * `sk_test_` key by deliberate policy (AGL-1137: localhost must never touch\n * live Stripe). The connect route then creates a test-mode Express account\n * and writes it into the production database. Nothing about that is going to\n * change — the split key is the right call — so the gate has to be the thing\n * that notices.\n */\n\n/**\n * The mode a Stripe secret key states about itself, or `undefined` when the\n * string is not a Stripe secret key.\n *\n * Deliberately narrow: it matches `sk_`/`rk_` followed by `live`/`test`, and\n * refuses everything else rather than guessing. Handing it an `acct_…` id\n * returns `undefined` — the whole point is that account ids say nothing.\n */\nexport function platformStripeMode(\n  key: string | undefined = process.env.STRIPE_SECRET_KEY,\n): PaymentMode | undefined {\n  const match = /^[sr]k_(live|test)_/.exec(String(key ?? '').trim())\n  return match ? (match[1] as PaymentMode) : undefined\n}\n\n/**\n * The platform's mode, asked of Stripe and only then of the key.\n *\n * `GET /v1/balance` is a singleton that carries `livemode`, so it states the\n * mode of whatever key made the call — no object has to be created to find\n * out. The key prefix is the fallback for a restricted key that cannot read\n * balance; without it, a self-hosted install with a scoped key could not\n * finish onboarding at all.\n */\nexport async function resolvePlatformStripeMode(\n  key: string | undefined = process.env.STRIPE_SECRET_KEY,\n  fetchImpl: typeof fetch = fetch,\n): Promise<PaymentMode | undefined> {\n  const fromKey = platformStripeMode(key)\n  if (!key) return fromKey\n  try {\n    const response = await fetchImpl('https://api.stripe.com/v1/balance', {\n      method: 'GET',\n      headers: { Authorization: `Bearer ${key}` },\n    })\n    if (response.ok) {\n      const payload = await response.json()\n      if (typeof payload?.livemode === 'boolean') {\n        return payload.livemode ? 'live' : 'test'\n      }\n    }\n  } catch {\n    // Network or transport failure — fall through to the key, which is the\n    // same answer we would have recorded before this existed.\n  }\n  return fromKey\n}\n\n/**\n * A Stripe webhook event about a connected account, applied to the profiles in\n * `collection` that store it — the contract's `applyAccountEvent`.\n *\n * Three events describe a connected account, and each keeps the account id\n * somewhere different:\n *\n *  - `account.updated` — its readiness changed (AGL-1997). The object IS the\n *    Account, and the EVENT carries `livemode` (AGL-2471): the Account object\n *    has no such field, and the event's is what lets a linkage whose mode was\n *    never recorded heal itself instead of staying refused forever.\n *  - `payout.failed` / `transfer.failed` — money headed for the account never\n *    landed. A payout is the connected account's balance failing to reach its\n *    bank, so its account id is `event.account`: the Payout's own\n *    `destination` names the BANK. A transfer is the platform's balance\n *    failing to reach the connected account, a platform event whose\n *    `destination` IS the account. Recorded and surfaced, never retried:\n *    Stripe runs its own retry schedule, and a second transfer against an\n *    account that has just refused one is how a duplicate lands.\n *  - `payout.paid` — a later payout landed, which retires the warning the\n *    failure left on the profile. The history is kept.\n *\n * Every other event answers `false` without loading anything. A write that\n * fails throws, and the webhook's 500 earns the redelivery; every write\n * mirrors current state or is keyed by Stripe's id, so a redelivery converges.\n */\nexport async function applyStripeConnectAccountEvent(\n  collection: string,\n  delivered: PaymentProviderEvent,\n): Promise<boolean> {\n  const type = delivered?.type\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const object = delivered?.object as any\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const event = delivered?.event as any\n  if (type === 'account.updated') {\n    const { syncConnectAccountStatus } = await import(\n      './payment-provider-stripe-connect-status'\n    )\n    await syncConnectAccountStatus(collection, object, event?.livemode)\n    return true\n  }\n  if (type === 'payout.failed' || type === 'transfer.failed') {\n    const failedAccountId =\n      type === 'payout.failed'\n        ? String(event?.account ?? '')\n        : String(object?.destination?.id ?? object?.destination ?? '')\n    const { recordConnectPayoutFailure } = await import(\n      './payment-provider-stripe-connect-payouts'\n    )\n    await recordConnectPayoutFailure(collection, {\n      kind: type === 'payout.failed' ? 'payout' : 'transfer',\n      object,\n      accountId: failedAccountId,\n      livemode: event?.livemode,\n    })\n    return true\n  }\n  if (type === 'payout.paid') {\n    const { clearConnectPayoutFailure } = await import(\n      './payment-provider-stripe-connect-payouts'\n    )\n    await clearConnectPayoutFailure(collection, String(event?.account ?? ''))\n    return true\n  }\n  return false\n}\n\n/** The adapter the contract returns. */\nexport const STRIPE_CONNECT_PAYMENT_PROVIDER: PaymentProvider = {\n  id: 'stripe-connect',\n  // Called with no argument, so the key is read when asked — not when this\n  // module was first evaluated.\n  platformMode: () => platformStripeMode(),\n  resolvePlatformMode: () => resolvePlatformStripeMode(),\n  applyAccountEvent: applyStripeConnectAccountEvent,\n}\n"],"names":["platformStripeMode","key","process","env","STRIPE_SECRET_KEY","match","exec","String","trim","undefined","resolvePlatformStripeMode","fetchImpl","fetch","fromKey","response","method","headers","Authorization","ok","payload","json","livemode","applyStripeConnectAccountEvent","collection","delivered","type","object","event","syncConnectAccountStatus","failedAccountId","account","destination","id","recordConnectPayoutFailure","kind","accountId","clearConnectPayoutFailure","STRIPE_CONNECT_PAYMENT_PROVIDER","platformMode","resolvePlatformMode","applyAccountEvent"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEC,GAED;;;;;;;CAOC,GACD,OAAO,SAASA,mBACdC,MAA0BC,QAAQC,GAAG,CAACC,iBAAiB;IAEvD,MAAMC,QAAQ,sBAAsBC,IAAI,CAACC,OAAON,cAAAA,MAAO,IAAIO,IAAI;IAC/D,OAAOH,QAASA,KAAK,CAAC,EAAE,GAAmBI;AAC7C;AAEA;;;;;;;;CAQC,GACD,OAAO,eAAeC,0BACpBT,MAA0BC,QAAQC,GAAG,CAACC,iBAAiB,EACvDO,YAA0BC,KAAK;IAE/B,MAAMC,UAAUb,mBAAmBC;IACnC,IAAI,CAACA,KAAK,OAAOY;IACjB,IAAI;QACF,MAAMC,WAAW,MAAMH,UAAU,qCAAqC;YACpEI,QAAQ;YACRC,SAAS;gBAAEC,eAAe,CAAC,OAAO,EAAEhB,KAAK;YAAC;QAC5C;QACA,IAAIa,SAASI,EAAE,EAAE;YACf,MAAMC,UAAU,MAAML,SAASM,IAAI;YACnC,IAAI,QAAOD,2BAAAA,QAASE,QAAQ,MAAK,WAAW;gBAC1C,OAAOF,QAAQE,QAAQ,GAAG,SAAS;YACrC;QACF;IACF,EAAE,eAAM;IACN,uEAAuE;IACvE,0DAA0D;IAC5D;IACA,OAAOR;AACT;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,eAAeS,+BACpBC,UAAkB,EAClBC,SAA+B;IAE/B,MAAMC,OAAOD,6BAAAA,UAAWC,IAAI;IAC5B,8DAA8D;IAC9D,MAAMC,SAASF,6BAAAA,UAAWE,MAAM;IAChC,8DAA8D;IAC9D,MAAMC,QAAQH,6BAAAA,UAAWG,KAAK;IAC9B,IAAIF,SAAS,mBAAmB;QAC9B,MAAM,EAAEG,wBAAwB,EAAE,GAAG,MAAM,MAAM,CAC/C;QAEF,MAAMA,yBAAyBL,YAAYG,QAAQC,yBAAAA,MAAON,QAAQ;QAClE,OAAO;IACT;IACA,IAAII,SAAS,mBAAmBA,SAAS,mBAAmB;kBAI7CC;YAAAA;QAHb,MAAMG,kBACJJ,SAAS,kBACLlB,eAAOoB,yBAAAA,MAAOG,OAAO,mBAAI,MACzBvB,QAAOmB,iBAAAA,2BAAAA,sBAAAA,OAAQK,WAAW,qBAAnBL,oBAAqBM,EAAE,oBAAIN,0BAAAA,OAAQK,WAAW,YAA9CL,QAAkD;QAC/D,MAAM,EAAEO,0BAA0B,EAAE,GAAG,MAAM,MAAM,CACjD;QAEF,MAAMA,2BAA2BV,YAAY;YAC3CW,MAAMT,SAAS,kBAAkB,WAAW;YAC5CC;YACAS,WAAWN;YACXR,QAAQ,EAAEM,yBAAAA,MAAON,QAAQ;QAC3B;QACA,OAAO;IACT;IACA,IAAII,SAAS,eAAe;;QAC1B,MAAM,EAAEW,yBAAyB,EAAE,GAAG,MAAM,MAAM,CAChD;QAEF,MAAMA,0BAA0Bb,YAAYhB,gBAAOoB,yBAAAA,MAAOG,OAAO,oBAAI;QACrE,OAAO;IACT;IACA,OAAO;AACT;AAEA,sCAAsC,GACtC,OAAO,MAAMO,kCAAmD;IAC9DL,IAAI;IACJ,yEAAyE;IACzE,8BAA8B;IAC9BM,cAAc,IAAMtC;IACpBuC,qBAAqB,IAAM7B;IAC3B8B,mBAAmBlB;AACrB,EAAC"}

package/src/lib/server/payment-provider.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The merchant's payment account — the one seam the payment vendor lives
+ * behind when a TENANT takes money.
+ *
+ * ## Which money this is, and which it is not
+ *
+ * Two different accounts move money on this platform and only one of them is
+ * here. The platform BILLS its customers — plans, add-ons, metered usage — on
+ * its own account; that rail is infrastructure (`org-billing.ts`, the billing
+ * webhook route, `api-idempotency.ts`, `stripe-deployment-mode.ts`) and names
+ * its vendor where it runs. A tenant SELLS — a storefront order, a booked
+ * appointment, a marketplace listing — into a connected merchant account of
+ * its own, and every plugin that takes money reaches that account through
+ * this contract: whether the account may be charged, which world (live or
+ * test) the platform charges in, and what the provider says when the account
+ * changes or a payout fails.
+ *
+ * Commerce's `PaymentProviderId` names the provider a CHECKOUT is created
+ * with. This is the other half: the account the checkout pays into.
+ *
+ * ## One adapter, compiled in, and no registry — by failure direction
+ *
+ * Stripe Connect is the only adapter
+ * (`payment-provider-stripe-connect.ts`), and {@link paymentProvider} returns
+ * it without consulting any registry, the way the domain driver's built-ins
+ * and the mail rail's are compiled into their libraries. A provider a plugin
+ * registered could be ABSENT where a door reads it — a declaration that threw
+ * part-way, a route bundle that evaluated the registry apart from boot's —
+ * and every answer an absent provider could give at a money door is wrong: a
+ * refusal takes every sale on every site down, and a default lets a checkout
+ * proceed against an account nobody checked. Compiled in, it cannot be
+ * absent, so neither can happen.
+ *
+ * It lives in this library rather than in a plugin because three plugins take
+ * money into the same account — a storefront, a calendar and the marketplace
+ * — and one plugin may not import another. A plugin that owned the adapter
+ * would make the other two's sales depend on its install and on its
+ * registration having run; the adapter itself sells nothing and holds no
+ * product, only the platform's own connected-account integration.
+ *
+ * A second adapter is one module beside the first and a selector here. There
+ * is no selector today because there is nothing to select: every plugin's
+ * checkout is created against the same vendor.
+ *
+ * ## The contract every adapter owes
+ *
+ * 1. **An account the provider did not describe is never ready.** Every
+ *    {@link MerchantAccountReadiness} other than `'ready'` refuses the charge,
+ *    and only a literal boolean is a recorded answer.
+ * 2. **Only what the provider stated is written.** An account event that
+ *    states nothing writes nothing, and a written record never invents a
+ *    `false` or a `true` from an absent field.
+ * 3. **Failures propagate.** {@link PaymentProvider.applyAccountEvent} runs
+ *    inside the platform's billing webhook, and a throw is what earns the
+ *    redelivery; every write it makes is idempotent so that redelivery
+ *    converges.
+ */
+/** Which world a platform credential or a merchant account charges in. */
+export type PaymentMode = 'live' | 'test';
+/**
+ * Why a stored merchant account may not be charged against. Every value
+ * other than `'ready'` is a refusal.
+ */
+export type MerchantAccountReadiness = 
+/** Charge away. */
+'ready'
+/** No merchant account is stored at all — the onboarding call to action. */
+ | 'not-connected'
+/** The provider will not let this account take charges. */
+ | 'charges-disabled'
+/**
+ * The account's mode was never recorded (AGL-2471) AND this deployment is
+ * LIVE. The onboarding route and the provider's account event both record
+ * it, so a genuine merchant self-heals on the next of either.
+ */
+ | 'mode-unverified'
+/** The account belongs to the OTHER world. The AGL-2471 defect. */
+ | 'mode-mismatch';
+export interface MerchantAccountReadinessInput {
+    /** The stored account id, whatever shape the document has. */
+    accountId?: unknown;
+    /** Whether the provider said the account may take charges. */
+    chargesEnabled?: unknown;
+    /** Whether the provider said the account is live — absent before AGL-2471. */
+    accountLivemode?: unknown;
+    /** Defaults to {@link PaymentProvider.platformMode}. */
+    platformMode?: PaymentMode | undefined;
+}
+/** One event the platform's billing webhook received, as the provider sent it. */
+export interface PaymentProviderEvent {
+    /** The provider's own name for the event. */
+    type: string;
+    /** The object the event describes. */
+    object: unknown;
+    /** The whole event as delivered. */
+    event: unknown;
+}
+export interface PaymentProvider {
+    /** Stable id, for log lines. Never a display name. */
+    readonly id: string;
+    /**
+     * The mode this deployment's platform credential states about itself, read
+     * without a network call; `undefined` when there is no credential or it
+     * states nothing.
+     */
+    platformMode(): PaymentMode | undefined;
+    /**
+     * The platform's mode, asked of the provider first and the credential
+     * second — what an onboarding route records against a merchant account it
+     * has just retrieved.
+     */
+    resolvePlatformMode(): Promise<PaymentMode | undefined>;
+    /**
+     * Applies an event about a connected merchant account — its readiness
+     * changed, a payout to it failed, a later payout landed — to the documents
+     * in `collection` that store it. A plugin passes the collection holding ITS
+     * merchant profiles; a non-matching account updates nothing.
+     *
+     * @returns `true` when the event was about a merchant account and has been
+     *   applied, so the caller's own sections have nothing to do with it;
+     *   `false` for every other event.
+     */
+    applyAccountEvent(collection: string, delivered: PaymentProviderEvent): Promise<boolean>;
+}
+/** The provider every merchant account on this deployment is held at. */
+export declare function paymentProvider(): PaymentProvider;
+/**
+ * Decides whether a stored merchant account may be charged against.
+ *
+ * Order matters: the two refusals that existed before AGL-2471 are asked
+ * first, so an unconnected or restricted merchant still gets the answer they
+ * always got, and only an account that WOULD have passed reaches the mode
+ * question.
+ *
+ * WHY THE MODE RULE IS ASYMMETRIC, AND NOT "REFUSE ANYTHING UNPROVEN". An
+ * unrecorded mode refuses only on a LIVE deployment. That is where real money
+ * moves, and a live deployment can always re-establish the field: the
+ * merchant reconnects, or the provider sends one account event. Everywhere
+ * else — a test deployment, a developer machine, a self-hosted install still
+ * in sandbox, the whole test suite — an unverified account keeps the
+ * behavior it had before, because no real money can move there and the
+ * provider enforces the mode boundary itself. A PROVEN mismatch is refused in
+ * both directions, because it costs nothing to detect and is never right.
+ */
+export declare function merchantAccountReadiness(input: MerchantAccountReadinessInput): MerchantAccountReadiness;
+/**
+ * The form every money door calls: `true` only when the account may be
+ * charged, with the two mode refusals reported to the server log.
+ *
+ * The log line is the part the shopper's generic 409 cannot carry. Before
+ * this, a mode mismatch surfaced as a 502 from the provider with nothing
+ * anywhere naming the cause; the sale is still refused the same way, but now
+ * somebody can find out why.
+ */
+export declare function merchantAccountIsReady(input: MerchantAccountReadinessInput, context?: {
+    subject?: string;
+}): boolean;