Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: stack-auth/stack-auth#0
File: AGENTS.md:0-0
Timestamp: 2025-10-20T22:25:40.427Z
Learning: Applies to apps/backend/src/app/api/latest/**/route.ts : In backend API routes, use the custom route handler system to ensure consistent API responses

apps/dashboard/src/components/data-table/transaction-table.tsx (1)

131-139: USD-only handling remains unresolved.

This issue was already flagged in a previous review. The function still only displays USD amounts and shows '—' for all other currencies, which blanks the amount column for non-USD tenants. Please refer to the previous review comment for the proposed solution.

apps/dashboard/src/components/data-table/transaction-table.tsx (2)

51-58: Consider simplifying the redundant check.

The condition at line 56 returns 'other' when a productGrant exists without subscription or purchase IDs, but line 57 also returns 'other' as the default. Since both paths lead to the same result, line 56 can be removed.

Apply this diff:

 function deriveSourceType(transaction: Transaction): SourceType {
   if (transaction.entries.some(isItemQuantityChangeEntry)) return 'item_quantity_change';
   const productGrant = transaction.entries.find(isProductGrantEntry);
   if (productGrant?.subscription_id) return 'subscription';
   if (productGrant?.one_time_purchase_id) return 'one_time';
-  if (productGrant) return 'other';
   return 'other';
 }

---

86-89: Improve type safety in the default fallback.

The as any cast suppresses type checking. Since transactionType is typed as TransactionType | null, the default case should only handle null. Consider using a type-safe fallback.

Apply this diff:

     default: {
-      return { label: (transactionType as any) ?? '—', Icon: CircleHelp };
+      return { label: transactionType ?? 'Unknown', Icon: CircleHelp };
     }

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

apps/dashboard/src/components/data-table/transaction-table.tsx (2)

131-139: Fix amount display for non-USD charges.

This issue was flagged in a previous review and remains unresolved. pickChargedAmountDisplay only returns USD amounts; all other currencies render as '—', which blanks the amount column for non-USD tenants.

---

192-218: Fix critical type mismatch in transaction filtering logic.

This issue was flagged in a previous review and remains unresolved. The column returns SourceType values but the toolbar populates the filter dropdown with TransactionType values from TRANSACTION_TYPES. These value sets don't overlap, so filtering will never match and always return empty results.

apps/backend/src/app/api/latest/internal/payments/transactions/transaction-builder.ts (1)

125-146: Net amount is forced to USD "0" for non‑USD charges.

This issue was flagged in a previous review and remains unresolved. If a purchase is denominated solely in a non-USD currency (e.g., EUR), this code emits net_amount: { USD: "0" }, causing downstream reporting to falsely record zero revenue.

This is compounded by the schema constraint in packages/stack-shared/src/interface/crud/transactions.ts (lines 90-92) that only allows USD in net_amount.

apps/backend/src/app/api/latest/internal/payments/transactions/transaction-builder.ts (1)

263-291: Unused parameter in buildItemQuantityChangeTransaction.

The tenancy parameter is accepted but never used in the function body. Consider removing it if it's not needed, or add a comment explaining why it's reserved for future use.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

apps/backend/src/app/api/latest/internal/payments/transactions/transaction-builder.ts (1)

124-145: Net amount is forced to USD "0" for non‑USD charges.

This issue was already identified in a previous review. When a purchase is denominated solely in EUR or another non-USD currency, this code still emits net_amount: { USD: "0" }, falsely recording zero revenue. The net_amount should reflect the actual charged currencies instead of fabricating zero USD values.

apps/backend/src/app/api/latest/internal/payments/transactions/transaction-builder.ts (2)

30-52: Consider validating the fallback structure.

The as ProductSnapshot cast on line 41 bypasses type checking. While the structure appears complete, if ProductSnapshot evolves, this could lead to runtime type mismatches.

Consider using a schema validator or ensuring all fields match the expected type explicitly:

   return {
     display_name: options.displayName,
     customer_type: options.customerType,
     prices: {},
     stackable: false,
     server_only: false,
     included_items: {},
+    client_metadata: null,
+    client_read_only_metadata: null,
+    server_metadata: null,
-  } as ProductSnapshot;
+  };

---

172-260: Consider extracting shared logic from subscription and one-time purchase builders.

buildSubscriptionTransaction and buildOneTimePurchaseTransaction share nearly identical logic (~45 lines of duplication), differing only in which ID field they pass to createProductGrantEntry. Extracting common logic would improve maintainability.

Consider creating a shared helper:

function buildPurchaseTransaction(options: {
  entity: Subscription | OneTimePurchase,
  idField: { subscriptionId?: string } | { oneTimePurchaseId?: string },
}): Transaction {
  const { entity, idField } = options;
  const customerType = typedToLowercase(entity.customerType);
  const product = entity.product as InferType<typeof productSchema> | null;
  const productSnapshot = ensureProductSnapshot(product, customerType);
  const selectedPrice = product ? resolveSelectedPriceFromProduct(product, entity.priceId ?? null) : null;
  const quantity = entity.quantity;
  const chargedAmount = buildChargedAmount(selectedPrice, quantity);
  const testMode = entity.creationSource === "TEST_MODE";

  const entries: TransactionEntry[] = [
    createProductGrantEntry({
      customerType,
      customerId: entity.customerId,
      productId: entity.productId ?? null,
      product: productSnapshot,
      priceId: entity.priceId ?? null,
      quantity,
      ...idField,
    }),
  ];

  const moneyTransfer = createMoneyTransferEntry({
    customerType,
    customerId: entity.customerId,
    chargedAmount,
    skip: testMode,
  });
  if (moneyTransfer) {
    entries.push(moneyTransfer);
  }

  return {
    id: entity.id,
    created_at_millis: entity.createdAt.getTime(),
    effective_at_millis: entity.createdAt.getTime(),
    type: "purchase",
    entries,
    adjusted_by: [],
    test_mode: testMode,
  };
}

export function buildSubscriptionTransaction(options: { subscription: Subscription }): Transaction {
  return buildPurchaseTransaction({
    entity: options.subscription,
    idField: { subscriptionId: options.subscription.id },
  });
}

export function buildOneTimePurchaseTransaction(options: { purchase: OneTimePurchase }): Transaction {
  return buildPurchaseTransaction({
    entity: options.purchase,
    idField: { oneTimePurchaseId: options.purchase.id },
  });
}

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

packages/stack-shared/src/interface/admin-interface.ts (1)

598-611: Method signature correctly updated to new Transaction model.

The method signature, query construction, and return type are all correctly updated to use Transaction and TransactionType. The implementation properly handles optional parameters and builds the query string as needed.

Consider extracting customerType to a type definition similar to TransactionType for consistency:

In packages/stack-shared/src/interface/crud/transactions.ts, add:

export const CUSTOMER_TYPES = ['user', 'team', 'custom'] as const;
export type CustomerType = (typeof CUSTOMER_TYPES)[number];

Then update this method signature:

-async listTransactions(params?: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' }): Promise<{ transactions: Transaction[], nextCursor: string | null }>
+async listTransactions(params?: { cursor?: string, limit?: number, type?: TransactionType, customerType?: CustomerType }): Promise<{ transactions: Transaction[], nextCursor: string | null }>

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

You are on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

apps/dashboard/src/components/data-table/transaction-table.tsx (2)

192-356: Restore functional type filtering
The source_type column still returns SourceType values while the toolbar hands it TransactionType values and the API filter expects TransactionType. As soon as you pick a type, the table accessor never matches, so the UI shows an empty grid even though the backend returns data. We need this column (and all related wiring) to operate directly on transaction.type so the table, toolbar, and API stay in sync.

@@
-    {
-      id: 'source_type',
-      accessorFn: (transaction) => summaryById.get(transaction.id)?.sourceType ?? 'other',
+    {
+      id: 'type',
+      accessorFn: (transaction) => transaction.type,
       header: ({ column }) => <DataTableColumnHeader column={column} columnTitle="Type" />,
       cell: ({ row }) => {
         const summary = summaryById.get(row.original.id);
@@
-    const newFilters: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' } = {
+    const newFilters: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' } = {
       cursor: options.cursor,
       limit: options.limit,
-      type: options.columnFilters.find(f => f.id === 'source_type')?.value as any,
+      type: options.columnFilters.find(f => f.id === 'type')?.value as any,
       customerType: options.columnFilters.find(f => f.id === 'customer')?.value as any,
     };
@@
       defaultVisibility={{
-        source_type: true,
+        type: true,
         customer: true,
         amount: true,
         detail: true,
         created_at_millis: true,
       }}
       defaultColumnFilters={[
-        { id: 'source_type', value: undefined },
+        { id: 'type', value: undefined },
         { id: 'customer', value: undefined },
       ]}
@@
-      toolbarRender={(table) => {
-        const selectedType = table.getColumn('source_type')?.getFilterValue() as TransactionType | undefined;
+      toolbarRender={(table) => {
+        const typeColumn = table.getColumn('type');
+        const selectedType = typeColumn?.getFilterValue() as TransactionType | undefined;
@@
-            <Select
-              value={selectedType ?? ''}
-              onValueChange={(v) => table.getColumn('source_type')?.setFilterValue(v === '__clear' ? undefined : v)}
+            <Select
+              value={selectedType ?? ''}
+              onValueChange={(v) => typeColumn?.setFilterValue(v === '__clear' ? undefined : v)}
             >

---

131-139: Show real amounts for every currency
pickChargedAmountDisplay still hardcodes USD, so non-USD tenants see "Non USD amount" and USD entries with undefined amounts render as "$undefined". Please surface whichever currency actually has a value and fall back to '—' only when none do.

 function pickChargedAmountDisplay(entry: MoneyTransferEntry | undefined): string {
   if (!entry) return '—';
   const chargedAmount = entry.charged_amount as Record<string, string | undefined>;
-  if ("USD" in chargedAmount) {
-    return `$${chargedAmount.USD}`;
-  }
-  // TODO: Handle other currencies
-  return 'Non USD amount';
+  const [currency, amount] =
+    Object.entries(chargedAmount).find(([, value]) => typeof value === 'string' && value.length > 0) ?? [];
+  if (!currency || !amount) {
+    return '—';
+  }
+  return currency === 'USD' ? `$${amount}` : `${currency} ${amount}`;
 }

apps/e2e/tests/backend/endpoints/api/v1/internal/transactions.test.ts (3)

5-8: Consider stronger typing for payment configuration.

Using Record<string, any> for extraProducts and extraItems loses type safety and could hide configuration errors.

Consider defining explicit types that match the product and item schemas used in the actual payment configuration, or at minimum use Record<string, unknown> to force type narrowing at usage sites.

---

13-37: Consider extracting base payment configurations to module-level constants.

The baseProducts and baseItems are defined inline, which could lead to duplication if these configurations are needed in other test files or helper functions.

Extract these to module-level constants at the top of the file:

+const BASE_PRODUCTS = {
+  "sub-product": {
+    displayName: "Sub Product",
+    customerType: "user",
+    serverOnly: false,
+    stackable: false,
+    prices: {
+      monthly: { USD: "1000", interval: [1, "month"] },
+    },
+    includedItems: {},
+  },
+  "otp-product": {
+    displayName: "One-Time Product",
+    customerType: "user",
+    serverOnly: false,
+    stackable: false,
+    prices: {
+      single: { USD: "5000" },
+    },
+    includedItems: {},
+  },
+};
+
+const BASE_ITEMS = {
+  credits: { displayName: "Credits", customerType: "user" },
+};
+
 async function setupProjectWithPaymentsConfig(options: PaymentsConfigOptions = {}) {
   await Project.createAndSwitch();
   await PaymentsHelper.setup();
-  const baseProducts = {
-    "sub-product": { ... },
-    "otp-product": { ... },
-  };
-  const baseItems = {
-    credits: { displayName: "Credits", customerType: "user" },
-  };
   await Project.updateConfig({
     payments: {
       testMode: true,
       products: {
-        ...baseProducts,
+        ...BASE_PRODUCTS,
         ...(options.extraProducts ?? {}),
       },
       items: {
-        ...baseItems,
+        ...BASE_ITEMS,
         ...(options.extraItems ?? {}),
       },
     },
   });
 }

---

332-395: LGTM with optional readability improvement.

Excellent test coverage for customer_type filtering across multiple sources (purchases and item changes).

The nested every() assertions on lines 384-386 and 394 could be more readable:

- expect(teamResponse.body.transactions.every((tx: any) =>
-   tx.entries.every((entry: any) => entry.customer_type === "team")
- )).toBe(true);
+ const allTeamEntries = teamResponse.body.transactions
+   .flatMap((tx: any) => tx.entries)
+   .every((entry: any) => entry.customer_type === "team");
+ expect(allTeamEntries).toBe(true);

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

packages/stack-shared/src/interface/crud/transactions.ts (1)

26-28: USD-only net_amount constraint already flagged.

The restriction of net_amount to USD while charged_amount supports multiple currencies has already been identified in a previous review as causing data integrity issues.

apps/dashboard/src/components/data-table/transaction-table.tsx (2)

236-252: Fix type column/filter to use transaction.type instead of derived sourceType.

The “Type” column currently has id: 'source_type' and its accessor returns the derived SourceType ('subscription' | 'one_time' | 'item_quantity_change' | 'other'), while:

• The toolbar dropdown is populated from TRANSACTION_TYPES ('purchase', 'subscription-renewal', etc.), and
• onUpdate forwards options.columnFilters.find(f => f.id === 'source_type')?.value as the backend type filter, which expects a TransactionType.

These value sets don’t overlap, so when a user picks a type filter:

• The backend gets a correct TransactionType (e.g. "purchase"), but
• TanStack’s client‑side filter for the source_type column compares "purchase" against values like "subscription"/"one_time", which never match, causing the table to show no rows.

To align everything and let the filter work end‑to‑end:

• Change the column id from 'source_type' to 'type'.
• Set its accessor to transaction.type for filtering/sorting.
• Keep using summary.displayType only for icon/label rendering.
• Update onUpdate, defaultVisibility, defaultColumnFilters, and toolbar to reference 'type' instead of 'source_type'.

Roughly:

-  {
-    id: 'source_type',
-    accessorFn: (transaction) => summaryById.get(transaction.id)?.sourceType ?? 'other',
+  {
+    id: 'type',
+    accessorFn: (transaction) => transaction.type,
     header: ({ column }) => <DataTableColumnHeader column={column} columnTitle="Type" />,
     cell: ({ row }) => {
       const summary = summaryById.get(row.original.id);
       const displayType = summary?.displayType;
       if (!displayType) {
         return <TextCell size={20}>—</TextCell>;
       }
       const { Icon, label } = displayType;
       return (
         <TextCell size={20}>
           <Tooltip>
             <TooltipTrigger asChild>
               <span className="flex h-6 w-6 items-center justify-center rounded-md bg-muted">
                 <Icon className="h-4 w-4" aria-hidden />
               </span>
             </TooltipTrigger>
             <TooltipContent side="left">{label}</TooltipContent>
           </Tooltip>
         </TextCell>
       );
     },
   },

- const newFilters: { cursor?: string, limit?: number, type?: TransactionType, customerType?: ... } = {
-   cursor: options.cursor,
-   limit: options.limit,
-   type: options.columnFilters.find(f => f.id === 'source_type')?.value as any,
-   customerType: options.columnFilters.find(f => f.id === 'customer')?.value as any,
- };
+ const newFilters: { cursor?: string, limit?: number, type?: TransactionType, customerType?: ... } = {
+   cursor: options.cursor,
+   limit: options.limit,
+   type: options.columnFilters.find(f => f.id === 'type')?.value as any,
+   customerType: options.columnFilters.find(f => f.id === 'customer')?.value as any,
+ };

and similarly update defaultVisibility, defaultColumnFilters, and the toolbar to call table.getColumn('type').

Also applies to: 252-353, 355-375, 378-441

---

142-150: Make pickChargedAmountDisplay multi‑currency aware and robust to undefined USD amounts.

pickChargedAmountDisplay still has two issues:

• It only checks for the presence of the "USD" key and will render "$undefined" if that key exists but its value is missing/undefined.
• For all non‑USD charges, it returns the literal string "Non USD amount" instead of the actual amount and currency, so tenants priced solely in EUR/GBP/JPY/etc. can’t see real values.

Given that money_transfer entries already carry a multi‑currency charged_amount map, this should pick any defined amount and label it, falling back to '—' only when no valid values exist.

For example:

function pickChargedAmountDisplay(entry: MoneyTransferEntry | undefined): string {
  if (!entry) return '—';
  const chargedAmount = entry.charged_amount as Record<string, string | undefined>;
-  if ("USD" in chargedAmount) {
-    return `$${chargedAmount.USD}`;
-  }
-  // TODO: Handle other currencies
-  return 'Non USD amount';
+  const [currency, amount] =
+    Object.entries(chargedAmount).find(([, value]) => typeof value === 'string' && value.length > 0) ?? [];
+  if (!currency || !amount) {
+    return '—';
+  }
+  if (currency === 'USD') {
+    return `$${amount}`;
+  }
+  return `${currency} ${amount}`;
}

This avoids $undefined, correctly surfaces non‑USD values, and will stay compatible as you add more currencies.

Also applies to: 172-189, 303-310

apps/backend/src/app/api/latest/internal/payments/transactions/transaction-builder.ts (2)

42-56: Fix decimal handling in multiplyMoneyAmount (currently overstates amounts for extra fractional digits).

The multiplyMoneyAmount helper currently pads the fractional part twice but never truncates it to currency.decimals:

const [wholePart, fractionalPart = ""] = normalized.split(".");
const paddedFractional = fractionalPart.padEnd(currency.decimals, "0");
const smallestUnit = BigInt(`${wholePart || "0"}${paddedFractional.padEnd(currency.decimals, "0")}`);

For a 2‑decimal currency and an input like "1.234", this builds "1234" as the smallest unit, which later converts back to "12.34" instead of something like "1.23"/"1.24". That’s a 10× overstatement of the amount.

You probably want to clamp the fractional part to currency.decimals digits, then right‑pad with zeros if it’s too short, e.g.:

- const [wholePart, fractionalPart = ""] = normalized.split(".");
- const paddedFractional = fractionalPart.padEnd(currency.decimals, "0");
- const smallestUnit = BigInt(`${wholePart || "0"}${paddedFractional.padEnd(currency.decimals, "0")}`);
+ const [wholePartRaw, fractionalRaw = ""] = normalized.split(".");
+ const wholePart = wholePartRaw || "0";
+ const fractionalNormalized =
+   currency.decimals === 0
+     ? ""
+     : fractionalRaw.slice(0, currency.decimals).padEnd(currency.decimals, "0");
+ const smallestUnit = BigInt(`${wholePart}${fractionalNormalized}`);

The rest of the function (multiplying by an integer quantity and re‑inserting the decimal point) can stay as is; this change ensures any extra fractional digits are not misinterpreted as extra whole digits.

Also applies to: 58-75, 77-85

---

88-99: Make net_amount truthful for non‑USD charges instead of forcing { USD: "0" }.

Both createMoneyTransferEntry and buildSubscriptionRenewalTransaction currently construct net_amount as USD only, defaulting to "0" or potentially undefined when there is no USD component:

const netUsd = options.chargedAmount.USD ?? "0";
...
net_amount: { USD: netUsd },

and

net_amount: { USD: chargedAmount.USD },

This causes:

• Purely non‑USD charges (e.g. { EUR: "5000" }) to be recorded as having net_amount: { USD: "0" }, effectively zeroing out revenue for those transactions.
• Potentially USD: undefined being serialized for renewals when only non‑USD currencies are present.

Since charged_amount is already a per‑currency map, net_amount should mirror real financial impact rather than fabricating a zero USD value. A simple fix is:

• Filter charged_amount down to actual defined string values.
• Use USD when present; otherwise use the original charged currencies as net_amount.

For example in createMoneyTransferEntry:

- const chargedCurrencies = Object.keys(options.chargedAmount);
- if (chargedCurrencies.length === 0) return null;
- const netUsd = options.chargedAmount.USD ?? "0";
+ const chargedEntries = Object.entries(options.chargedAmount)
+   .filter(([, amount]) => typeof amount === "string") as Array<[string, string]>;
+ if (chargedEntries.length === 0) return null;
+ const chargedAmount = Object.fromEntries(chargedEntries) as Record<string, string>;
+ const netAmount = chargedAmount.USD !== undefined ? { USD: chargedAmount.USD } : chargedAmount;
  return {
    type: "money_transfer",
    adjusted_transaction_id: null,
    adjusted_entry_index: null,
    customer_type: options.customerType,
    customer_id: options.customerId,
-   charged_amount: options.chargedAmount,
-   net_amount: { USD: netUsd },
+   charged_amount: chargedAmount,
+   net_amount: netAmount,
  };

and in buildSubscriptionRenewalTransaction:

- net_amount: { USD: chargedAmount.USD },
+ net_amount: chargedAmount.USD !== undefined
+   ? { USD: chargedAmount.USD }
+   : { ...chargedAmount },

This keeps net_amount consistent and non‑misleading for tenants billing in non‑USD currencies.

Also applies to: 101-122, 292-322

apps/backend/src/app/api/latest/internal/payments/transactions/route.tsx (1)

94-101: Advance per‑source cursors based on merged (not just page) to keep pagination correct under filtering and avoid repeated scans

Right now lastSubId/lastIqcId/lastOtpId/lastSiId are derived only from page (the filtered slice). If a source’s rows are filtered out by query.type, its cursor never advances, so that table is repeatedly scanned from the beginning on subsequent pages. Today each table maps to a single transaction type, so results stay correct but you still over‑fetch and create a fragile coupling between “one table = one type”. If any table ever emits multiple transaction types, this will starve later matching rows and break paginated type views.

You can fix both correctness (future‑proof) and efficiency by advancing cursors based on all merged records up to the last item actually returned in the page, as in the earlier bot suggestion:

-    const page = filtered.slice(0, limit);
-    let lastSubId = "";
-    let lastIqcId = "";
-    let lastOtpId = "";
-    let lastSiId = "";
-    for (const r of page) {
-      if (r.source === "subscription") lastSubId = r.id;
-      if (r.source === "item_quantity_change") lastIqcId = r.id;
-      if (r.source === "one_time") lastOtpId = r.id;
-      if (r.source === "subscription-invoice") lastSiId = r.id;
-    }
+    const page = filtered.slice(0, limit);
+    let lastSubId = "";
+    let lastIqcId = "";
+    let lastOtpId = "";
+    let lastSiId = "";
+
+    if (page.length === limit) {
+      // Find the position of the last item in the page within the merged results
+      const lastPageItem = page[page.length - 1];
+      const lastPageIndex = merged.findIndex((item) =>
+        item.source === lastPageItem.source &&
+        item.id === lastPageItem.id
+      );
+
+      // Advance cursors for all sources based on records processed up to this point
+      for (let i = 0; i <= lastPageIndex; i++) {
+        const r = merged[i];
+        if (r.source === "subscription") lastSubId = r.id;
+        if (r.source === "item_quantity_change") lastIqcId = r.id;
+        if (r.source === "one_time") lastOtpId = r.id;
+        if (r.source === "subscription-invoice") lastSiId = r.id;
+      }
+    }

This keeps concatenated‑cursor pagination consistent even when a filter drops some merged rows, and avoids endlessly re‑reading already‑processed records from non‑selected sources.

Also applies to: 112-201

packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts (1)

607-616: Restore safe default for params in listTransactions / useTransactions

Both methods now require a params object, so adminApp.listTransactions() or adminApp.useTransactions() with no args will throw at runtime when accessing params.*. The previous API allowed no‑arg calls; this is a breaking ergonomics change and was already flagged in a prior review.

You can fix this by defaulting params = {} and destructuring before using the cache:

-  async listTransactions(params: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' }): Promise<{ transactions: Transaction[], nextCursor: string | null }> {
-    const crud = Result.orThrow(await this._transactionsCache.getOrWait([params.cursor, params.limit, params.type, params.customerType] as const, "write-only"));
+  async listTransactions(params: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' } = {}): Promise<{ transactions: Transaction[], nextCursor: string | null }> {
+    const { cursor, limit, type, customerType } = params;
+    const crud = Result.orThrow(await this._transactionsCache.getOrWait([cursor, limit, type, customerType] as const, "write-only"));
     return crud;
   }
@@
-  useTransactions(params: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' }): { transactions: Transaction[], nextCursor: string | null } {
-    const data = useAsyncCache(this._transactionsCache, [params.cursor, params.limit, params.type, params.customerType] as const, "adminApp.useTransactions()");
+  useTransactions(params: { cursor?: string, limit?: number, type?: TransactionType, customerType?: 'user' | 'team' | 'custom' } = {}): { transactions: Transaction[], nextCursor: string | null } {
+    const { cursor, limit, type, customerType } = params;
+    const data = useAsyncCache(this._transactionsCache, [cursor, limit, type, customerType] as const, "adminApp.useTransactions()");
     return data;
   }

apps/e2e/tests/backend/endpoints/api/v1/internal/transactions-refund.test.ts (1)

6-79: E2E coverage for refund flows is solid; consider a couple of small robustness tweaks.

The helpers and three scenarios here (test‑mode one‑time purchase, missing subscription ID, and non‑test one‑time purchase via Stripe webhook including double‑refund protection and post‑refund product state) give very good end‑to‑end coverage of the new refund route and transaction model.

A couple of small, optional hardening ideas:

• In the “refunds non‑test mode one-time purchases” test, you already snapshot transactionsRes.body, but also asserting transactionsRes.status === 200 (and similarly for transactionsAfterRefund) would make failures easier to diagnose if the endpoint ever starts returning a KnownError instead of a 2xx.
• createTestModeTransaction currently picks the first transaction from /transactions; if you ever add more background transactions in this project, you might want to filter by type === "purchase" to ensure you grab the correct one.

Overall though, this file looks good.

Also applies to: 80-109, 112-135, 137-290

apps/backend/prisma/schema.prisma (1)

772-799: Schema changes line up with code; consider enforcing the “one creation invoice per subscription” invariant in the DB.

The added refundedAt fields and the new SubscriptionInvoice model align with how the refund route and handleStripeInvoicePaid use them (linking invoices to subscriptions via (tenancyId, stripeSubscriptionId) and upserting by (tenancyId, stripeInvoiceId)).

Right now, the “there must be at most one creation invoice per subscription” rule is enforced only in application code (findMany + if (length > 1) throw StackAssertionError). If you want stronger protection against data drift or concurrent writers, you could add a unique index such as:

model SubscriptionInvoice {
  // existing fields...

  @@id([tenancyId, id])
  @@unique([tenancyId, stripeInvoiceId])
  @@unique([tenancyId, stripeSubscriptionId, isSubscriptionCreationInvoice])
}

This would ensure duplicates for isSubscriptionCreationInvoice = true can’t be inserted even outside the main code path.

Also applies to: 815-831, 859-873

apps/backend/src/lib/stripe.tsx (1)

50-60: Invoice line parsing is valid per Stripe v18.3.0; Stripe client scope works but relies on caller invariant.

The concerns raised have nuanced validity:

1. Invoice line subscription extraction: Stripe SDK v18.3.0 does expose parent.subscription_item_details.subscription on invoice line items, so the parsing at lines 125–127 is correct. No issue here.

2. Stripe client scope: The current implementation works correctly because the webhook handler creates an account-scoped client with getStripeForAccount({ accountId }, mockData) and then passes the same accountId to both syncStripeSubscriptions and handleStripeInvoicePaid. Inside getTenancyFromStripeAccountIdOrThrow, calling stripe.accounts.retrieve(stripeAccountId) succeeds because the account-scoped client's stripeAccount config matches the stripeAccountId parameter.

However, this pattern is fragile: it silently depends on callers always passing a client and stripeAccountId that match. If a refactoring mixes a platform client with a specific stripeAccountId (or vice versa), the calls would fail subtly. To harden this:

• Document the expected invariant: all three functions assume the stripe client's account scope (if any) matches the provided stripeAccountId.
• Consider adding a runtime check in getTenancyFromStripeAccountIdOrThrow or an assertion that the client and accountId are compatible.
• Add integration tests using the mock that verify a real webhook event produces the expected invoiceSubscriptionIds array (currently no tests found).

apps/backend/src/app/api/latest/internal/payments/transactions/route.tsx (1)

101-103: Verify Prisma relation filter for subscriptionInvoice + customer_type

customerTypeFilter is { customerType: ... }, which is passed directly as subscription: customerTypeFilter in the subscriptionInvoice.findMany where clause. For typical Prisma schemas, a relation field uses a RelationFilter (e.g. { is: { customerType: ... } } for 1‑1), so subscription: customerTypeFilter may either be a type error or throw a runtime validation error.

Please double‑check the generated SubscriptionInvoiceWhereInput:

• If subscription is a relation filter, this likely needs to be:

where: {
  tenancyId: auth.tenancy.id,
  ...(siWhere ?? {}),
  ...(query.customer_type
    ? { subscription: { is: customerTypeFilter } }
    : {}),
  isSubscriptionCreationInvoice: false,
},

• If your Prisma model truly exposes subscription as an embedded where‑input, then this is fine but is non‑standard and worth a comment.

Also applies to: 133-139

apps/e2e/tests/backend/endpoints/api/v1/internal/transactions.test.ts (1)

75-90: Avoid duplicating sendStripeWebhook logic already available in backend helpers

This local sendStripeWebhook mirrors the implementation in backend-helpers.ts, differing mainly in how the secret is sourced. To reduce duplication and keep Stripe-signature logic single-sourced, consider delegating to the shared helper instead:

// backend-helpers.ts already exposes:
export async function sendStripeWebhook(payload: unknown, options?: { secret?: string; ... })

// here:
import { ..., sendStripeWebhook as sendStripeWebhookHelper } from "../../../../backend-helpers";

const stripeWebhookSecret = process.env.STACK_STRIPE_WEBHOOK_SECRET ?? "mock_stripe_webhook_secret";

async function sendStripeWebhook(payload: unknown) {
  return await sendStripeWebhookHelper(payload, { secret: stripeWebhookSecret });
}

This keeps tests aligned if the signing logic changes in one place.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: N2D4
Repo: stack-auth/stack-auth PR: 943
File: examples/convex/app/action/page.tsx:23-28
Timestamp: 2025-10-11T04:13:19.308Z
Learning: In the stack-auth codebase, use `runAsynchronouslyWithAlert` from `stackframe/stack-shared/dist/utils/promises` for async button click handlers and form submissions instead of manual try/catch blocks. This utility automatically handles errors and shows alerts to users.