@opengeni/api-router 1.1.0 → 1.2.0

package/src/routes/billing.ts

@@ -8,12 +8,15 @@ import {
   OrganizationUsageWorkspacePageQuery,
   type AccessContext,
   type Permission,
+  type PromotionalCreditScope,
 } from "@opengeni/contracts";
 import { OrganizationModelUsageQuery } from "@opengeni/contracts/organization-model-usage";
-import { configuredEntitlements } from "@opengeni/config";
+import { configuredEntitlements, promotionalCreditScope } from "@opengeni/config";
+import { creditScopeMetadata, creditScopeFromMetadata } from "../credit-promotion-snapshot";
 import {
   applyCreditLedgerEntry,
   getBillingBalance,
+  readCreditPromotionPolicy,
   getBillingCustomer,
   getCreditLedgerEntry,
   hasCreditLedgerEntry,
@@ -23,6 +26,7 @@ import {
   getOrganizationUsageSummary,
   getOrganizationUsageWorkspacePage,
   withSessionRlsActorContext,
+  withRlsContext,
   getManagedAccount,
   markStripeWebhookProcessed,
   recordStripeWebhookEvent,
@@ -134,6 +138,15 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
     const promotion = body.promotionCode
       ? await resolveCheckoutPromotionCode(stripe, body.promotionCode)
       : null;
+    const promotionalScope = promotion
+      ? promotionalCreditScope(
+          {
+            creditPromotionPolicy:
+              (await readCreditPromotionPolicy(deps.db)) ?? deps.settings.creditPromotionPolicy,
+          },
+          promotion.couponId,
+        )
+      : undefined;
     const amountCents =
       body.amountUsd !== undefined
         ? usdToCents(body.amountUsd)
@@ -150,6 +163,15 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "Credits must be between $5 and $10,000.",
       });
     }
+    if (
+      promotionalScope &&
+      (!promotion?.amountOffCents || amountCents !== promotion.amountOffCents)
+    ) {
+      throw new HTTPException(422, {
+        message:
+          "Redeem this offer for its exact credit amount. Buy additional credits separately.",
+      });
+    }
     const amountMicros = centsToMicros(amountCents);
     const customerId = await getOrCreateStripeCustomer(deps, stripe, context, accountId);
     const idempotencyKey = `checkout:${accountId}:${amountMicros}:${crypto.randomUUID()}`;
@@ -167,9 +189,11 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
           successUrl: body.successUrl,
           cancelUrl: body.cancelUrl,
           idempotencyKey,
+          promotionalScope,
           ...(promotion
             ? {
                 promotionCodeId: promotion.id,
+                couponId: promotion.couponId,
                 fullyDiscounted:
                   promotion.percentOff === 100 || (promotion.amountOffCents ?? 0) >= amountCents,
               }
@@ -193,6 +217,7 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
         checkoutSessionId: session.id,
         url: session.url,
         amountUsd: amountCents / 100,
+        promotionalScope,
       }),
     );
   });
@@ -241,6 +266,7 @@ export function registerBillingRoutes(app: Hono, deps: ApiRouteDeps): void {
           state: entry ? "granted" : "pending",
           amountMicros: entry?.amountMicros ?? credit.amountMicros,
           currency: "usd",
+          promotionalScope: creditScopeFromMetadata(session.metadata),
           free: entry
             ? entry.sourceType === "stripe_checkout_coupon"
             : isFreeCouponCheckout(session),
@@ -340,6 +366,8 @@ export function stripeCheckoutSessionCreateParams(input: {
   idempotencyKey: string;
   /** Apply this promotion code up front instead of letting Stripe ask for one. */
   promotionCodeId?: string | undefined;
+  couponId?: string | undefined;
+  promotionalScope?: PromotionalCreditScope | 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
@@ -366,7 +394,7 @@ export function stripeCheckoutSessionCreateParams(input: {
     // 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 }),
+      : { allow_promotion_codes: false }),
     customer: input.customerId,
     customer_update: {
       address: "auto",
@@ -397,6 +425,8 @@ export function stripeCheckoutSessionCreateParams(input: {
       },
     ],
     metadata: {
+      ...creditScopeMetadata(input.promotionalScope),
+      ...(input.couponId ? { opengeni_credit_offer_id: input.couponId } : {}),
       opengeni_account_id: input.accountId,
       opengeni_credit_amount_usd: (input.amountCents / 100).toFixed(2),
       opengeni_credit_micros: String(input.amountMicros),
@@ -607,6 +637,10 @@ async function grantCheckoutSessionCredits(
   }
   const credit = decision.credit;
   const freeCouponCheckout = isFreeCouponCheckout(session);
+  const promotionalScope = creditScopeFromMetadata(session.metadata);
+  if (promotionalScope && !freeCouponCheckout) {
+    throw new Error("Scoped promotional credits require a fully discounted checkout");
+  }
   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
@@ -636,10 +670,13 @@ async function grantCheckoutSessionCredits(
     accountId: credit.accountId,
     type: freeCouponCheckout ? "grant" : "credit_topup",
     amountMicros: credit.amountMicros,
+    eligibleModelIds: promotionalScope?.eligibleModelIds,
     sourceType: freeCouponCheckout ? "stripe_checkout_coupon" : "stripe_checkout_session",
     sourceId: session.id,
     idempotencyKey: credit.idempotencyKey,
     metadata: {
+      ...(promotionalScope ? { creditOfferLabel: promotionalScope.label } : {}),
+      creditOfferId: session.metadata?.opengeni_credit_offer_id ?? null,
       stripeEventId: source.stripeEventId,
       stripePaymentIntentId:
         typeof session.payment_intent === "string"
@@ -665,7 +702,12 @@ async function grantCheckoutSessionCredits(
 async function resolveCheckoutPromotionCode(
   stripe: Stripe,
   code: string,
-): Promise<{ id: string; amountOffCents: number | null; percentOff: number | null }> {
+): Promise<{
+  id: string;
+  couponId: string;
+  amountOffCents: number | null;
+  percentOff: number | null;
+}> {
   const listed = await stripe.promotionCodes.list({
     code,
     active: true,
@@ -684,7 +726,12 @@ async function resolveCheckoutPromotionCode(
     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 };
+  return {
+    id: promotionCode.id,
+    couponId: coupon.id,
+    amountOffCents,
+    percentOff: coupon.percent_off ?? null,
+  };
 }
 
 async function mirrorPaymentIntentCustomer(deps: ApiRouteDeps, event: Stripe.Event): Promise<void> {
@@ -792,18 +839,28 @@ async function releaseDisputedCredits(
     return;
   }
   const holdIdempotencyKey = `stripe:dispute_hold:${dispute.id}`;
-  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: debitMicros,
-    sourceType: "stripe_dispute",
-    sourceId: dispute.id,
-    idempotencyKey: `stripe:dispute_release:${dispute.id}`,
-    metadata: { stripeDisputeId: dispute.id, stripeEventType: event.type },
+  await withRlsContext(deps.db, { accountId }, async (tx) => {
+    // Stripe can deliver the resolution before the hold. Materialize both
+    // receipts atomically so a late hold cannot withhold restored credits.
+    await applyCreditLedgerEntry(tx, {
+      accountId,
+      type: "credit_dispute_hold",
+      amountMicros: -debitMicros,
+      sourceType: "stripe_dispute",
+      sourceId: dispute.id,
+      idempotencyKey: holdIdempotencyKey,
+      metadata: { stripeDisputeId: dispute.id, stripeEventType: event.type },
+    });
+    await applyCreditLedgerEntry(tx, {
+      accountId,
+      type: "credit_dispute_release",
+      amountMicros: debitMicros,
+      sourceType: "stripe_dispute",
+      sourceId: dispute.id,
+      idempotencyKey: `stripe:dispute_release:${dispute.id}`,
+      metadata: { stripeDisputeId: dispute.id, stripeEventType: event.type },
+    });
   });
 }
 

package/src/routes/managed-onboarding.ts

@@ -1,3 +1,4 @@
+import { signupCreditModelIds } from "@opengeni/config";
 import {
   CompleteSelfServiceOrganizationSetupRequest,
   CompleteSelfServiceOrganizationSetupResponse,
@@ -80,6 +81,7 @@ export function registerManagedOnboardingRoutes(
           organizationName,
           operationId: parsed.data.operationId,
           requestFingerprint,
+          trialCreditModelIds: signupCreditModelIds(deps.settings),
           trialCreditsEnabled:
             deps.settings.productAccessMode === "managed" &&
             deps.settings.verifiedSignupTrialCreditsEnabled,

package/src/routes/organization-memberships.ts

@@ -1,3 +1,4 @@
+import { signupCreditModelIds } from "@opengeni/config";
 import {
   lookupExternalIdentityForRequest,
   cancelExternalWorkspaceMemberGrantForRequest,
@@ -310,6 +311,7 @@ export function registerOrganizationMembershipRoutes(app: Hono, deps: ApiRouteDe
             subjectId,
             subjectLabel: session.user.email || session.user.name,
             ...payload,
+            trialCreditModelIds: signupCreditModelIds(deps.settings),
             trialCreditsEnabled:
               deps.settings.productAccessMode === "managed" &&
               deps.settings.verifiedSignupTrialCreditsEnabled,

package/src/routes/workspaces.ts

@@ -48,6 +48,8 @@ import {
 import { loadWorkspaceCodexModelAvailability } from "@opengeni/core";
 import {
   allWorkspacePermissions,
+  getBillingBalance,
+  spendableCreditMicros,
   createWorkspace,
   ensureWorkspaceByExternalIdentity,
   findWorkspaceByExternalIdentity,
@@ -621,25 +623,38 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     // The same precedence the server applies when a new chat, API create, or
     // scheduled occurrence names no model; published so pickers show it.
     const workspaceSettings = workspace?.settings ?? {};
+    const creditBalance =
+      deps.settings.billingMode === "stripe"
+        ? await getBillingBalance(deps.db, grant.accountId)
+        : undefined;
     const defaultSelection = await resolveDefaultSessionModelForSelections(deps.db, {
       settings: workspaceCatalogSettings,
       accountId: grant.accountId,
       workspaceSettings,
       selections,
     });
+    const catalog = projectWorkspaceModelCatalog(selections, {
+      defaultSelection,
+      creditsSelection: creditsDefaultSessionModel({
+        settings: workspaceCatalogSettings,
+        selections,
+        workspaceSettings,
+      }),
+    });
+    if (creditBalance) {
+      for (const model of catalog.models) {
+        if (model.cost !== "credits") continue;
+        model.creditFunding = creditBalance.promotionalCredits?.some(
+          (credit) => credit.remainingMicros > 0 && credit.eligibleModelIds.includes(model.id),
+        )
+          ? "promotional"
+          : spendableCreditMicros(creditBalance, model.id) > 0
+            ? "general"
+            : "unavailable";
+      }
+    }
     c.header("cache-control", "private, no-store");
-    return c.json(
-      WorkspaceModelCatalogResponse.parse(
-        projectWorkspaceModelCatalog(selections, {
-          defaultSelection,
-          creditsSelection: creditsDefaultSessionModel({
-            settings: workspaceCatalogSettings,
-            selections,
-            workspaceSettings,
-          }),
-        }),
-      ),
-    );
+    return c.json(WorkspaceModelCatalogResponse.parse(catalog));
   });
 
   app.get("/v1/workspaces/:workspaceId/gateway-custom-models", async (c) => {