apps/backend/prisma/migrations/20250820164831_custom_customer_types/migration.sql (1)

1-16: Adding NOT NULL column without default can fail on non-empty tables.

This will error if ItemQuantityChange has rows. Use a two-step migration: add as nullable, backfill, then set NOT NULL. Also ensure backfill uses the correct customerType derived from your data.

Here’s a safe pattern to adapt:

 -- AlterEnum
 ALTER TYPE "CustomerType" ADD VALUE 'CUSTOM';

--- AlterTable
-ALTER TABLE "ItemQuantityChange" ADD COLUMN     "customerType" "CustomerType" NOT NULL,
-ALTER COLUMN "customerId" SET DATA TYPE TEXT;
+-- AlterTable (step 1: add nullable)
+ALTER TABLE "ItemQuantityChange" 
+  ADD COLUMN "customerType" "CustomerType",
+  ALTER COLUMN "customerId" SET DATA TYPE TEXT;
+
+-- Backfill (step 2: set proper values; adjust logic to your data model)
+-- Example placeholder (set all to USER if that's guaranteed safe; otherwise join against items config)
+-- UPDATE "ItemQuantityChange" ic SET "customerType" = 'USER' WHERE "customerType" IS NULL;
+
+-- AlterTable (step 3: enforce NOT NULL)
+ALTER TABLE "ItemQuantityChange" 
+  ALTER COLUMN "customerType" SET NOT NULL;

 -- AlterTable
 ALTER TABLE "Subscription" ALTER COLUMN "customerId" SET DATA TYPE TEXT;

If the table is guaranteed empty in all environments, keeping NOT NULL in a single step is fine; otherwise, prefer the two-step approach.

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

1779-1801: Use stringifyJson per code patterns (JSON.stringify is disallowed here)

This file adheres to a rule to use stringifyJson from stack-shared/utils/json. The changed line still uses JSON.stringify.

Apply within the changed range:

-        body: JSON.stringify({ customer_type, customer_id, ...offerBody }),
+        body: stringifyJson({ customer_type, customer_id, ...offerBody }),

And add the import (outside the changed hunk):

// at the top alongside ReadonlyJson
import { ReadonlyJson, stringifyJson } from '../utils/json';

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

862-867: Encode path segments (customerType/customerId/itemId) to avoid malformed URLs and potential routing issues.

The template literal inserts unencoded values into the path. If any identifier contains reserved characters (e.g., spaces, slashes, unicode), requests can break or misroute. Encode each segment or use the project’s urlString util consistently.

-      `/payments/items/${customerType}/${customerId}/${itemId}/update-quantity?${queryParams.toString()}`,
+      `/payments/items/${encodeURIComponent(customerType)}/${encodeURIComponent(customerId)}/${encodeURIComponent(itemId)}/update-quantity?${queryParams.toString()}`,

Alternatively (for consistency with the rest of this file), you can switch to urlString for the path and append the query string:

const path = urlString`/payments/items/${customerType}/${customerId}/${itemId}/update-quantity` + `?${queryParams.toString()}`;
await this.sendServerRequest(path, { /* ... */ }, null);

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

511-518: Remove any-cast; narrow the discriminated union safely.

The current approach uses (options as any).customId. Prefer standard discriminated narrowing to retain type safety.

-  async createItemQuantityChange(options: (
-    { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-    { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-    { customId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
-  )): Promise<void> {
+  async createItemQuantityChange(options: (
+    { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
+    { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
+    { customId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
+  )): Promise<void> {
     await this._interface.updateItemQuantity(
-      { itemId: options.itemId, ...("userId" in options ? { userId: options.userId } : ("teamId" in options ? { teamId: options.teamId } : { customId: (options as any).customId })) },
+      {
+        itemId: options.itemId,
+        ...("userId" in options
+          ? { userId: options.userId }
+          : ("teamId" in options
+            ? { teamId: options.teamId }
+            : { customId: options.customId }))
+      },
       {
         delta: options.quantity,
         expires_at: options.expiresAt,
         description: options.description,
       }
     );
   }

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

22-22: Confirm unrelated change to ownerTeamId.

Line 22 is marked as modified, but it’s effectively the same declaration. If this was accidental churn (e.g., whitespace/formatting), consider dropping it to reduce noise. If intentional, ignore.

---

753-765: Consider indexing customerType for query efficiency.

Likely hot paths filter by tenancyId + customerType + customerId + itemId (+ expiresAt). Current index omits customerType and itemId, which can degrade performance with the new dimension.

Apply this diff to add a composite index:

 model ItemQuantityChange {
   id           String       @default(uuid()) @db.Uuid
   tenancyId    String       @db.Uuid
   customerType CustomerType
   customerId   String
   itemId       String
   quantity     Int
   description  String?
   expiresAt    DateTime?
   createdAt    DateTime     @default(now())

   @@id([tenancyId, id])
-  @@index([tenancyId, customerId, expiresAt])
+  @@index([tenancyId, customerId, expiresAt])
+  @@index([tenancyId, customerType, customerId, itemId, expiresAt])
 }

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

58-101: Customer-type aware quantity calculation looks correct; add DB indexes to keep queries fast

The switch to filtering by customerType (uppercased) in both Subscription and ItemQuantityChange is correct and consistent with the new enum. To prevent regressions at scale, add composite indexes aligned with these where-clauses.

Suggested indexes (pseudo-sql/Prisma):

• Subscription: (tenancyId, customerType, customerId, status)
• ItemQuantityChange: (tenancyId, customerType, customerId, itemId, expiresAt)

These match the high-selectivity filters used by getItemQuantityForCustomer.

apps/e2e/tests/backend/endpoints/api/v1/payments/purchase-session.test.ts (1)

94-113: Optionally add coverage for mismatched customer_type vs inline_offer.customer_type

A negative test asserting OfferCustomerTypeDoesNotMatch would harden the contract.

If helpful, I can draft an additional test case that sends a mismatched pair and expects the known error response.

packages/template/src/lib/stack-app/apps/interfaces/server-app.ts (1)

58-63: Deduplicate the “item key” union across client/server

The exact union type for item keys is duplicated here and in the client interface. Consider extracting a shared alias (e.g., ItemKey = { itemId: string } & ({ userId: string } | { teamId: string } | { customId: string })) in customers/index.ts and importing it in both places to avoid drift.

Example:

// packages/template/src/lib/stack-app/customers/index.ts
export type ItemKey =
  | { itemId: string, userId: string }
  | { itemId: string, teamId: string }
  | { itemId: string, customId: string };

Then here:

-  & AsyncStoreProperty<
-    "item",
-    [{ itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }],
-    ServerItem,
-    false
-  >
+  & AsyncStoreProperty<"item", [ItemKey], ServerItem, false>

apps/e2e/tests/backend/endpoints/api/v1/payments/create-purchase-url.test.ts (2)

232-238: Avoid snapshotting dynamic purchase URL — reduce flakiness

Inline snapshot asserts the full URL including a generated token. Even with "", the remaining random suffix may change. Prefer asserting status + URL shape (you already do with the regex below) and skip the full inline snapshot.

Replace the snapshot with a direct status assertion:

-  expect(response).toMatchInlineSnapshot(`
-    NiceResponse {
-      "status": 200,
-      "body": { "url": "http://localhost:8101/purchase/<stripped UUID>_cngg259jnn72d55dxfzmafzan54vcw7n429evq7bfbaa0" },
-      "headers": Headers { <some fields may have been hidden> },
-    }
-  `);
+  expect(response.status).toBe(200);

---

171-201: Nit: duplicate customer_type in nested offer_inline

You’re specifying customer_type at both the top-level request and inside offer_inline. If the route requires both, ignore this. Otherwise consider relying on a single source of truth to avoid divergence in future edits.

If only one is required, consider removing the redundant one in the client-path negative test to simplify payload.

Also applies to: 211-231

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/page-client.tsx (1)

171-171: DRY up duplicated customer type literals

The allowed values and select options are repeated for offers and items. Consider centralizing:

• A shared union literal array (e.g., const customerTypeOptions = [{ value: "user", ...}, ...]) and reuse in both forms.
• A shared yup schema (if not already in stack-shared) imported here to avoid drift.

Example:

const customerTypeOptions = [
  { value: "user", label: "User" },
  { value: "team", label: "Team" },
  { value: "custom", label: "Custom" },
];

// In both schemas:
yup.string().oneOf(customerTypeOptions.map(o => o.value as const)).defined().label("Customer Type");

Also applies to: 233-239

packages/template/src/lib/stack-app/apps/interfaces/client-app.ts (1)

80-85: Avoid duplicating the item key union across client/server

Same suggestion as server interface: extract a shared ItemKey type to customers/index.ts and reuse here for consistency and easier evolution.

-  & AsyncStoreProperty<
-    "item",
-    [{ itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }],
-    Item,
-    false
-  >
+  & AsyncStoreProperty<"item", [ItemKey], Item, false>

apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts (1)

165-172: Reduce URL construction duplication with small helpers

The file repeats building item paths and querystrings. Consider tiny helpers to reduce duplication and make future route-shape changes safer.

Example at top of file:

function itemUrl(scope: "user" | "team" | "custom", id: string, itemId: string) {
  return `/api/latest/payments/items/${scope}/${id}/${itemId}`;
}
function updateQuantityUrl(scope: "user" | "team" | "custom", id: string, itemId: string, allowNegative: boolean) {
  return `${itemUrl(scope, id, itemId)}/update-quantity?allow_negative=${allowNegative ? "true" : "false"}`;
}

Then:

await niceBackendFetch(updateQuantityUrl("user", user.userId, "test-item", false), { ... })

Also applies to: 194-199, 224-229, 255-261, 424-428

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

79-83: Type union looks good; consider DRYing shared fields for maintainability.

Options share the same item fields; extracting a base type reduces duplication and helps future changes (e.g., adding a new optional field once).

Apply this minimal change inside the existing union (optional), or introduce shared types at file scope:

-    createItemQuantityChange(options: (
-      { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-      { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-      { customId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
-    )): Promise<void>,
+    createItemQuantityChange(options: (
+      ({ userId: string } | { teamId: string } | { customId: string })
+      & { itemId: string, quantity: number, expiresAt?: string, description?: string }
+    )): Promise<void>,

If you prefer explicit names, add these near the top of the file and then reference them:

type ItemQuantityChangeCore = { itemId: string; quantity: number; expiresAt?: string; description?: string };
type ItemOwner = { userId: string } | { teamId: string } | { customId: string };
type CreateItemQuantityChangeOptions = ItemOwner & ItemQuantityChangeCore;
// ...
// createItemQuantityChange(options: CreateItemQuantityChangeOptions): Promise<void>

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

845-846: Remove redundant type annotation; rely on inference.

Minor cleanup: the explicit type on itemId is redundant.

-    const itemId: string = options.itemId;
+    const { itemId } = options;

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

1206-1217: Deduplicate getItem branch logic.

This can be simplified while keeping behavior intact.

-  async getItem(options: { itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }): Promise<Item> {
-    const session = await this._getSession();
-    let crud: ItemCrud['Client']['Read'];
-    if ("userId" in options) {
-      crud = Result.orThrow(await this._userItemCache.getOrWait([session, options.userId, options.itemId], "write-only"));
-    } else if ("teamId" in options) {
-      crud = Result.orThrow(await this._teamItemCache.getOrWait([session, options.teamId, options.itemId], "write-only"));
-    } else {
-      crud = Result.orThrow(await this._customItemCache.getOrWait([session, options.customId, options.itemId], "write-only"));
-    }
-    return this._clientItemFromCrud(crud);
-  }
+  async getItem(options: { itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }): Promise<Item> {
+    const session = await this._getSession();
+    const [cache, ownerId] =
+      "userId" in options ? [this._userItemCache, options.userId] :
+      "teamId" in options ? [this._teamItemCache, options.teamId] :
+                            [this._customItemCache, options.customId];
+    const crud = Result.orThrow(await cache.getOrWait([session, ownerId, options.itemId] as const, "write-only"));
+    return this._clientItemFromCrud(crud);
+  }

apps/e2e/tests/js/payments.test.ts (1)

192-192: Strengthen assertion: expect the specific KnownError.

Asserting the precise error type improves signal and avoids false positives.

-  await expect(adminApp.createItemQuantityChange({ teamId: team.id, itemId, quantity: -1 }))
-    .rejects.toThrow();
+  await expect(
+    adminApp.createItemQuantityChange({ teamId: team.id, itemId, quantity: -1 })
+  ).rejects.toThrow(KnownErrors.ItemQuantityInsufficientAmount);

Add this import at the top of the file:

import { KnownErrors } from "@stackframe/stack-shared";

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts (1)

20-23: Prefer shared schema: use customerTypeSchema for a single source of truth.

Inline oneOf duplicates definitions across the codebase. Importing the shared schema keeps enum values consistent with future changes.

-      customer_type: yupString().oneOf(["user", "team", "custom"]).defined(),
+      customer_type: customerTypeSchema.defined(),

Add to the existing schema-fields import:

import { adaptSchema, clientOrHigherAuthTypeSchema, yupNumber, yupObject, yupString, customerTypeSchema } from "@stackframe/stack-shared/dist/schema-fields";

apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)

22-24: Add light schema validation for customer_id

Although we escape single quotes when constructing the Stripe query, constraining customer_id at the schema level helps guard against malformed or malicious inputs and avoids query errors.

• File: apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Lines: 22–24

Suggested diff:

   customer_type: yupString().oneOf(["user", "team", "custom"]).defined(),
-  customer_id: yupString().defined(),
+  customer_id: yupString()
+    .matches(/^[A-Za-z0-9_-]+$/, "customer_id may only contain letters, numbers, hyphens, and underscores")
+    .defined(),
   offer_id: yupString().optional(),

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (1)

69-74: Validate expires_at as an ISO date to avoid Invalid Date writes.

new Date(req.body.expires_at) will produce Invalid Date for malformed input, which can bubble into runtime/DB errors. Prefer explicit date validation.

-      expires_at: yupString().optional(),
+      // If ISO 8601 is expected, enforce it at the edge
+      expires_at: yupString().matches(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/,
+        "expires_at must be an ISO 8601 UTC timestamp"
+      ).optional(),

Alternatively, use a yup date schema if available and acceptable across the codebase.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: CR
PR: stack-auth/stack-auth#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-04T22:25:51.260Z
Learning: Applies to apps/backend/prisma/schema.prisma : Database models use Prisma

apps/e2e/tests/backend/endpoints/api/v1/payments/create-purchase-url.test.ts (1)

5-27: Consider adding at least one positive/negative case for customer_type: "custom".

Since this PR adds "custom" support across the stack, adding a basic acceptance test here (valid customId path + mismatch/error path) would tighten coverage for the purchases endpoint too.

I can draft two focused tests: one success with offer_id configured for "custom", and one mismatch returning OFFER_CUSTOMER_TYPE_DOES_NOT_MATCH. Want me to add them?

Also applies to: 29-78, 134-173, 176-206, 208-239, 241-278

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

103-140: ensureCustomerExists: use UserIdDoesNotExist for users and guard “custom” IDs

For consistency and better DX:

• UserNotFound’s constructor takes zero arguments, so don’t pass customerId to it. If you want the ID in the error, swap to
  throw new KnownErrors.UserIdDoesNotExist(options.customerId)
• Add an explicit guard for empty IDs when customerType === "custom"

Changes:

• In apps/backend/src/lib/payments.tsx

@@ export async function ensureCustomerExists(options: {
   if (options.customerType === "user") {
     if (!isUuid(options.customerId)) {
-      throw new KnownErrors.UserNotFound();
+      throw new KnownErrors.UserIdDoesNotExist(options.customerId);
     }
     const user = await options.prisma.projectUser.findUnique({
@@
     if (!user) {
-      throw new KnownErrors.UserNotFound();
+      throw new KnownErrors.UserIdDoesNotExist(options.customerId);
     }
   } else if (options.customerType === "team") {
@@
-  }
+  } else if (options.customerType === "custom") {
+    if (options.customerId.trim().length === 0) {
+      // Keep error shape consistent with other 4xx validation paths
+      throw new StatusError(400, "customer_id must be non-empty for custom customers");
+    }
+  }

• Add import at top if not already present:

import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";

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

147-151: Updated error handling matches new backend semantics.

Switching to UserNotFound/TeamNotFound is consistent with the new ensureCustomerExists flow. Consider adding a specific message for invalid/empty Custom IDs if you adopt a non-empty check server-side.

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts (1)

20-23: Optionally enforce non-empty custom customer_id.

Currently customer_id uses yupString().defined(), which allows empty strings. For "custom", that would flow through and produce changes for an empty identifier. Consider a minimal runtime check here (lighter than a schema-level conditional):

   if (!itemConfig) {
     throw new KnownErrors.ItemNotFound(req.params.item_id);
   }
+  if (req.params.customer_type === "custom" && req.params.customer_id.trim().length === 0) {
+    throw new StatusError(400, "customer_id must be non-empty for custom customers");
+  }

You’d need to import StatusError:

import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";

If you’d prefer schema-level validation, we can add a conditional yup.when on customer_type.

Also applies to: 42-44

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)

20-23: End-to-end: customer_type wiring and persistence look solid; validate expires_at to avoid invalid dates.

• The route schema and mismatch check are correct.
• ensureCustomerExists and uppercasing for persistence match the DB enum.
• One potential footgun: expires_at is a free-form string. If it’s malformed, new Date(...) yields Invalid Date, which can lead to DB errors or bad data.

Strengthen the body schema or add a runtime guard:

Schema-level (minimal change using a test):

 body: yupObject({
   delta: yupNumber().integer().defined(),
-  expires_at: yupString().optional(),
+  expires_at: yupString()
+    .test("is-iso-date", "expires_at must be a valid ISO date string", v => !v || !Number.isNaN(Date.parse(v)))
+    .optional(),
   description: yupString().optional(),
 }).defined(),

Or runtime guard before create:

const expiresAt = req.body.expires_at ? new Date(req.body.expires_at) : null;
if (expiresAt && Number.isNaN(expiresAt.getTime())) {
  throw new StatusError(400, "expires_at must be a valid ISO date string");
}

(For this runtime approach, import StatusError from @stackframe/stack-shared/dist/utils/errors.)

Also applies to: 49-51, 53-58, 65-67, 75-80

---

25-26: Nit: consider a boolean query param for allow_negative.

Using "true"/"false" strings is fine, but switching to a boolean in the schema (and auto-parsing) would be a small DX improvement.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

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

1220-1229: Conditional hook issue fixed — useAsyncCache is now called unconditionally.

This addresses the prior Biome error on conditional hooks in useItem.

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

605-609: Wording nit: reference the actual tokenStore values.

Error message currently suggests tokenStore value 'cookies', while the code uses 'cookie' and 'nextjs-cookie'.

Apply this small wording tweak:

-      throw new Error("Cannot call this function on a Stack app without a persistent token store. Make sure the tokenStore option on the constructor is set to a non-null value when initializing Stack.\n\nStack uses token stores to access access tokens of the current user. For example, on web frontends it is commonly the string value 'cookies' for cookie storage.");
+      throw new Error("Cannot call this function on a Stack app without a persistent token store. Make sure the tokenStore option on the constructor is set to a non-null value when initializing Stack.\n\nStack uses token stores to access access tokens of the current user. For example, on web frontends the tokenStore is commonly 'cookie' or 'nextjs-cookie'.");

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

517-523: Minor readability refactor: extract owner object before calling updateItemQuantity.

Current nested spread is correct but a bit dense to read.

Apply this small refactor:

-    await this._interface.updateItemQuantity(
-      { itemId: options.itemId, ...("userId" in options ? { userId: options.userId } : ("teamId" in options ? { teamId: options.teamId } : { customId: options.customId })) },
+    const owner =
+      "userId" in options ? { userId: options.userId } :
+      "teamId" in options ? { teamId: options.teamId } :
+                            { customId: options.customId };
+    await this._interface.updateItemQuantity(
+      { itemId: options.itemId, ...owner },
       {
         delta: options.quantity,
         expires_at: options.expiresAt,
         description: options.description,
       }
     );

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

1011-1035: Add missing dependencies to useMemo to avoid stale closures.

The returned ServerItem captures type and id inside useMemo but only depends on result. Include id and type to be safe when the discriminator changes.

Apply this minimal fix:

-    return useMemo(() => this._serverItemFromCrud({ type, id }, result), [result]);
+    return useMemo(() => this._serverItemFromCrud({ type, id }, result), [result, id, type]);

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.