@opengeni/api-router 0.30.3 → 1.0.0

package/src/routes/billing.ts

@@ -1,17 +1,28 @@
 import {
+  BillingCheckoutStatus,
+  CreateBillingPortalRequest,
+  CreateBillingPortalResponse,
   CreateCheckoutRequest,
   CreateCheckoutResponse,
+  OrganizationUsageQuery,
+  OrganizationUsageWorkspacePageQuery,
   type AccessContext,
   type Permission,
 } from "@opengeni/contracts";
+import { OrganizationModelUsageQuery } from "@opengeni/contracts/organization-model-usage";
 import { configuredEntitlements } from "@opengeni/config";
 import {
   applyCreditLedgerEntry,
   getBillingBalance,
   getBillingCustomer,
+  getCreditLedgerEntry,
   hasCreditLedgerEntry,
   isStripeWebhookProcessed,
   listUsageEvents,
+  getOrganizationModelUsage,
+  getOrganizationUsageSummary,
+  getOrganizationUsageWorkspacePage,
+  withSessionRlsActorContext,
   getManagedAccount,
   markStripeWebhookProcessed,
   recordStripeWebhookEvent,
@@ -22,6 +33,7 @@ import { HTTPException } from "hono/http-exception";
 import Stripe from "stripe";
 import { requireAccessContext } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
 
 export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/billing", async (c) => {
@@ -55,6 +67,46 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
     });
   });
 
+  app.get("/v1/billing/usage-summary", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.query("accountId"), "billing:read");
+    const parsed = OrganizationUsageQuery.safeParse(c.req.query());
+    if (!parsed.success) {
+      throw new HTTPException(400, {
+        message: parsed.error.issues[0]?.message ?? "invalid usage query",
+      });
+    }
+    return await withBillingUsageActor(deps, context, accountId, async () =>
+      c.json(await getOrganizationUsageSummary(deps.db, { accountId, ...parsed.data })),
+    );
+  });
+
+  app.get("/v1/billing/usage-workspaces", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.query("accountId"), "billing:read");
+    const parsed = OrganizationUsageWorkspacePageQuery.safeParse(c.req.query());
+    if (!parsed.success)
+      throw new HTTPException(400, {
+        message: parsed.error.issues[0]?.message ?? "invalid usage page query",
+      });
+    return await withBillingUsageActor(deps, context, accountId, async () =>
+      c.json(await getOrganizationUsageWorkspacePage(deps.db, { accountId, ...parsed.data })),
+    );
+  });
+
+  app.get("/v1/billing/usage-models", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.query("accountId"), "billing:read");
+    const parsed = OrganizationModelUsageQuery.safeParse(c.req.query());
+    if (!parsed.success)
+      throw new HTTPException(400, {
+        message: parsed.error.issues[0]?.message ?? "invalid model usage query",
+      });
+    return await withBillingUsageActor(deps, context, accountId, async () =>
+      c.json(await getOrganizationModelUsage(deps.db, { accountId, ...parsed.data })),
+    );
+  });
+
   app.get("/v1/billing/entitlements", async (c) => {
     const context = await requireAccessContext(c, deps);
     const accountId = requireSelectedAccount(context, c.req.query("accountId"), "billing:read");
@@ -78,31 +130,154 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
     const body = parsed.data;
     const accountId = requireSelectedAccount(context, body.accountId, "billing:manage");
-    const amountCents = usdToCents(body.amountUsd);
-    const amountMicros = centsToMicros(amountCents);
     const stripe = stripeClient(deps);
+    const promotion = body.promotionCode
+      ? await resolveCheckoutPromotionCode(stripe, body.promotionCode)
+      : null;
+    const amountCents =
+      body.amountUsd !== undefined
+        ? usdToCents(body.amountUsd)
+        : (promotion?.amountOffCents ?? null);
+    if (amountCents === null) {
+      throw new HTTPException(422, {
+        message: promotion
+          ? "Choose how many credits to buy with this code."
+          : "amountUsd is required",
+      });
+    }
+    if (amountCents < 500 || amountCents > 1_000_000) {
+      throw new HTTPException(422, {
+        message: "Credits must be between $5 and $10,000.",
+      });
+    }
+    const amountMicros = centsToMicros(amountCents);
     const customerId = await getOrCreateStripeCustomer(deps, stripe, context, accountId);
     const idempotencyKey = `checkout:${accountId}:${amountMicros}:${crypto.randomUUID()}`;
-    const session = await stripe.checkout.sessions.create(
-      stripeCheckoutSessionCreateParams({
-        accountId,
+    let session: Stripe.Checkout.Session;
+    try {
+      session = await stripe.checkout.sessions.create(
+        stripeCheckoutSessionCreateParams({
+          accountId,
+          customerId,
+          amountCents,
+          amountMicros,
+          creditsProductId: deps.settings.stripeCreditsProductId,
+          publicBaseUrl: deps.settings.publicBaseUrl,
+          webBaseUrl: deps.settings.webBaseUrl,
+          successUrl: body.successUrl,
+          cancelUrl: body.cancelUrl,
+          idempotencyKey,
+          ...(promotion
+            ? {
+                promotionCodeId: promotion.id,
+                fullyDiscounted:
+                  promotion.percentOff === 100 || (promotion.amountOffCents ?? 0) >= amountCents,
+              }
+            : {}),
+        }),
+        { idempotencyKey },
+      );
+    } catch (error) {
+      // Stripe refuses a code whose restrictions this purchase doesn't meet
+      // (first purchase only, a minimum amount, another customer's code).
+      if (promotion && error instanceof Stripe.errors.StripeInvalidRequestError) {
+        throw new HTTPException(422, { message: "This code can't be used for this purchase." });
+      }
+      throw error;
+    }
+    if (!session.url) {
+      throw new HTTPException(502, { message: "Stripe did not return a checkout URL" });
+    }
+    return c.json(
+      CreateCheckoutResponse.parse({
+        checkoutSessionId: session.id,
+        url: session.url,
+        amountUsd: amountCents / 100,
+      }),
+    );
+  });
+
+  // Where one checkout stands, for the page the customer returns to. Credits
+  // normally post from the webhook; a completed checkout whose webhook has not
+  // arrived yet is settled here from Stripe's own record of the session, under
+  // the same ledger idempotency key, so it grants at most once.
+  app.get("/v1/billing/checkout/:checkoutSessionId", async (c) => {
+    if (deps.settings.billingMode !== "stripe") {
+      throw new HTTPException(404, { message: "stripe billing is not enabled" });
+    }
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.query("accountId"), "billing:read");
+    const checkoutSessionId = c.req.param("checkoutSessionId");
+    if (!/^cs_[A-Za-z0-9_]{1,250}$/.test(checkoutSessionId)) {
+      throw new HTTPException(404, { message: "checkout not found" });
+    }
+    const stripe = stripeClient(deps);
+    let session: Stripe.Checkout.Session;
+    try {
+      session = await stripe.checkout.sessions.retrieve(checkoutSessionId);
+    } catch (error) {
+      if (error instanceof Stripe.errors.StripeInvalidRequestError) {
+        throw new HTTPException(404, { message: "checkout not found" });
+      }
+      throw error;
+    }
+    if (session.metadata?.opengeni_account_id !== accountId) {
+      throw new HTTPException(404, { message: "checkout not found" });
+    }
+    const credit = creditMetadata(session.metadata, `Stripe checkout session ${session.id}`);
+    let entry = await getCreditLedgerEntry(deps.db, accountId, credit.idempotencyKey);
+    if (!entry && session.status === "complete") {
+      await grantCheckoutSessionCredits(deps, session, {
+        stripeEventId: null,
+        livemode: session.livemode,
+      });
+      entry = await getCreditLedgerEntry(deps.db, accountId, credit.idempotencyKey);
+    }
+    return c.json(
+      BillingCheckoutStatus.parse({
+        checkoutSessionId: session.id,
+        status: session.status ?? "open",
+        credit: {
+          state: entry ? "granted" : "pending",
+          amountMicros: entry?.amountMicros ?? credit.amountMicros,
+          currency: "usd",
+          free: entry
+            ? entry.sourceType === "stripe_checkout_coupon"
+            : isFreeCouponCheckout(session),
+        },
+        balance: entry ? await getBillingBalance(deps.db, accountId) : null,
+      }),
+    );
+  });
+
+  app.post("/v1/billing/portal", async (c) => {
+    if (deps.settings.billingMode !== "stripe") {
+      throw new HTTPException(404, { message: "stripe billing is not enabled" });
+    }
+    const context = await requireAccessContext(c, deps);
+    const parsed = CreateBillingPortalRequest.safeParse(await c.req.json());
+    if (!parsed.success) {
+      throw new HTTPException(400, {
+        message: parsed.error.issues[0]?.message ?? "invalid billing portal request",
+      });
+    }
+    const accountId = requireSelectedAccount(context, parsed.data.accountId, "billing:manage");
+    const stripe = stripeClient(deps);
+    const customerId = await getOrCreateStripeCustomer(deps, stripe, context, accountId);
+    const session = await stripe.billingPortal.sessions.create(
+      stripeBillingPortalSessionCreateParams({
         customerId,
-        amountCents,
-        amountMicros,
-        creditsProductId: deps.settings.stripeCreditsProductId,
         publicBaseUrl: deps.settings.publicBaseUrl,
-        successUrl: body.successUrl,
-        cancelUrl: body.cancelUrl,
-        idempotencyKey,
+        webBaseUrl: deps.settings.webBaseUrl,
+        returnUrl: parsed.data.returnUrl,
       }),
-      { idempotencyKey },
     );
     if (!session.url) {
-      throw new HTTPException(502, { message: "Stripe did not return a checkout URL" });
+      throw new HTTPException(502, { message: "Stripe did not return a billing portal URL" });
     }
     return c.json(
-      CreateCheckoutResponse.parse({
-        checkoutSessionId: session.id,
+      CreateBillingPortalResponse.parse({
+        portalSessionId: session.id,
         url: session.url,
       }),
     );
@@ -159,24 +334,39 @@ export function stripeCheckoutSessionCreateParams(input: {
   amountMicros: number;
   creditsProductId?: string | undefined;
   publicBaseUrl?: string | undefined;
+  webBaseUrl?: string | undefined;
   successUrl?: string | undefined;
   cancelUrl?: string | undefined;
   idempotencyKey: string;
+  /** Apply this promotion code up front instead of letting Stripe ask for one. */
+  promotionCodeId?: string | undefined;
+  /**
+   * The applied code covers the whole package, so the total is $0. Nothing is
+   * taxable, so Checkout skips tax and with it the billing address: the
+   * customer only confirms.
+   */
+  fullyDiscounted?: boolean | undefined;
 }): Stripe.Checkout.SessionCreateParams {
   const successUrl = checkoutReturnUrl(
     input.publicBaseUrl,
+    input.webBaseUrl,
     input.successUrl,
     "/billing?checkout=success",
     "successUrl",
   );
   const cancelUrl = checkoutReturnUrl(
     input.publicBaseUrl,
+    input.webBaseUrl,
     input.cancelUrl,
     "/billing?checkout=cancelled",
     "cancelUrl",
   );
   return {
     mode: "payment",
+    // Stripe takes either a code field on its page or one discount up front.
+    ...(input.promotionCodeId
+      ? { discounts: [{ promotion_code: input.promotionCodeId }] }
+      : { allow_promotion_codes: true }),
     customer: input.customerId,
     customer_update: {
       address: "auto",
@@ -184,7 +374,7 @@ export function stripeCheckoutSessionCreateParams(input: {
     },
     success_url: successUrl,
     cancel_url: cancelUrl,
-    automatic_tax: { enabled: true },
+    automatic_tax: { enabled: !(input.promotionCodeId && input.fullyDiscounted) },
     billing_address_collection: "auto",
     line_items: [
       {
@@ -196,7 +386,7 @@ export function stripeCheckoutSessionCreateParams(input: {
             ? { product: input.creditsProductId }
             : {
                 product_data: {
-                  name: "OpenGeni credits",
+                  name: "Opengeni credits",
                   metadata: {
                     app: "opengeni",
                     billing_model: "prepaid_credits",
@@ -211,6 +401,7 @@ export function stripeCheckoutSessionCreateParams(input: {
       opengeni_credit_amount_usd: (input.amountCents / 100).toFixed(2),
       opengeni_credit_micros: String(input.amountMicros),
       opengeni_credit_idempotency_key: input.idempotencyKey,
+      opengeni_credit_coupon_v1: "1",
     },
     payment_intent_data: {
       metadata: {
@@ -218,30 +409,65 @@ export function stripeCheckoutSessionCreateParams(input: {
         opengeni_credit_amount_usd: (input.amountCents / 100).toFixed(2),
         opengeni_credit_micros: String(input.amountMicros),
         opengeni_credit_idempotency_key: input.idempotencyKey,
+        opengeni_credit_coupon_v1: "1",
+      },
+    },
+    invoice_creation: {
+      enabled: true,
+      invoice_data: {
+        metadata: {
+          opengeni_account_id: input.accountId,
+          opengeni_credit_amount_usd: (input.amountCents / 100).toFixed(2),
+          opengeni_credit_micros: String(input.amountMicros),
+          opengeni_credit_idempotency_key: input.idempotencyKey,
+          opengeni_credit_coupon_v1: "1",
+        },
       },
     },
   };
 }
 
+export function stripeBillingPortalSessionCreateParams(input: {
+  customerId: string;
+  publicBaseUrl?: string | undefined;
+  webBaseUrl?: string | undefined;
+  returnUrl?: string | undefined;
+}): Stripe.BillingPortal.SessionCreateParams {
+  return {
+    customer: input.customerId,
+    return_url: checkoutReturnUrl(
+      input.publicBaseUrl,
+      input.webBaseUrl,
+      input.returnUrl,
+      "/billing",
+      "returnUrl",
+    ),
+  };
+}
+
 function checkoutReturnUrl(
   publicBaseUrl: string | undefined,
+  webBaseUrl: string | undefined,
   candidate: string | undefined,
   fallbackPath: string,
   field: string,
 ): string {
   if (!publicBaseUrl) {
     throw new HTTPException(500, {
-      message: "OPENGENI_PUBLIC_BASE_URL is required for Stripe checkout",
+      message: "OPENGENI_PUBLIC_BASE_URL is required for Stripe redirects",
     });
   }
-  const base = new URL(publicBaseUrl);
+  const base = new URL(webBaseUrl ?? publicBaseUrl);
   const fallback = new URL(fallbackPath, base).toString();
   if (!candidate) {
     return fallback;
   }
   const parsed = new URL(candidate);
-  if (parsed.origin !== base.origin) {
-    throw new HTTPException(400, { message: `${field} must use the OpenGeni public origin` });
+  const allowedOrigins = new Set([new URL(publicBaseUrl).origin, base.origin]);
+  if (!allowedOrigins.has(parsed.origin)) {
+    throw new HTTPException(400, {
+      message: `${field} must use the Opengeni public${allowedOrigins.size > 1 ? " or web" : ""} origin`,
+    });
   }
   return parsed.toString();
 }
@@ -253,7 +479,12 @@ async function handleStripeWebhookEvent(
 ): Promise<void> {
   switch (event.type) {
     case "checkout.session.completed":
-      await handleCheckoutSessionCompleted(deps, event);
+    case "checkout.session.async_payment_succeeded":
+      await handleCheckoutSessionPayment(deps, event);
+      return;
+    case "checkout.session.async_payment_failed":
+      // A delayed payment method failed. Completion reported it `unpaid`, so
+      // no credit was granted and there is nothing to reverse.
       return;
     case "checkout.session.expired":
     case "payment_intent.succeeded":
@@ -289,42 +520,171 @@ async function handleStripeWebhookEvent(
   }
 }
 
-async function handleCheckoutSessionCompleted(
+export type StripeCheckoutCreditDecision =
+  | { action: "grant"; credit: CheckoutCreditMetadata }
+  | { action: "ignore"; reason: "foreign_checkout" | "not_payment_mode" | "payment_not_paid" };
+
+/**
+ * Decides whether a Checkout Session webhook grants OpenGeni credits.
+ *
+ * Sessions created outside OpenGeni on the same Stripe account carry no
+ * `opengeni_` metadata and are acknowledged without effect. An OpenGeni
+ * session with malformed credit metadata still throws so the failure stays
+ * visible. Credits are granted once Stripe reports the payment `paid` or a
+ * completed checkout fully covered by a coupon:
+ * on `checkout.session.completed` for immediate methods, or on
+ * `checkout.session.async_payment_succeeded` for delayed methods, whose
+ * completion event arrives `unpaid`. Both events carry the same session
+ * metadata, so the ledger idempotency key grants at most once.
+ */
+export function stripeCheckoutCreditDecision(
+  session: Stripe.Checkout.Session,
+): StripeCheckoutCreditDecision {
+  if (!Object.keys(session.metadata ?? {}).some((key) => key.startsWith("opengeni_"))) {
+    return { action: "ignore", reason: "foreign_checkout" };
+  }
+  if (session.mode !== "payment") {
+    return { action: "ignore", reason: "not_payment_mode" };
+  }
+  if (session.payment_status !== "paid" && !isFreeCouponCheckout(session)) {
+    return { action: "ignore", reason: "payment_not_paid" };
+  }
+  const credit = creditMetadata(session.metadata, `Stripe checkout session ${session.id}`);
+  if (
+    session.metadata?.opengeni_credit_coupon_v1 === "1" &&
+    (session.currency !== "usd" ||
+      session.amount_subtotal !== credit.amountMicros / 10_000 ||
+      typeof session.amount_total !== "number" ||
+      !Number.isSafeInteger(session.amount_total) ||
+      session.amount_total < 0)
+  ) {
+    throw new Error(`Stripe checkout session ${session.id} has invalid credit package totals`);
+  }
+  return { action: "grant", credit };
+}
+
+function isFreeCouponCheckout(session: Stripe.Checkout.Session): boolean {
+  return (
+    (session.payment_status === "paid" || session.payment_status === "no_payment_required") &&
+    session.status === "complete" &&
+    session.amount_total === 0 &&
+    typeof session.amount_subtotal === "number" &&
+    session.amount_subtotal > 0 &&
+    (session.total_details?.amount_discount ?? 0) >= session.amount_subtotal
+  );
+}
+
+async function handleCheckoutSessionPayment(
   deps: ApiRouteDeps,
   event: Stripe.Event,
 ): Promise<void> {
-  const session = event.data.object as Stripe.Checkout.Session;
-  if (session.mode !== "payment" || session.payment_status !== "paid") {
+  await grantCheckoutSessionCredits(deps, event.data.object as Stripe.Checkout.Session, {
+    stripeEventId: event.id,
+    stripeEventType: event.type,
+    livemode: event.livemode,
+  });
+}
+
+/**
+ * Grants a paid (or fully coupon-covered) OpenGeni checkout's credits once.
+ * The webhook calls this with its event; the checkout status read calls it
+ * with the session it retrieved from Stripe when the webhook is late.
+ */
+async function grantCheckoutSessionCredits(
+  deps: ApiRouteDeps,
+  session: Stripe.Checkout.Session,
+  source: { stripeEventId: string | null; stripeEventType?: string; livemode: boolean },
+): Promise<void> {
+  const decision = stripeCheckoutCreditDecision(session);
+  if (decision.action === "ignore") {
+    if (decision.reason === "foreign_checkout") {
+      console.info("[api] stripe webhook ignored a checkout session not created by OpenGeni", {
+        stripeEventType: source.stripeEventType ?? null,
+        livemode: source.livemode,
+      });
+    }
+    return;
+  }
+  const credit = decision.credit;
+  const freeCouponCheckout = isFreeCouponCheckout(session);
+  if (!(await getManagedAccount(deps.db, credit.accountId))) {
+    // Another OpenGeni deployment sharing the Stripe account (or an account
+    // removed before a delayed payment settled). Retrying cannot succeed, so
+    // acknowledge instead of failing the delivery for days.
+    console.info(
+      "[api] stripe webhook ignored a checkout session for an account not in this deployment",
+      {
+        stripeEventType: source.stripeEventType ?? null,
+        livemode: source.livemode,
+      },
+    );
     return;
   }
-  const credit = creditMetadata(session.metadata, `Stripe checkout session ${session.id}`);
   const customerId = typeof session.customer === "string" ? session.customer : session.customer?.id;
   if (customerId) {
     await upsertBillingCustomer(deps.db, {
       accountId: credit.accountId,
-      provider: stripeCustomerProvider(event),
+      provider: source.livemode ? "stripe:live" : "stripe:test",
       providerCustomerId: customerId,
       email: session.customer_details?.email ?? session.customer_email ?? null,
     });
   }
+  if (await hasCreditLedgerEntry(deps.db, credit.accountId, credit.idempotencyKey)) {
+    return;
+  }
   await applyCreditLedgerEntry(deps.db, {
     accountId: credit.accountId,
-    type: "credit_topup",
+    type: freeCouponCheckout ? "grant" : "credit_topup",
     amountMicros: credit.amountMicros,
-    sourceType: "stripe_checkout_session",
+    sourceType: freeCouponCheckout ? "stripe_checkout_coupon" : "stripe_checkout_session",
     sourceId: session.id,
     idempotencyKey: credit.idempotencyKey,
     metadata: {
-      stripeEventId: event.id,
+      stripeEventId: source.stripeEventId,
       stripePaymentIntentId:
         typeof session.payment_intent === "string"
           ? session.payment_intent
           : (session.payment_intent?.id ?? null),
       stripePackageId: credit.packageId,
       stripeCreditAmountUsd: credit.amountUsd,
+      ...(session.metadata?.opengeni_credit_coupon_v1 === "1"
+        ? {
+            stripeAmountTotalCents: session.amount_total,
+            stripeDiscountCents: session.total_details?.amount_discount ?? 0,
+          }
+        : {}),
     },
   });
-  recordCreditMicrosMetric(deps, "topup", credit.amountMicros);
+  recordCreditMicrosMetric(deps, freeCouponCheckout ? "grant" : "topup", credit.amountMicros);
+}
+
+/**
+ * Looks up a customer-typed promotion code. Stripe matches codes without
+ * regard to case. A fixed USD amount off sets the credits a checkout buys.
+ */
+async function resolveCheckoutPromotionCode(
+  stripe: Stripe,
+  code: string,
+): Promise<{ id: string; amountOffCents: number | null; percentOff: number | null }> {
+  const listed = await stripe.promotionCodes.list({
+    code,
+    active: true,
+    limit: 1,
+    expand: ["data.promotion.coupon"],
+  });
+  const promotionCode = listed.data[0];
+  const coupon =
+    promotionCode && typeof promotionCode.promotion?.coupon === "object"
+      ? promotionCode.promotion.coupon
+      : null;
+  if (!promotionCode || !coupon?.valid) {
+    throw new HTTPException(422, { message: "That code isn't valid or has expired." });
+  }
+  const amountOffCents =
+    coupon.amount_off && coupon.currency === "usd"
+      ? coupon.amount_off
+      : (coupon.currency_options?.usd?.amount_off ?? null);
+  return { id: promotionCode.id, amountOffCents, percentOff: coupon.percent_off ?? null };
 }
 
 async function mirrorPaymentIntentCustomer(deps: ApiRouteDeps, event: Stripe.Event): Promise<void> {
@@ -377,19 +737,21 @@ async function applyRefundDebit(
   if (await hasCreditLedgerEntry(deps.db, accountId, idempotencyKey)) {
     return;
   }
+  const debitMicros = await creditAdjustmentMicros(deps, metadata, refund.amount);
   await applyCreditLedgerEntry(deps.db, {
     accountId,
     type: "credit_refund",
-    amountMicros: -centsToMicros(refund.amount),
+    amountMicros: -debitMicros,
     sourceType: "stripe_refund",
     sourceId: refund.id,
     idempotencyKey,
     metadata: {
       stripeRefundId: refund.id,
       stripePaymentIntentId: paymentIntentId(refund.payment_intent),
+      stripeRefundAmountCents: refund.amount,
     },
   });
-  recordCreditMicrosMetric(deps, "refund", centsToMicros(refund.amount));
+  recordCreditMicrosMetric(deps, "refund", debitMicros);
 }
 
 async function holdDisputedCredits(
@@ -403,10 +765,11 @@ async function holdDisputedCredits(
   if (!accountId) {
     return;
   }
+  const debitMicros = await creditAdjustmentMicros(deps, metadata, dispute.amount);
   await applyCreditLedgerEntry(deps.db, {
     accountId,
     type: "credit_dispute_hold",
-    amountMicros: -centsToMicros(dispute.amount),
+    amountMicros: -debitMicros,
     sourceType: "stripe_dispute",
     sourceId: dispute.id,
     idempotencyKey: `stripe:dispute_hold:${dispute.id}`,
@@ -432,10 +795,11 @@ async function releaseDisputedCredits(
   if (!(await hasCreditLedgerEntry(deps.db, accountId, holdIdempotencyKey))) {
     return;
   }
+  const debitMicros = await creditAdjustmentMicros(deps, metadata, dispute.amount);
   await applyCreditLedgerEntry(deps.db, {
     accountId,
     type: "credit_dispute_release",
-    amountMicros: centsToMicros(dispute.amount),
+    amountMicros: debitMicros,
     sourceType: "stripe_dispute",
     sourceId: dispute.id,
     idempotencyKey: `stripe:dispute_release:${dispute.id}`,
@@ -443,6 +807,34 @@ async function releaseDisputedCredits(
   });
 }
 
+async function creditAdjustmentMicros(
+  deps: ApiRouteDeps,
+  metadata: Stripe.Metadata | null,
+  amountCents: number,
+): Promise<number> {
+  if (metadata?.opengeni_credit_coupon_v1 !== "1") return centsToMicros(amountCents);
+  const credit = creditMetadata(metadata, "Stripe adjustment");
+  const entry = await getCreditLedgerEntry(deps.db, credit.accountId, credit.idempotencyKey);
+  const paidCents = entry?.metadata.stripeAmountTotalCents;
+  if (
+    entry?.sourceType !== "stripe_checkout_session" ||
+    entry.amountMicros !== credit.amountMicros ||
+    typeof paidCents !== "number" ||
+    !Number.isSafeInteger(paidCents) ||
+    paidCents <= 0 ||
+    !Number.isSafeInteger(amountCents) ||
+    amountCents <= 0
+  ) {
+    throw new Error("Stripe credit adjustment is missing a settled checkout");
+  }
+  const proportionalMicros =
+    (BigInt(entry.amountMicros) * BigInt(amountCents) + BigInt(Math.floor(paidCents / 2))) /
+    BigInt(paidCents);
+  return Number(
+    proportionalMicros > BigInt(entry.amountMicros) ? entry.amountMicros : proportionalMicros,
+  );
+}
+
 async function mirrorCustomer(
   deps: ApiRouteDeps,
   event: Stripe.Event,
@@ -480,18 +872,20 @@ async function metadataForRefund(
   stripe: Stripe,
   refund: Stripe.Refund,
 ): Promise<Stripe.Metadata | null> {
-  if (Object.keys(refund.metadata ?? {}).length > 0) {
+  if (refund.metadata?.opengeni_credit_idempotency_key) {
     return refund.metadata;
   }
   const paymentIntent = paymentIntentId(refund.payment_intent);
-  return paymentIntent ? (await stripe.paymentIntents.retrieve(paymentIntent)).metadata : null;
+  return paymentIntent
+    ? (await stripe.paymentIntents.retrieve(paymentIntent)).metadata
+    : refund.metadata;
 }
 
 async function metadataForDispute(
   stripe: Stripe,
   dispute: Stripe.Dispute,
 ): Promise<Stripe.Metadata | null> {
-  if (Object.keys(dispute.metadata ?? {}).length > 0) {
+  if (dispute.metadata?.opengeni_credit_idempotency_key) {
     return dispute.metadata;
   }
   const paymentIntent = paymentIntentId(
@@ -503,7 +897,7 @@ async function metadataForDispute(
   }
   const chargeId = typeof dispute.charge === "string" ? dispute.charge : dispute.charge?.id;
   if (!chargeId) {
-    return null;
+    return dispute.metadata;
   }
   const charge = await stripe.charges.retrieve(chargeId);
   const chargePaymentIntent = paymentIntentId(charge.payment_intent);
@@ -512,21 +906,23 @@ async function metadataForDispute(
     : charge.metadata;
 }
 
-function creditMetadata(
-  metadata: Stripe.Metadata | null | undefined,
-  label: string,
-): {
+export type CheckoutCreditMetadata = {
   accountId: string;
   amountMicros: number;
   idempotencyKey: string;
   amountUsd?: string;
   packageId?: string;
-} {
+};
+
+function creditMetadata(
+  metadata: Stripe.Metadata | null | undefined,
+  label: string,
+): CheckoutCreditMetadata {
   const accountId = metadata?.opengeni_account_id;
   const amountMicros = Number(metadata?.opengeni_credit_micros);
   const idempotencyKey = metadata?.opengeni_credit_idempotency_key;
   if (!accountId || !Number.isSafeInteger(amountMicros) || amountMicros <= 0 || !idempotencyKey) {
-    throw new Error(`${label} is missing OpenGeni credit metadata`);
+    throw new Error(`${label} is missing Opengeni credit metadata`);
   }
   return {
     accountId,
@@ -582,7 +978,26 @@ export function stripeCustomerProvider(
     : "stripe:test";
 }
 
-function requireSelectedAccount(
+/** Billing routes do not traverse the workspace actor middleware. Always bind
+ * these reads explicitly; only a revalidated live attempt may supply a human
+ * initiator. Neither query parameters nor serviceInitiator claims are proof. */
+export async function withBillingUsageActor<T>(
+  deps: ApiRouteDeps,
+  context: AccessContext,
+  accountId: string,
+  read: () => Promise<T>,
+): Promise<T> {
+  const attemptGrant = context.workspaceGrants.find(
+    (grant) =>
+      grant.accountId === accountId &&
+      grant.subjectId === context.subjectId &&
+      grant.principalKind === "agent_attempt",
+  );
+  if (attemptGrant) return await withAccessGrantSessionRlsContext(deps, attemptGrant, read);
+  return await withSessionRlsActorContext({ subjectId: context.subjectId }, read);
+}
+
+export function requireSelectedAccount(
   context: AccessContext,
   requested: string | undefined,
   permission: Permission,