@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/usage-invoice.js

@@ -0,0 +1,397 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * ONE-OFF USAGE INVOICES (AGL-3011).
+ *
+ * A workspace's accrued usage, charged to the card on file while the billing
+ * period is still open, rather than waiting for the renewal invoice. The
+ * caller decides WHEN and HOW MUCH; this module only knows how to turn that
+ * decision into a Stripe invoice and report what happened.
+ *
+ * ## Why it is here and not in the plugin that calls it
+ *
+ * Stripe credentials, the pinned API version and the idempotency discipline
+ * are platform concerns, and a plugin that minted its own invoices would be
+ * a second Stripe integration to keep in step with this one. Nothing in this
+ * module names a plugin, a meter or a product: the caller hands over a
+ * customer, an amount, a product and its own metadata, and every figure on
+ * the invoice came from the caller.
+ *
+ * ## Why an invoice and not a PaymentIntent
+ *
+ * An invoice carries invoice-level automatic tax, produces a document the
+ * customer can see in Billing and pay from it, and reaches the platform's
+ * existing `invoice.paid` tax-ledger and revenue path. A raw PaymentIntent
+ * has none of that, and a failure on one would simply be lost.
+ *
+ * ## ⚠️ NOTHING RETRIES A FAILED CHARGE HERE (AGL-3023)
+ *
+ * These invoices are created `auto_advance: false`, so Stripe runs no
+ * automatic collection on them: no retry schedule, no dunning emails, no
+ * further attempt of any kind. Measured on a test clock — the invoice sat at
+ * `attempt_count: 1, next_payment_attempt: null` through four clock
+ * advances over a week.
+ *
+ * `auto_advance: false` is deliberate, because it is what lets this module
+ * finalize and pay as its own steps and RETURN the outcome rather than a
+ * promise of one. The cost is that re-collection is ours: a failed charge
+ * leaves an open invoice that the customer can pay from Billing, and nothing
+ * chases it until they do.
+ *
+ * Do not restore a claim that Smart Retries cover these. An earlier version
+ * of this comment said so; it was never true of an invoice created this way,
+ * and a comment that is wrong about money is worse than no comment.
+ *
+ * ## Why a failure here never threatens the subscription
+ *
+ * This invoice is not a subscription invoice. It has its own lifecycle, so a
+ * card that declines fails THIS invoice and leaves the plan alone; Stripe's
+ * subscription dunning — which ends by canceling the subscription — is not
+ * reachable from here.
+ */ /**
+ * The API version every call below is pinned to.
+ *
+ * Pinned rather than taking the account default, because the parameters on
+ * an invoice item have moved between versions — `2025-03-31.basil` replaced
+ * the top-level `price` with `pricing[price]` — and a charge that silently
+ * changed shape under a Dashboard upgrade is the failure this constant
+ * exists to prevent. The same string the checkout route pins.
+ */ export const USAGE_INVOICE_API_VERSION = '2024-06-20';
+/**
+ * The smallest invoice this module will raise, in cents (AGL-3023).
+ *
+ * Stripe's minimum chargeable amount in USD. Below it there is nothing to
+ * charge, and an invoice raised anyway is finalized as PAID having collected
+ * nothing — the same "paid without money" shape that a caller crediting its
+ * own claim would read as a successful charge. Measured on a test clock: a
+ * $0.40 invoice came back `status: paid` and every later call answered
+ * "Invoice is already paid".
+ *
+ * Enforced HERE rather than left to each caller's own floor, because this is
+ * the module that knows about Stripe. A caller is free to hold a higher
+ * floor of its own; none may go under this one.
+ */ export const USAGE_INVOICE_MIN_CHARGE_CENTS = 50;
+async function stripe(fetchImpl, secretKey, path, params, idempotencyKey) {
+    const response = await fetchImpl(`https://api.stripe.com/v1/${path}`, {
+        method: params ? 'POST' : 'GET',
+        headers: _extends({
+            Authorization: `Bearer ${secretKey}`,
+            'Stripe-Version': USAGE_INVOICE_API_VERSION
+        }, params ? {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        } : {}, params && idempotencyKey ? {
+            'Idempotency-Key': idempotencyKey
+        } : {}),
+        body: params ? new URLSearchParams(params).toString() : undefined
+    });
+    const body = await response.json().catch(()=>({}));
+    return {
+        ok: response.ok,
+        status: response.status,
+        body
+    };
+}
+function stripeError(answer, fallback) {
+    var _answer_body;
+    const error = (_answer_body = answer.body) == null ? void 0 : _answer_body['error'];
+    const message = error == null ? void 0 : error.message;
+    return typeof message === 'string' && message ? message : fallback;
+}
+/** `metadata[key]=value` pairs, with every value coerced to a string. */ function metadataParams(metadata) {
+    const params = {};
+    for (const [key, value] of Object.entries(metadata)){
+        if (value === undefined || value === null) continue;
+        params[`metadata[${key}]`] = String(value);
+    }
+    return params;
+}
+/**
+ * Charges one workspace's accrued usage to the card on file.
+ *
+ * Four Stripe writes, each with its own idempotency key derived from the
+ * caller's: the invoice item, the invoice, the finalization and the pay. A
+ * retry of the whole attempt with the same key re-reads the objects the
+ * first attempt made rather than making a second set.
+ *
+ * `auto_advance` is left OFF and the invoice is finalized and paid here, so
+ * the answer this returns is the outcome rather than a promise of one. The
+ * webhook remains the authority — this only gets there sooner.
+ *
+ * The amount is NOT validated against anything: the caller is the only one
+ * that knows what was accrued, and a helper second-guessing it would be a
+ * second figure to drift from the first. It is checked for being a positive
+ * whole number of cents, which is a shape check, not a judgement.
+ */ export async function chargeOrgUsageInvoice(request, options = {}) {
+    var _ref, _options_secretKey, _options_fetchImpl, _ref1, _ref2;
+    var _created_body, _finalized_body;
+    const secretKey = (_ref = (_options_secretKey = options.secretKey) != null ? _options_secretKey : process.env.STRIPE_SECRET_KEY) != null ? _ref : '';
+    const fetchImpl = (_options_fetchImpl = options.fetchImpl) != null ? _options_fetchImpl : fetch;
+    const empty = {
+        ok: false,
+        invoiceId: null,
+        status: null,
+        totalCents: 0,
+        amountPaidCents: 0,
+        requiresAction: false,
+        error: null
+    };
+    if (!secretKey) return _extends({}, empty, {
+        error: 'Stripe is not configured'
+    });
+    const amountCents = Math.floor(Number(request.amountCents));
+    if (!Number.isFinite(amountCents) || amountCents <= 0) {
+        return _extends({}, empty, {
+            error: 'A usage invoice needs a positive amount'
+        });
+    }
+    if (amountCents < USAGE_INVOICE_MIN_CHARGE_CENTS) {
+        // Refused rather than attempted: Stripe finalizes a sub-minimum invoice
+        // as paid without collecting, so attempting one produces a document that
+        // claims to be settled and is not. Carrying the amount to the next
+        // charge is the caller's business and the honest answer here is "no".
+        return _extends({}, empty, {
+            error: `A usage invoice must be at least ${USAGE_INVOICE_MIN_CHARGE_CENTS} ` + `cents; ${amountCents} would finalize as paid having collected nothing`
+        });
+    }
+    if (!request.stripeCustomerId || !request.productId) {
+        return _extends({}, empty, {
+            error: 'A usage invoice needs a customer and a product'
+        });
+    }
+    const currency = String(request.currency || 'usd').toLowerCase();
+    const metadata = metadataParams(request.metadata);
+    const key = (object)=>`${request.idempotencyKey}:${object}`;
+    // THE INVOICE FIRST, THEN THE LINE ATTACHED TO IT BY ID (AGL-3023).
+    //
+    // The order is the fix, and the reason is a default. `POST /v1/invoices`
+    // documents `pending_invoice_items_behavior` as "Defaults to `exclude` if
+    // the parameter is omitted" — so an invoice created after a pending item,
+    // without that parameter, sweeps up NOTHING. Every invoice comes out
+    // empty, finalizes at zero, and a zero-total invoice is already paid the
+    // moment it finalizes. That is what the first test-clock drill measured.
+    //
+    // Passing `pending_invoice_items_behavior: 'include'` would also fix the
+    // zero, and it is the wrong fix: "include" means every pending item on
+    // that customer, not ours. A proration, another plugin's usage line, an
+    // item some other part of the platform staged — all of it would land on an
+    // invoice this module then reports as an AI overage charge for an amount
+    // it made up. Attaching our line to our invoice BY ID binds exactly one
+    // line and cannot pick up a second.
+    const created = await stripe(fetchImpl, secretKey, 'invoices', _extends({
+        customer: request.stripeCustomerId,
+        collection_method: 'charge_automatically',
+        auto_advance: 'false',
+        'automatic_tax[enabled]': 'true',
+        // Stated rather than left to the default, so this call says what it
+        // means: this invoice carries the line added below and nothing else.
+        pending_invoice_items_behavior: 'exclude'
+    }, metadata), key('invoice'));
+    if (!created.ok) {
+        return _extends({}, empty, {
+            error: stripeError(created, 'The usage invoice was refused')
+        });
+    }
+    const invoiceId = String((_ref1 = (_created_body = created.body) == null ? void 0 : _created_body['id']) != null ? _ref1 : '');
+    if (!invoiceId) {
+        return _extends({}, empty, {
+            error: 'Stripe returned an invoice with no id'
+        });
+    }
+    // The line, addressed to the draft above. `price_data` rather than a bare
+    // amount, because the PRODUCT is what carries the tax code the account's
+    // automatic tax computes from, and an amount with no product behind it is
+    // an untaxed line on a taxed invoice. `tax_behavior` is stated rather than
+    // left to the account default: US sales tax is added on top of the
+    // platform's prices, and an unspecified behavior is refused outright when
+    // automatic tax is on.
+    const item = await stripe(fetchImpl, secretKey, 'invoiceitems', _extends({
+        customer: request.stripeCustomerId,
+        invoice: invoiceId,
+        'price_data[product]': request.productId,
+        'price_data[currency]': currency,
+        'price_data[unit_amount]': String(amountCents),
+        'price_data[tax_behavior]': 'exclusive',
+        description: request.description
+    }, metadata), key('invoiceitem'));
+    if (!item.ok) {
+        return _extends({}, empty, {
+            invoiceId,
+            status: 'draft',
+            error: stripeError(item, 'The usage line was refused')
+        });
+    }
+    const finalized = await stripe(fetchImpl, secretKey, `invoices/${invoiceId}/finalize`, {
+        auto_advance: 'false'
+    }, key('finalize'));
+    if (!finalized.ok) {
+        var _ref3;
+        var _finalized_body1;
+        return _extends({}, empty, {
+            invoiceId,
+            status: String((_ref3 = (_finalized_body1 = finalized.body) == null ? void 0 : _finalized_body1['status']) != null ? _ref3 : 'draft'),
+            error: stripeError(finalized, 'The usage invoice could not be finalized')
+        });
+    }
+    // WHAT THE INVOICE ACTUALLY CAME TO (AGL-3023).
+    //
+    // Checked before paying, because a zero-total invoice is not a cheap
+    // charge — it is a charge that did not happen, and Stripe marks it paid on
+    // finalization. Calling `pay` on one answers "Invoice is already paid",
+    // which reads like a failure of the card and is nothing of the sort.
+    //
+    // The comparison is `< amountCents` rather than `!== 0`: automatic tax
+    // ADDS to the total, so a correct invoice is at least what we asked for
+    // and usually more. Anything less means the line did not land.
+    const totalCents = Math.max(0, Math.floor(Number((_ref2 = (_finalized_body = finalized.body) == null ? void 0 : _finalized_body['total']) != null ? _ref2 : 0)));
+    if (totalCents < amountCents) {
+        var _ref4;
+        var _finalized_body2;
+        return _extends({}, empty, {
+            invoiceId,
+            status: String((_ref4 = (_finalized_body2 = finalized.body) == null ? void 0 : _finalized_body2['status']) != null ? _ref4 : null) || null,
+            totalCents,
+            error: `The usage invoice finalized at ${totalCents} cents for a ` + `${amountCents}-cent line, so the line did not reach it`
+        });
+    }
+    const paid = await stripe(fetchImpl, secretKey, `invoices/${invoiceId}/pay`, {}, key('pay'));
+    return readPayOutcome(invoiceId, totalCents, paid);
+}
+/**
+ * The charge's outcome, told apart from the transport.
+ *
+ * A declined card is a 402 from Stripe with a real invoice behind it, not a
+ * fault of ours — so the invoice id and the status survive the failure, and
+ * the caller can record which invoice to wait on. `requires_action` is
+ * singled out because it reads like "not yet" and is in fact "no": nobody is
+ * present to complete a 3-D Secure challenge on an off-session charge.
+ *
+ * ## `paid` is not enough; money is (AGL-3023)
+ *
+ * Success requires BOTH a `paid` status and an `amount_paid` that covers the
+ * line. An invoice can read `paid` having collected nothing — a zero total
+ * is marked paid at finalization — and a caller that credited a workspace
+ * from our own requested figure would record a payment that never happened.
+ * On a usage bound that is the worst possible failure: the balance the gate
+ * refuses on would be cleared by bookkeeping rather than by money, and the
+ * workspace could spend without limit. So what is reported here is what
+ * Stripe says it took.
+ */ function readPayOutcome(invoiceId, totalCents, paid) {
+    var _status, _amount_paid, _ref;
+    var _paid_body, _error_payment_intent;
+    const invoice = paid.ok ? paid.body : null;
+    const status = String((_status = (invoice != null ? invoice : {})['status']) != null ? _status : '') || null;
+    const amountPaidCents = Math.max(0, Math.floor(Number((_amount_paid = (invoice != null ? invoice : {})['amount_paid']) != null ? _amount_paid : 0)));
+    if (paid.ok && status === 'paid' && amountPaidCents >= totalCents && totalCents > 0) {
+        return {
+            ok: true,
+            invoiceId,
+            status,
+            totalCents,
+            amountPaidCents,
+            requiresAction: false,
+            error: null
+        };
+    }
+    if (paid.ok && status === 'paid') {
+        // Stripe answered 200 and `paid`, and took less than the invoice came
+        // to. Reported as a failure with the figures, because the alternative is
+        // crediting a workspace for money nobody received.
+        return {
+            ok: false,
+            invoiceId,
+            status,
+            totalCents,
+            amountPaidCents,
+            requiresAction: false,
+            error: `The usage invoice reports paid having collected ${amountPaidCents} ` + `cents of ${totalCents}`
+        };
+    }
+    const error = (_paid_body = paid.body) == null ? void 0 : _paid_body['error'];
+    const intentStatus = String((_ref = error == null ? void 0 : (_error_payment_intent = error.payment_intent) == null ? void 0 : _error_payment_intent.status) != null ? _ref : '');
+    return {
+        ok: false,
+        invoiceId,
+        status: status != null ? status : 'open',
+        totalCents,
+        amountPaidCents,
+        requiresAction: intentStatus === 'requires_action',
+        error: stripeError(paid, 'The card on file did not complete the charge')
+    };
+}
+/**
+ * Finds a usage invoice by the caller's own claim id.
+ *
+ * The reconciliation read for a caller that claimed a charge and then lost
+ * the process before it learned the outcome — a crash, a killed background
+ * task. Searching by the caller's metadata answers "did this claim ever
+ * become an invoice" without the caller having to persist a Stripe id it
+ * never received.
+ *
+ * Stripe's search index is eventually consistent, so an empty answer means
+ * "not found YET" and never "not created". Callers reconcile on a schedule
+ * with that in mind rather than treating the first miss as proof.
+ */ export async function findOrgUsageInvoice(query, options = {}) {
+    var _ref, _options_secretKey, _options_fetchImpl, _ref1, _found_id, _found_status, _found_amount_paid;
+    var _answer_body;
+    const secretKey = (_ref = (_options_secretKey = options.secretKey) != null ? _options_secretKey : process.env.STRIPE_SECRET_KEY) != null ? _ref : '';
+    const fetchImpl = (_options_fetchImpl = options.fetchImpl) != null ? _options_fetchImpl : fetch;
+    if (!secretKey) {
+        return {
+            invoiceId: null,
+            status: null,
+            amountPaidCents: 0,
+            error: 'Stripe is not configured'
+        };
+    }
+    // Single quotes around the value are Stripe's own search syntax; a value
+    // carrying one would break the query, so it is refused rather than escaped
+    // — every id this is called with is generated by us from `[A-Za-z0-9-]`.
+    if (/['\\]/.test(query.metadataValue)) {
+        return {
+            invoiceId: null,
+            status: null,
+            amountPaidCents: 0,
+            error: 'Unsearchable claim id'
+        };
+    }
+    const search = `metadata['${query.metadataKey}']:'${query.metadataValue}'`;
+    const answer = await stripe(fetchImpl, secretKey, `invoices/search?query=${encodeURIComponent(search)}&limit=1`, null, null);
+    if (!answer.ok) {
+        return {
+            invoiceId: null,
+            status: null,
+            amountPaidCents: 0,
+            error: stripeError(answer, 'Invoice search failed')
+        };
+    }
+    const data = (_ref1 = (_answer_body = answer.body) == null ? void 0 : _answer_body['data']) != null ? _ref1 : [];
+    const found = data[0];
+    if (!found) return {
+        invoiceId: null,
+        status: null,
+        amountPaidCents: 0,
+        error: null
+    };
+    return {
+        invoiceId: String((_found_id = found['id']) != null ? _found_id : '') || null,
+        status: String((_found_status = found['status']) != null ? _found_status : '') || null,
+        amountPaidCents: Math.max(0, Math.floor(Number((_found_amount_paid = found['amount_paid']) != null ? _found_amount_paid : 0))),
+        error: null
+    };
+}
+
+//# sourceMappingURL=usage-invoice.js.map

package/src/lib/server/usage-invoice.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/usage-invoice.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\n/**\n * ONE-OFF USAGE INVOICES (AGL-3011).\n *\n * A workspace's accrued usage, charged to the card on file while the billing\n * period is still open, rather than waiting for the renewal invoice. The\n * caller decides WHEN and HOW MUCH; this module only knows how to turn that\n * decision into a Stripe invoice and report what happened.\n *\n * ## Why it is here and not in the plugin that calls it\n *\n * Stripe credentials, the pinned API version and the idempotency discipline\n * are platform concerns, and a plugin that minted its own invoices would be\n * a second Stripe integration to keep in step with this one. Nothing in this\n * module names a plugin, a meter or a product: the caller hands over a\n * customer, an amount, a product and its own metadata, and every figure on\n * the invoice came from the caller.\n *\n * ## Why an invoice and not a PaymentIntent\n *\n * An invoice carries invoice-level automatic tax, produces a document the\n * customer can see in Billing and pay from it, and reaches the platform's\n * existing `invoice.paid` tax-ledger and revenue path. A raw PaymentIntent\n * has none of that, and a failure on one would simply be lost.\n *\n * ## ⚠️ NOTHING RETRIES A FAILED CHARGE HERE (AGL-3023)\n *\n * These invoices are created `auto_advance: false`, so Stripe runs no\n * automatic collection on them: no retry schedule, no dunning emails, no\n * further attempt of any kind. Measured on a test clock — the invoice sat at\n * `attempt_count: 1, next_payment_attempt: null` through four clock\n * advances over a week.\n *\n * `auto_advance: false` is deliberate, because it is what lets this module\n * finalize and pay as its own steps and RETURN the outcome rather than a\n * promise of one. The cost is that re-collection is ours: a failed charge\n * leaves an open invoice that the customer can pay from Billing, and nothing\n * chases it until they do.\n *\n * Do not restore a claim that Smart Retries cover these. An earlier version\n * of this comment said so; it was never true of an invoice created this way,\n * and a comment that is wrong about money is worse than no comment.\n *\n * ## Why a failure here never threatens the subscription\n *\n * This invoice is not a subscription invoice. It has its own lifecycle, so a\n * card that declines fails THIS invoice and leaves the plan alone; Stripe's\n * subscription dunning — which ends by canceling the subscription — is not\n * reachable from here.\n */\n\n/**\n * The API version every call below is pinned to.\n *\n * Pinned rather than taking the account default, because the parameters on\n * an invoice item have moved between versions — `2025-03-31.basil` replaced\n * the top-level `price` with `pricing[price]` — and a charge that silently\n * changed shape under a Dashboard upgrade is the failure this constant\n * exists to prevent. The same string the checkout route pins.\n */\nexport const USAGE_INVOICE_API_VERSION = '2024-06-20'\n\n/**\n * The smallest invoice this module will raise, in cents (AGL-3023).\n *\n * Stripe's minimum chargeable amount in USD. Below it there is nothing to\n * charge, and an invoice raised anyway is finalized as PAID having collected\n * nothing — the same \"paid without money\" shape that a caller crediting its\n * own claim would read as a successful charge. Measured on a test clock: a\n * $0.40 invoice came back `status: paid` and every later call answered\n * \"Invoice is already paid\".\n *\n * Enforced HERE rather than left to each caller's own floor, because this is\n * the module that knows about Stripe. A caller is free to hold a higher\n * floor of its own; none may go under this one.\n */\nexport const USAGE_INVOICE_MIN_CHARGE_CENTS = 50\n\n/** What a caller asks to be charged. */\nexport interface OrgUsageInvoiceRequest {\n  /** The workspace the charge belongs to, for the invoice's metadata. */\n  orgId: string\n  /** The Stripe customer to bill — resolved by the caller from org billing. */\n  stripeCustomerId: string\n  /** The Stripe product the line is billed against; it carries the tax code. */\n  productId: string\n  /** The amount in whole cents. Must be positive. */\n  amountCents: number\n  /** ISO 4217, lower case. */\n  currency: string\n  /** The line's description, as the customer reads it on the invoice. */\n  description: string\n  /**\n   * Metadata stamped on BOTH the invoice item and the invoice.\n   *\n   * The caller's own claim ticket travels here — which plugin asked, which\n   * accrual this settles — so the webhook can route the outcome back without\n   * core knowing what any of it means.\n   */\n  metadata: Readonly<Record<string, string>>\n  /**\n   * One string that identifies this attempt.\n   *\n   * Every write below derives its own key from it, because Stripe's\n   * idempotency layer is account-scoped and compares parameters: sending one\n   * key to `/v1/invoiceitems` and then to `/v1/invoices` would make the\n   * second call fail outright. Same discipline as the enterprise\n   * provisioning route.\n   */\n  idempotencyKey: string\n}\n\n/** What became of the attempt. */\nexport interface OrgUsageInvoiceResult {\n  ok: boolean\n  /** The invoice, once it exists — present even when the charge failed. */\n  invoiceId: string | null\n  /**\n   * Stripe's own invoice status: `paid`, `open`, `void`, `uncollectible`, or\n   * `draft` when finalization itself failed.\n   */\n  status: string | null\n  /**\n   * What the finalized invoice actually came to, and what Stripe actually\n   * collected, in cents (AGL-3023).\n   *\n   * Both are reported because the caller must never credit a workspace from\n   * the amount it ASKED to charge. An invoice that finalized at zero, or one\n   * that reports `paid` having collected nothing, is not a payment — and a\n   * bound enforced by our own bookkeeping rather than by money is not a\n   * bound at all.\n   */\n  totalCents: number\n  amountPaidCents: number\n  /**\n   * Whether Stripe asked for more from the cardholder (3-D Secure). It is\n   * not a payment, and a caller extending credit must treat it as a failure\n   * rather than wait: nobody is at the keyboard on an off-session charge.\n   */\n  requiresAction: boolean\n  /** Stripe's message when something went wrong, for logs and staff. */\n  error: string | null\n}\n\ntype StripeFetch = typeof fetch\n\ninterface StripeAnswer {\n  ok: boolean\n  status: number\n  body: Record<string, unknown>\n}\n\nasync function stripe(\n  fetchImpl: StripeFetch,\n  secretKey: string,\n  path: string,\n  params: Record<string, string> | null,\n  idempotencyKey: string | null,\n): Promise<StripeAnswer> {\n  const response = await fetchImpl(`https://api.stripe.com/v1/${path}`, {\n    method: params ? 'POST' : 'GET',\n    headers: {\n      Authorization: `Bearer ${secretKey}`,\n      'Stripe-Version': USAGE_INVOICE_API_VERSION,\n      ...(params ? { 'Content-Type': 'application/x-www-form-urlencoded' } : {}),\n      // Stripe documents idempotency keys as having no effect on GET, so\n      // only the writes carry one.\n      ...(params && idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),\n    },\n    body: params ? new URLSearchParams(params).toString() : undefined,\n  })\n  const body = (await response.json().catch(() => ({}))) as Record<string, unknown>\n  return { ok: response.ok, status: response.status, body }\n}\n\nfunction stripeError(answer: StripeAnswer, fallback: string): string {\n  const error = answer.body?.['error'] as { message?: unknown } | undefined\n  const message = error?.message\n  return typeof message === 'string' && message ? message : fallback\n}\n\n/** `metadata[key]=value` pairs, with every value coerced to a string. */\nfunction metadataParams(\n  metadata: Readonly<Record<string, string>>,\n): Record<string, string> {\n  const params: Record<string, string> = {}\n  for (const [key, value] of Object.entries(metadata)) {\n    if (value === undefined || value === null) continue\n    params[`metadata[${key}]`] = String(value)\n  }\n  return params\n}\n\n/**\n * Charges one workspace's accrued usage to the card on file.\n *\n * Four Stripe writes, each with its own idempotency key derived from the\n * caller's: the invoice item, the invoice, the finalization and the pay. A\n * retry of the whole attempt with the same key re-reads the objects the\n * first attempt made rather than making a second set.\n *\n * `auto_advance` is left OFF and the invoice is finalized and paid here, so\n * the answer this returns is the outcome rather than a promise of one. The\n * webhook remains the authority — this only gets there sooner.\n *\n * The amount is NOT validated against anything: the caller is the only one\n * that knows what was accrued, and a helper second-guessing it would be a\n * second figure to drift from the first. It is checked for being a positive\n * whole number of cents, which is a shape check, not a judgement.\n */\nexport async function chargeOrgUsageInvoice(\n  request: OrgUsageInvoiceRequest,\n  options: { secretKey?: string; fetchImpl?: StripeFetch } = {},\n): Promise<OrgUsageInvoiceResult> {\n  const secretKey = options.secretKey ?? process.env.STRIPE_SECRET_KEY ?? ''\n  const fetchImpl = options.fetchImpl ?? fetch\n  const empty: OrgUsageInvoiceResult = {\n    ok: false,\n    invoiceId: null,\n    status: null,\n    totalCents: 0,\n    amountPaidCents: 0,\n    requiresAction: false,\n    error: null,\n  }\n  if (!secretKey) return { ...empty, error: 'Stripe is not configured' }\n  const amountCents = Math.floor(Number(request.amountCents))\n  if (!Number.isFinite(amountCents) || amountCents <= 0) {\n    return { ...empty, error: 'A usage invoice needs a positive amount' }\n  }\n  if (amountCents < USAGE_INVOICE_MIN_CHARGE_CENTS) {\n    // Refused rather than attempted: Stripe finalizes a sub-minimum invoice\n    // as paid without collecting, so attempting one produces a document that\n    // claims to be settled and is not. Carrying the amount to the next\n    // charge is the caller's business and the honest answer here is \"no\".\n    return {\n      ...empty,\n      error:\n        `A usage invoice must be at least ${USAGE_INVOICE_MIN_CHARGE_CENTS} ` +\n        `cents; ${amountCents} would finalize as paid having collected nothing`,\n    }\n  }\n  if (!request.stripeCustomerId || !request.productId) {\n    return { ...empty, error: 'A usage invoice needs a customer and a product' }\n  }\n  const currency = String(request.currency || 'usd').toLowerCase()\n  const metadata = metadataParams(request.metadata)\n  const key = (object: string) => `${request.idempotencyKey}:${object}`\n\n  // THE INVOICE FIRST, THEN THE LINE ATTACHED TO IT BY ID (AGL-3023).\n  //\n  // The order is the fix, and the reason is a default. `POST /v1/invoices`\n  // documents `pending_invoice_items_behavior` as \"Defaults to `exclude` if\n  // the parameter is omitted\" — so an invoice created after a pending item,\n  // without that parameter, sweeps up NOTHING. Every invoice comes out\n  // empty, finalizes at zero, and a zero-total invoice is already paid the\n  // moment it finalizes. That is what the first test-clock drill measured.\n  //\n  // Passing `pending_invoice_items_behavior: 'include'` would also fix the\n  // zero, and it is the wrong fix: \"include\" means every pending item on\n  // that customer, not ours. A proration, another plugin's usage line, an\n  // item some other part of the platform staged — all of it would land on an\n  // invoice this module then reports as an AI overage charge for an amount\n  // it made up. Attaching our line to our invoice BY ID binds exactly one\n  // line and cannot pick up a second.\n  const created = await stripe(\n    fetchImpl,\n    secretKey,\n    'invoices',\n    {\n      customer: request.stripeCustomerId,\n      collection_method: 'charge_automatically',\n      auto_advance: 'false',\n      'automatic_tax[enabled]': 'true',\n      // Stated rather than left to the default, so this call says what it\n      // means: this invoice carries the line added below and nothing else.\n      pending_invoice_items_behavior: 'exclude',\n      ...metadata,\n    },\n    key('invoice'),\n  )\n  if (!created.ok) {\n    return { ...empty, error: stripeError(created, 'The usage invoice was refused') }\n  }\n  const invoiceId = String(created.body?.['id'] ?? '')\n  if (!invoiceId) {\n    return { ...empty, error: 'Stripe returned an invoice with no id' }\n  }\n\n  // The line, addressed to the draft above. `price_data` rather than a bare\n  // amount, because the PRODUCT is what carries the tax code the account's\n  // automatic tax computes from, and an amount with no product behind it is\n  // an untaxed line on a taxed invoice. `tax_behavior` is stated rather than\n  // left to the account default: US sales tax is added on top of the\n  // platform's prices, and an unspecified behavior is refused outright when\n  // automatic tax is on.\n  const item = await stripe(\n    fetchImpl,\n    secretKey,\n    'invoiceitems',\n    {\n      customer: request.stripeCustomerId,\n      invoice: invoiceId,\n      'price_data[product]': request.productId,\n      'price_data[currency]': currency,\n      'price_data[unit_amount]': String(amountCents),\n      'price_data[tax_behavior]': 'exclusive',\n      description: request.description,\n      ...metadata,\n    },\n    key('invoiceitem'),\n  )\n  if (!item.ok) {\n    return {\n      ...empty,\n      invoiceId,\n      status: 'draft',\n      error: stripeError(item, 'The usage line was refused'),\n    }\n  }\n\n  const finalized = await stripe(\n    fetchImpl,\n    secretKey,\n    `invoices/${invoiceId}/finalize`,\n    { auto_advance: 'false' },\n    key('finalize'),\n  )\n  if (!finalized.ok) {\n    return {\n      ...empty,\n      invoiceId,\n      status: String(finalized.body?.['status'] ?? 'draft'),\n      error: stripeError(finalized, 'The usage invoice could not be finalized'),\n    }\n  }\n\n  // WHAT THE INVOICE ACTUALLY CAME TO (AGL-3023).\n  //\n  // Checked before paying, because a zero-total invoice is not a cheap\n  // charge — it is a charge that did not happen, and Stripe marks it paid on\n  // finalization. Calling `pay` on one answers \"Invoice is already paid\",\n  // which reads like a failure of the card and is nothing of the sort.\n  //\n  // The comparison is `< amountCents` rather than `!== 0`: automatic tax\n  // ADDS to the total, so a correct invoice is at least what we asked for\n  // and usually more. Anything less means the line did not land.\n  const totalCents = Math.max(0, Math.floor(Number(finalized.body?.['total'] ?? 0)))\n  if (totalCents < amountCents) {\n    return {\n      ...empty,\n      invoiceId,\n      status: String(finalized.body?.['status'] ?? null) || null,\n      totalCents,\n      error:\n        `The usage invoice finalized at ${totalCents} cents for a ` +\n        `${amountCents}-cent line, so the line did not reach it`,\n    }\n  }\n\n  const paid = await stripe(\n    fetchImpl,\n    secretKey,\n    `invoices/${invoiceId}/pay`,\n    {},\n    key('pay'),\n  )\n  return readPayOutcome(invoiceId, totalCents, paid)\n}\n\n/**\n * The charge's outcome, told apart from the transport.\n *\n * A declined card is a 402 from Stripe with a real invoice behind it, not a\n * fault of ours — so the invoice id and the status survive the failure, and\n * the caller can record which invoice to wait on. `requires_action` is\n * singled out because it reads like \"not yet\" and is in fact \"no\": nobody is\n * present to complete a 3-D Secure challenge on an off-session charge.\n *\n * ## `paid` is not enough; money is (AGL-3023)\n *\n * Success requires BOTH a `paid` status and an `amount_paid` that covers the\n * line. An invoice can read `paid` having collected nothing — a zero total\n * is marked paid at finalization — and a caller that credited a workspace\n * from our own requested figure would record a payment that never happened.\n * On a usage bound that is the worst possible failure: the balance the gate\n * refuses on would be cleared by bookkeeping rather than by money, and the\n * workspace could spend without limit. So what is reported here is what\n * Stripe says it took.\n */\nfunction readPayOutcome(\n  invoiceId: string,\n  totalCents: number,\n  paid: StripeAnswer,\n): OrgUsageInvoiceResult {\n  const invoice = paid.ok ? paid.body : null\n  const status = String((invoice ?? {})['status'] ?? '') || null\n  const amountPaidCents = Math.max(\n    0,\n    Math.floor(Number((invoice ?? {})['amount_paid'] ?? 0)),\n  )\n  if (paid.ok && status === 'paid' && amountPaidCents >= totalCents && totalCents > 0) {\n    return {\n      ok: true,\n      invoiceId,\n      status,\n      totalCents,\n      amountPaidCents,\n      requiresAction: false,\n      error: null,\n    }\n  }\n  if (paid.ok && status === 'paid') {\n    // Stripe answered 200 and `paid`, and took less than the invoice came\n    // to. Reported as a failure with the figures, because the alternative is\n    // crediting a workspace for money nobody received.\n    return {\n      ok: false,\n      invoiceId,\n      status,\n      totalCents,\n      amountPaidCents,\n      requiresAction: false,\n      error:\n        `The usage invoice reports paid having collected ${amountPaidCents} ` +\n        `cents of ${totalCents}`,\n    }\n  }\n  const error = paid.body?.['error'] as\n    | { message?: unknown; payment_intent?: { status?: unknown } }\n    | undefined\n  const intentStatus = String(error?.payment_intent?.status ?? '')\n  return {\n    ok: false,\n    invoiceId,\n    status: status ?? 'open',\n    totalCents,\n    amountPaidCents,\n    requiresAction: intentStatus === 'requires_action',\n    error: stripeError(paid, 'The card on file did not complete the charge'),\n  }\n}\n\n/**\n * Finds a usage invoice by the caller's own claim id.\n *\n * The reconciliation read for a caller that claimed a charge and then lost\n * the process before it learned the outcome — a crash, a killed background\n * task. Searching by the caller's metadata answers \"did this claim ever\n * become an invoice\" without the caller having to persist a Stripe id it\n * never received.\n *\n * Stripe's search index is eventually consistent, so an empty answer means\n * \"not found YET\" and never \"not created\". Callers reconcile on a schedule\n * with that in mind rather than treating the first miss as proof.\n */\nexport async function findOrgUsageInvoice(\n  query: { metadataKey: string; metadataValue: string },\n  options: { secretKey?: string; fetchImpl?: StripeFetch } = {},\n): Promise<{\n  invoiceId: string | null\n  status: string | null\n  /** What that invoice collected, in cents — 0 when none was found. */\n  amountPaidCents: number\n  error: string | null\n}> {\n  const secretKey = options.secretKey ?? process.env.STRIPE_SECRET_KEY ?? ''\n  const fetchImpl = options.fetchImpl ?? fetch\n  if (!secretKey) {\n    return {\n      invoiceId: null,\n      status: null,\n      amountPaidCents: 0,\n      error: 'Stripe is not configured',\n    }\n  }\n  // Single quotes around the value are Stripe's own search syntax; a value\n  // carrying one would break the query, so it is refused rather than escaped\n  // — every id this is called with is generated by us from `[A-Za-z0-9-]`.\n  if (/['\\\\]/.test(query.metadataValue)) {\n    return { invoiceId: null, status: null, amountPaidCents: 0, error: 'Unsearchable claim id' }\n  }\n  const search = `metadata['${query.metadataKey}']:'${query.metadataValue}'`\n  const answer = await stripe(\n    fetchImpl,\n    secretKey,\n    `invoices/search?query=${encodeURIComponent(search)}&limit=1`,\n    null,\n    null,\n  )\n  if (!answer.ok) {\n    return {\n      invoiceId: null,\n      status: null,\n      amountPaidCents: 0,\n      error: stripeError(answer, 'Invoice search failed'),\n    }\n  }\n  const data = (answer.body?.['data'] ?? []) as Array<Record<string, unknown>>\n  const found = data[0]\n  if (!found) return { invoiceId: null, status: null, amountPaidCents: 0, error: null }\n  return {\n    invoiceId: String(found['id'] ?? '') || null,\n    status: String(found['status'] ?? '') || null,\n    amountPaidCents: Math.max(0, Math.floor(Number(found['amount_paid'] ?? 0))),\n    error: null,\n  }\n}\n"],"names":["USAGE_INVOICE_API_VERSION","USAGE_INVOICE_MIN_CHARGE_CENTS","stripe","fetchImpl","secretKey","path","params","idempotencyKey","response","method","headers","Authorization","body","URLSearchParams","toString","undefined","json","catch","ok","status","stripeError","answer","fallback","error","message","metadataParams","metadata","key","value","Object","entries","String","chargeOrgUsageInvoice","request","options","created","finalized","process","env","STRIPE_SECRET_KEY","fetch","empty","invoiceId","totalCents","amountPaidCents","requiresAction","amountCents","Math","floor","Number","isFinite","stripeCustomerId","productId","currency","toLowerCase","object","customer","collection_method","auto_advance","pending_invoice_items_behavior","item","invoice","description","max","paid","readPayOutcome","intentStatus","payment_intent","findOrgUsageInvoice","query","found","test","metadataValue","search","metadataKey","encodeURIComponent","data"],"mappings":"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"}

package/src/lib/server/user-profiles.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AglynPostalAddress } from '@aglyn/aglyn/server';
+export interface SeedUserProfileInput {
+    /** The provider's single name string, when the assertion carries one. */
+    displayName?: string | null;
+    /**
+     * Avatar and phone from the same assertion (AGL-1131). Callers pass these
+     * through `resolveIdpPhotoUrl` / `resolveIdpPhone`, which is where the
+     * https-only check on the photo lives — this function does not re-validate.
+     */
+    photoUrl?: string | null;
+    phoneNumber?: string | null;
+    /**
+     * Postal address from the same assertion (AGL-1963). Callers pass this
+     * through `resolveIdpAddress`, whose loose `IdpAddressParts` is structurally
+     * an `AglynPostalAddress` — it is the seed below, not the caller, that
+     * decides whether the parts amount to an address at all. Stored only when
+     * the assertion carries a STREET LINE (AGL-1566): a directory that releases
+     * a home city and postcode and no street has given us personal data with no
+     * use, not an address.
+     */
+    address?: AglynPostalAddress | null;
+    /** Injectable for tests; defaults to the admin app's Firestore. */
+    firestore?: any;
+}
+/**
+ * Create `users/{uid}` if it is missing and prefill the name fields from the
+ * identity provider, without ever overwriting what the user has typed.
+ *
+ * Only ABSENT fields are written, so re-running on every sign-in — which is
+ * what the SSO route does — cannot undo an edit: rename yourself in Basic
+ * info and the IdP's copy stays out of it.
+ *
+ * Best-effort by contract. Provisioning access must not fail because a
+ * cosmetic prefill did, so the caller is expected to let a rejection through
+ * rather than surface it; the profile self-heals on the next sign-in.
+ *
+ * @returns what the seed actually wrote, for logging and tests.
+ */
+export declare function seedUserProfile(uid: string, input?: SeedUserProfileInput): Promise<{
+    created: boolean;
+    fields: string[];
+}>;
+/**
+ * "Delete the phone number you hold for me" — the second half of Privacy
+ * Policy v4 §11 (AGL-1592). Deliberately adjacent to `seedUserProfile`,
+ * because the two are halves of one invariant: this sets the marker that one
+ * reads, and changing either without the other silently restores the defect.
+ *
+ * WHAT IT DOES, AND WHY IT IS NOT JUST A DELETE
+ *
+ *  1. Removes `users/{uid}.phoneNumber` outright (`FieldValue.delete()`, not
+ *     `null` — the request was to stop holding it, and a nulled field still
+ *     reads as "we have a phone slot for this person").
+ *  2. Stamps `phoneNumberErasedAt`, which is what stops the IdP re-asserting
+ *     it on the next sign-in.
+ *  3. Writes a suppression record for the number, with `erasePhoneOnFile`.
+ *
+ * Step 3 is the one that looks contradictory and is not. Deleting every copy
+ * of a number does NOT protect the person from being called — it destroys the
+ * only artefact that could recognise them, so the same number arriving later
+ * from a customer's CRM, a support ticket, or their own re-typed profile is a
+ * number we have never heard of and will happily dial. The minimal retained
+ * record is what makes the deletion request mean what the person meant by it.
+ * The full reasoning, and the statutory carve-outs it rests on, are in
+ * contact-suppression.ts.
+ *
+ * §11 does not currently say this. It should — see the wording proposed on
+ * AGL-1592. Do not resolve the mismatch by making the code forget the number.
+ *
+ * WHY THE MARKER LIVES ON A CLIENT-WRITABLE DOCUMENT. `users/{uid}` is
+ * writable by its owner (and by staff) under the Firestore rules, so this
+ * marker is not tamper-proof. It does not need to be: the only party who can
+ * clear it is the person it protects, and a person clearing their own erasure
+ * marker is a person changing their mind, not an attacker. The adversary here
+ * is our own seeding code path, which is server-side and honours it. Moving
+ * the marker to a server-only document would buy nothing and cost a second
+ * read on every sign-in.
+ *
+ * A stale marker is harmless: it only ever suppresses an IdP prefill, and a
+ * user who types a number back in has a non-blank field, which the seed skips
+ * anyway.
+ *
+ * @param phoneNumber the number to suppress. Defaults to whatever the profile
+ *        currently holds — pass it explicitly when the request named a number
+ *        we do not have on file.
+ * @returns `suppressed` is the E.164 that went onto the do-not-contact list,
+ *          or null when there was no recognizable number to record.
+ */
+export declare function forgetUserPhoneNumber(input: {
+    uid: string;
+    phoneNumber?: string | null;
+    /** Staff member who took the request, for the suppression record. */
+    recordedByUid?: string | null;
+    note?: string | null;
+    firestore?: any;
+}): Promise<{
+    cleared: boolean;
+    suppressed: string | null;
+}>;
+/**
+ * "Delete the address you hold for me" (AGL-1963) — the address half of the
+ * same §11 invariant `forgetUserPhoneNumber` implements for the phone, and
+ * deliberately adjacent to both for the same reason: this sets the marker
+ * that `seedUserProfile` reads, and changing either without the other
+ * silently restores the defect.
+ *
+ * A guard whose marker nothing ever writes is decorative, so this exists
+ * before anything needs it. Two callers do:
+ *
+ *  - Manage Account, when someone clears their own address. That is the
+ *    common case by a wide margin — nobody files a support ticket to remove
+ *    a street address, they empty the field — and without a marker their
+ *    next SSO sign-in puts it straight back.
+ *  - Staff, handling an erasure request against an account the person can no
+ *    longer sign in to.
+ *
+ * `FieldValue.delete()`, not `null`, on the same reasoning as the phone: the
+ * request was to stop holding it, and a nulled field still reads as "we have
+ * an address slot for this person".
+ *
+ * REVERSIBLE BY THE PERSON IT PROTECTS, and only by them. `users/{uid}` is
+ * writable by its owner (and by staff) under the Firestore rules, so this
+ * marker is not tamper-proof and does not need to be — the adversary it
+ * guards against is our own seeding path, which is server-side and honours
+ * it. Someone who types an address back in has a non-blank field, which the
+ * seed skips anyway — and Manage Account drops the marker on that same save,
+ * so opting back into IdP prefill is just filling the field in again.
+ */
+export declare function forgetUserAddress(input: {
+    uid: string;
+    firestore?: any;
+}): Promise<{
+    cleared: boolean;
+}>;
+export default seedUserProfile;