https://www.loom.com/share/2767f799df9d48519c737a1d082fc3f4?sid=967802e9-5bfb-438d-96cd-2f6fcbd2f69b
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds a "Grant Product" feature to the dashboard's customer page,
allowing administrators to manually grant products to users, teams, or
custom customers. The UI has been updated to rename "Items" to
"Customers" in the navigation, and the page now includes a dialog for
selecting a product and quantity (for stackable products) to grant.
Additionally, the backend payment logic has been enhanced to properly
set `currentPeriodEnd` and `cancelAtPeriodEnd` when canceling
conflicting subscriptions during product grants.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/sidebar-layout.tsx`
|
| 2 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/customers/page.tsx`
|
| 3 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/customers/page-client.tsx`
|
| 4 | `apps/backend/src/lib/payments.tsx` |
| 5 |
`packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts`
|
</details>
<details>
<summary>⚠️ Inconsistent Changes Detected</summary>
| File Path | Warning |
|-----------|---------|
|
`packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts`
| This appears to be a simple variable rename (cache to itemsCache) that
seems unrelated to adding grant product functionality to the dashboard |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Adds "Grant Product" feature to dashboard, enabling admins to grant
products to customers, with new API endpoints, UI updates, and backend
logic enhancements.
>
> - **Behavior**:
> - Adds "Grant Product" feature to dashboard's customer page, allowing
admins to grant products to users, teams, or custom customers.
> - Updates UI to rename "Items" to "Customers" in navigation and adds
dialogs for product selection and quantity.
> - Enhances backend payment logic to set `currentPeriodEnd` and
`cancelAtPeriodEnd` when canceling conflicting subscriptions.
> - **API**:
> - New endpoints in `route.ts` for listing customer products and
granting products.
> - Implements `grantProductToCustomer()` in `payments.tsx` to handle
product grants.
> - **SDK**:
> - Adds `grantProduct` (server) and `listProducts` (client/server)
methods.
> - Updates `client-app-impl.ts` and `server-app-impl.ts` to support new
product functionalities.
> - **Models**:
> - Adds `CustomerProduct` and `CustomerProductsList` types in
`customers/index.ts`.
> - **Misc**:
> - Introduces `PRODUCT_ALREADY_GRANTED` error in `known-errors.tsx`.
> - Updates tests in `products.test.ts` and other test files to cover
new product grant scenarios.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for f0d112f578. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Dashboard: New "Customers" page to view customers, grant products, and
manage items with dialogs and selectors for users, teams, or custom IDs.
- API/SDK: Endpoints and client/server SDK methods to list a customer’s
products (paginated) and to grant products.
- **Improvements**
- Error responses for already-owned non-stackable products are now
structured with clear codes and headers.
- Product payloads include server_only, included_items, and new
stackable support.
- **UI**
- Team search table and clickable team rows for faster navigation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<img width="549" height="576" alt="Screenshot 2025-10-07 at 4 15 53 PM"
src="https://github.com/user-attachments/assets/7dd63333-691d-42f2-996f-80a22e9effca"
/>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds an optional tooltip feature to code blocks and improves the
UI layout and spacing in the product catalog view. The `CodeBlock`
component now accepts a `tooltip` prop that displays an info tooltip
next to the copy button. The product catalog view receives several
layout improvements including better spacing, reorganized form controls,
and the addition of tooltips to code blocks that explain their purpose.
The changes also swap item ID display for item display names in some
places for better readability.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `apps/dashboard/src/components/code-block.tsx` |
| 2 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/products/page-client-catalogs-view.tsx`
|
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Add tooltips to code blocks and adjust spacing in `ProductItemRow` for
improved UI and readability.
>
> - **Code Block Enhancements**:
> - Add `tooltip` prop to `CodeBlock` in `code-block.tsx` for displaying
tooltips with additional information.
> - Use `SimpleTooltip` to show tooltips next to the copy button.
> - **UI Adjustments**:
> - Adjust spacing in `ProductItemRow` in
`page-client-catalogs-view.tsx` for better layout.
> - Replace `itemId` with `itemDisplayName` for better readability.
> - Add tooltips to buttons in `ProductCard` for checkout and item
retrieval.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 5547ddb9c3. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- New Features
- Inline tooltips on code blocks and checkout actions.
- Per-item expiration editing via a dropdown, including a “Never
expires” option.
- Remove item action integrated directly into the editing row.
- UI Improvements
- Redesigned product item editing layout with clearer headers, spacing,
and grouped controls.
- Consistent use of item display names across views and cards.
- Enhanced checkout code block in product cards with explanatory
tooltip.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
…or non stackable offer
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR improves error messaging in the payments system by addressing
two main issues: (1) providing clearer error messages when an item ID is
mistakenly used as a product ID, including distinguishing between
non-existent products, server-only products, and cases where an item
exists with that ID, and (2) preventing checkout creation for
non-stackable products that a customer already owns by adding an early
validation check. The changes update the `ProductDoesNotExist` known
error to include contextual information, introduce a new
`getCustomerPurchaseContext` helper function to check existing
purchases, and update related test snapshots to reflect the improved
error messages.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `packages/stack-shared/src/known-errors.tsx` |
| 2 | `apps/backend/src/lib/payments.tsx` |
| 3 |
`apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts`
|
| 4 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/create-purchase-url.test.ts`
|
| 5 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/before-offer-to-product-rename/outdated--create-purchase-url.test.ts`
|
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Enhances payment error handling by adding context to error messages
and preventing duplicate purchases of non-stackable products.
>
> - **Behavior**:
> - Adds early validation in `create-purchase-url/route.ts` to prevent
checkout for non-stackable products already owned by the customer.
> - Updates `ensureProductIdOrInlineProduct` in `payments.tsx` to
include context in `ProductDoesNotExist` error.
> - Introduces `getCustomerPurchaseContext` in `payments.tsx` to check
existing purchases.
> - **Errors**:
> - Modifies `ProductDoesNotExist` in `known-errors.tsx` to include
`context` (null, server_only, item_exists).
> - **Tests**:
> - Updates test cases in `create-purchase-url.test.ts`,
`purchase-session.test.ts`, and `validate-code.test.ts` to reflect new
error messages and behavior.
> - Adds tests for blocking repeat purchases of non-stackable products.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 5495b9c269. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- New Features
- Blocks creating a purchase URL when a customer already owns a
non-stackable product, preventing duplicate checkouts.
- Bug Fixes
- Standardized error responses for missing or server-only products with
consistent codes, messages, and structured details.
- Error payloads now include details.context (null, server_only, or
item_exists) instead of access_type.
- Tests
- Added and updated tests to cover blocking repeat purchases and the new
standardized error format (including inline snapshot updates).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
Adds MCP installation instructions pages to docs:
<img width="1156" height="851" alt="image"
src="https://github.com/user-attachments/assets/ba3b1431-b3a5-403b-98ee-35afa8b93720"
/>
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds MCP (Model Context Protocol) installation documentation to
the Stack Auth docs. It creates a new page (`mcp-setup.mdx`) with
instructions for setting up Stack Auth's MCP server in various
development environments including Cursor, VS Code, Claude Code, Claude
Desktop, Windsurf, ChatGPT, and Gemini CLI. The PR includes necessary
supporting assets like SVG icons, a new button component, modifications
to existing components, and updates to configuration files to properly
register the new documentation page.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `docs/templates/others/mcp-setup.mdx` |
| 2 | `docs/docs-platform.yml` |
| 3 | `docs/src/components/icons.tsx` |
| 4 | `docs/src/components/mdx/button.tsx` |
| 5 | `docs/src/components/mdx/info.tsx` |
| 6 | `docs/src/mdx-components.tsx` |
| 7 | `docs/templates/meta.json` |
| 8 | `docs/public/imgs/mcp.svg` |
| 9 | `docs/public/imgs/vscode.svg` |
| 10 | `docs/public/imgs/cursor.svg` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Adds MCP installation instructions to documentation, introduces new
components, and updates existing components for enhanced MDX support.
>
> - **Documentation**:
> - Adds `mcp-setup.mdx` for MCP installation instructions in
`docs/templates/others`.
> - Updates `docs-platform.yml` and `meta.json` to include the new MCP
setup page.
> - **Components**:
> - Adds `Button` component in `button.tsx` for MDX content.
> - Updates `Info` component in `info.tsx` to include a size option for
compact notices.
> - Adds `StackAuthIcon` and `CursorIcon` to `icons.tsx` for MDX use.
> - **MDX Components**:
> - Exposes new `Button` and icons in `mdx-components.tsx`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for d8ef95cdfb. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added an MCP setup guide page available across Next, React, JS, and
Python.
* Introduced a reusable Button component for MDX content with
link/button behavior.
* Added a size option to Info components for compact notices.
* New StackAuth and Cursor icons available for MDX use.
* **Documentation**
* Added the MCP setup template to docs and navigation/meta.
* Exposed the new Button and icons in MDX component mappings.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Hi there, I have noticed that the project recently moved to using
freestyle.sh for rendering emails. I am currently self-hosting stack
auth and freestyle.sh does not have a privacy policy as far as I can
see. Therefore, it is not usable in a compliant way.
This PR simply adds an optional environment variable to be able to
override the API endpoint. This way, users can easily opt-out and use a
different implementation to render the mails.
Let me know if this is something you would consider merging and if the
variable should be added in some docs or examples.
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Add environment variable `STACK_FREESTYLE_API_ENDPOINT` to override
Freestyle API endpoint in `freestyle.tsx`.
>
> - **Behavior**:
> - Adds environment variable `STACK_FREESTYLE_API_ENDPOINT` to override
Freestyle API endpoint in `Freestyle` class constructor in
`freestyle.tsx`.
> - Defaults to `http://localhost:8122` for development and test
environments if API key is `mock_stack_freestyle_key` and no override is
set.
> - **Imports**:
> - Adds `getEnvVariable` import from
`@stackframe/stack-shared/dist/utils/env` in `freestyle.tsx`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 58ffd62704. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Freestyle service endpoint can be configured via an environment
variable for deployments.
* By default the configured endpoint is used; in development/test, a
mock key causes the client to point to a local default for local
testing.
* **Bug Fixes**
* Using the mock key outside development/test now triggers a validation
error to prevent accidental misuse.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Paul Graf <paul.graf@student.tugraz.at>
https://www.loom.com/share/59ff826f88324a61bb2fefc51769f840?sid=3fe23444-c56e-46c8-a402-8df38a69403c
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR improves the payment products UI by relocating the save/cancel
buttons from the top to the bottom of the product card and replacing the
generic `EditableInput` component with a custom `ProductEditableInput`
component that better handles the specific styling and interaction
patterns needed for product fields. The changes include better visual
feedback during editing and improved layout alignment for the price
input field.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/products/page-client-catalogs-view.tsx`
|
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* New Features
- Unified editable product input with read-only and inline editing
modes, placeholder support, and explicit Cancel/Save actions.
* Style
- Improved price-editing layout: aligned currency symbol, spacing, and
input visuals for clearer monetary entry.
- Polished input appearance for consistent look and feel across product
views.
* Refactor
- Replaced scattered editable fields with a single reusable input
component across product editing screens for consistency.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Move save/cancel buttons to bottom and replace `EditableInput` with
`ProductEditableInput` for improved UI in
`page-client-catalogs-view.tsx`.
>
> - **UI Changes**:
> - Move save/cancel buttons to the bottom of the product card in
`ProductCard`.
> - Replace `EditableInput` with `ProductEditableInput` for better
styling and interaction in `ProductCard`.
> - **Component Changes**:
> - Add `ProductEditableInput` component to handle product-specific
input styling and behavior.
> - Update `ProductPriceRow` to improve price input layout and visuals.
> - **Misc**:
> - Remove unused import of `EditableInput`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for c09cb54306. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR fixes a bug in the one-time purchase validation logic by
allowing stackable offers to be purchased multiple times. Previously,
the system blocked duplicate one-time purchases regardless of whether
the offer was marked as stackable. The fix adds a check to only prevent
duplicate purchases when the offer's `stackable` property is not `true`,
enabling customers to purchase stackable offers more than once.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `apps/backend/src/lib/payments.tsx` |
| 2 | `apps/backend/src/lib/payments.test.tsx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Fixes purchase validation to allow multiple purchases of stackable
products and updates tests accordingly.
>
> - **Behavior**:
> - Fixes bug in `validatePurchaseSession` in `payments.tsx` to allow
multiple purchases of stackable products.
> - Updates error message for non-stackable products to "Customer
already has purchased this product; this product is not stackable".
> - **Tests**:
> - Adds test cases in `payments.test.tsx` to verify stackable and
non-stackable purchase logic.
> - Ensures stackable products can be purchased multiple times, while
non-stackable products cannot.
> - **Misc**:
> - Minor updates to error messages and test descriptions for clarity.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 113d035b35. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- New Features
- Improved default product handling per catalog with clear errors when
multiple defaults are configured.
- Bug Fixes
- Unified validation for non-stackable products across subscriptions and
one-time purchases, preventing duplicate ownership.
- Standardized error message when attempting to repurchase a
non-stackable product: “Customer already has purchased this product;
this product is not stackable”.
- Tests
- Updated unit and end-to-end tests to reflect non-stackable product
behavior and the new error messaging.
- Adjusted scenarios and expectations around default product selection
and duplicate purchase blocking.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR fixes a bug where ungrouped offers with `include-by-default`
pricing were not being automatically included in subscription lists. The
fix ensures that ungrouped default offers are now properly added to the
subscriptions array when no explicit database subscription exists for
them, matching the existing behavior for grouped offers. Additionally,
it adds validation to prevent multiple `include-by-default` offers from
being configured within the same group.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `apps/backend/src/lib/payments.tsx` |
| 2 | `apps/backend/src/lib/payments.test.tsx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Fixes bug to include ungrouped `include-by-default` offers in
subscriptions and adds validation for multiple offers in the same group.
>
> - **Behavior**:
> - Fixes bug in `getSubscriptions()` in `payments.tsx` to include
ungrouped `include-by-default` offers in subscriptions when no explicit
subscription exists.
> - Adds validation in `getSubscriptions()` to prevent multiple
`include-by-default` offers in the same group.
> - **Tests**:
> - Adds test cases in `payments.test.tsx` to verify inclusion of
ungrouped `include-by-default` offers and validation of multiple offers
in the same group.
> - **Misc**:
> - Updates import in `payments.test.tsx` to include `getSubscriptions`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 565acc31cb. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* New Features
* Subscriptions now automatically include eligible “include-by-default”
items even when they aren’t tied to a catalog, granting access without
requiring an explicit subscription.
* Consistent handling of catalog-level default items when no prior
subscriptions exist.
* Improvements
* Expanded subscriptions data to ensure all applicable default products
are surfaced to users.
* Tests
* Added comprehensive tests for default-inclusion behavior and edge
cases to improve reliability.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR updates the peer dependency requirements across multiple
package.json files to remove support for React 18.2 and only specify
React 19.0.0-rc.0 or newer as the minimum required version. The change
affects React, React DOM, and their corresponding TypeScript type
packages.
⏱️ Estimated Review Time: 5-15 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `packages/react/package.json` |
| 2 | `packages/stack/package.json` |
| 3 | `packages/template/package-template.json` |
| 4 | `packages/template/package.json` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Update peer dependencies to require React 19.0.0 or newer across
multiple packages.
>
> - **Peer Dependencies**:
> - Updated minimum peer dependency to React 19.0.0 for `react`,
`react-dom`, `@types/react`, and `@types/react-dom` in
`packages/react/package.json`, `packages/stack/package.json`, and
`packages/template/package.json`.
> - Removed support for React 18.2 in peer dependencies across all
affected `package.json` files.
> - **Dev Dependencies**:
> - Updated development dependencies to React 19.0.0 in
`packages/react/package.json`, `packages/stack/package.json`, and
`packages/template/package.json`.
> - **Misc**:
> - No runtime behavior changes; only stricter dependency constraints.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for fa6ee35f32. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Raised peer dependency minimums to React 19.0.0 for react, react-dom,
@types/react, and @types/react-dom across packages.
* Bumped development dependencies used for building and testing to React
19.x.
* Applies to templates, stack packages, UI/shared packages, and
development tooling; no runtime behavior changes—only stricter
dependency requirements.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR implements a comprehensive renaming of "offer" to "product" and
"offer group" to "product catalog" throughout the codebase. The changes
include database migrations, schema updates, API compatibility layers,
function renames, and updates to client and server implementations.
Backwards compatibility is maintained through migration layers that
handle requests using the old terminology, translating them to the new
terminology before processing. The PR includes documentation of this
approach in CLAUDE-KNOWLEDGE.md. This rename affects multiple parts of
the system including the database schema, API endpoints, error types,
and SDK interfaces.
⏱️ Estimated Review Time: 1-3 hours
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 |
`apps/backend/prisma/migrations/20250923191615_rename_offers_to_products/migration.sql`
|
| 2 |
`apps/backend/src/app/api/migrations/v2beta1/payments/purchases/offers-compat.ts`
|
| 3 |
`apps/backend/src/app/api/migrations/v2beta1/payments/purchases/create-purchase-url/route.ts`
|
| 4 |
`apps/backend/src/app/api/migrations/v2beta1/payments/purchases/validate-code/route.ts`
|
| 5 | `apps/backend/src/lib/payments.tsx` |
| 6 | `.claude/CLAUDE-KNOWLEDGE.md` |
| 7 | `packages/stack-shared/src/schema-fields.ts` |
| 8 | `packages/stack-shared/src/known-errors.tsx` |
| 9 | `packages/stack-shared/src/config/schema.ts` |
| 10 | `packages/template/src/lib/stack-app/customers/index.ts` |
| 11 |
`packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts`
|
| 12 |
`packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts`
|
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Renames 'offer' to 'product' and 'offer group' to 'product catalog'
across the codebase, updating database schema, API endpoints, and
application logic for consistency and backward compatibility.
>
> - **Database**:
> - Rename columns `offer` to `product` and `offerId` to `productId` in
`OneTimePurchase` and `Subscription` tables in `migration.sql`.
> - **API & Migrations**:
> - Update API endpoints to accept `product_id`/`product_inline` instead
of `offer_id`/`offer_inline`.
> - Add `v2beta5` compatibility layer to map legacy `offer` fields to
`product` equivalents.
> - **Shared Schemas**:
> - Rename `offerSchema` to `productSchema` and related schemas in
`schema-fields.ts`.
> - **Server Implementation**:
> - Update `createCheckoutUrl` method in `server-app-impl.ts` to use
`productId`/`InlineProduct`.
> - **Tests**:
> - Update tests to reflect renaming in `backend-helpers.ts` and other
test files.
> - **Miscellaneous**:
> - Remove dummy data related to offers in `dummy-data.tsx`.
> - Update documentation and comments to reflect terminology changes.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for e3227bcbd2. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Backwards-compatibility: legacy offer_id/offer_inline requests are
accepted, normalized, and routed to product-based handlers.
* **Refactor**
* Global rename from Offer/Group → Product/Catalog across UI, APIs,
types, client/server interfaces, and error codes.
* **Bug Fixes**
* Responses, webhooks and UI consistently surface product_display_name
and product-related metadata.
* **Documentation**
* Migration notes and docs updated to explain compatibility and
parameter changes.
* **Tests**
* Unit and E2E suites updated to cover product/catalog flows.
* **Chores**
* Database schema migration, seed and config updates applied.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Renames offers→products and groups→catalogs end-to-end (DB, APIs,
schemas, UI, SDK, docs), adding v2beta5 compatibility to accept legacy
offer fields while updating all internals.
>
> - **Backend/DB**:
> - Prisma migration: rename `offer`/`offerId`→`product`/`productId` in
`OneTimePurchase` and `Subscription`.
> - Update Stripe webhook, purchase-session, and internal test-mode
flows to use `product*` metadata/fields.
> - **API & Migrations**:
> - Latest endpoints now accept `product_id`/`product_inline`.
> - Add `v2beta5` compat layer mapping legacy `offer_id`/`offer_inline`
to product equivalents; responses alias conflicting products.
> - **Shared Schemas/Errors/Config**:
> - `offerSchema`→`productSchema`,
`inlineOfferSchema`→`inlineProductSchema`, prices/types renamed.
> - KnownErrors renamed (e.g., `PRODUCT_DOES_NOT_EXIST`).
> - Config: `groups`→`catalogs`, defaults/migrations updated; improved
override validation messages; ID regex loosened; formatter tweaks; add
schema fuzzer tests.
> - **Payments Lib**:
> - Rename APIs and logic (`offers`→`products`, `groupId`→`catalogId`),
subscription and item-quantity computation updated.
> - **Dashboard/UI**:
> - Routes, dialogs, editors, tables, and code samples switched to
products/catalogs; removed offers dummy data.
> - **SDK/Template**:
> - Client/server `createCheckoutUrl` now uses
`productId`/`InlineProduct`.
> - **Tests/Docs/Utilities**:
> - E2E and unit tests updated; add legacy (pre-rename) tests.
> - Docs and knowledge base revised; minor script tweaks (recent-first,
limits).
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e6e20ecd72. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: BilalG1 <bg2002@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR fixes test issues by making two primary changes: 1) In the API
keys test, replacing `Date {}` with actual date strings in test
snapshots to make them deterministic, and 2) Adding "react-dom" to the
node modules list in the email rendering component. These changes likely
address test failures that were occurring due to non-deterministic date
serialization in snapshots and a missing dependency.
⏱️ Estimated Review Time: 5-15 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `apps/e2e/tests/js/api-keys.test.ts` |
| 2 | `apps/backend/src/lib/email-rendering.tsx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Fixes inline snapshot for `expiresAt` in `api-keys.test.ts` and adds
`react-dom` to dependencies in `email-rendering.tsx`.
>
> - **Tests**:
> - Fixes inline snapshot for `expiresAt` in `api-keys.test.ts` by using
a constant `expiresAt` variable.
> - Updates `expiresAt` field in three inline snapshots to use
`expiresAt.toISOString()`.
> - **Dependencies**:
> - Adds `react-dom` version "19.1.1" to `nodeModules` in
`email-rendering.tsx`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 290a6a2cf9. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved reliability of email template rendering, ensuring content
that relies on DOM behavior renders correctly during Freestyle
executions.
* **Tests**
* Unified expiration timestamps in API key tests for consistency and
updated related snapshots.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
Adds JWT docs and JWT viewer component to docs
<img width="1182" height="668" alt="image"
src="https://github.com/user-attachments/assets/f4196dd9-e159-420e-9d78-a3928983f126"
/>
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds comprehensive JWT (JSON Web Token) documentation and an
interactive JWT viewer component to the Stack Auth documentation. The
main additions are a new documentation page explaining JWT concepts,
structure, and usage within Stack Auth, along with a React component
that allows users to decode and inspect JWT tokens. The JWT viewer can
automatically load the current user's session token if they are signed
in, or accept manually pasted tokens. The documentation provides
examples of both client-side and server-side JWT usage, security
considerations, troubleshooting guidance, and best practices. The PR
also includes necessary updates to metadata files and component exports
to integrate the new content into the documentation platform.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `docs/templates/concepts/jwt.mdx` |
| 2 | `docs/src/components/mdx/jwt-viewer.tsx` |
| 3 | `docs/docs-platform.yml` |
| 4 | `docs/src/components/mdx/index.ts` |
| 5 | `docs/src/mdx-components.tsx` |
| 6 | `docs/templates/meta.json` |
| 7 | `docs/templates-python/meta.json` |
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Adds a new JWT concepts page and an interactive `JWTViewer` component,
integrating it into MDX and navigation, with `jose` added for decoding.
>
> - **Docs**:
> - Add `concepts/jwt.mdx` with JWT structure, claims, examples,
verification, security, and best practices.
> - Include JWT page in navigation: `docs-platform.yml`,
`templates/meta.json`, and Python `templates-python/meta.json`.
> - **UI Component**:
> - Add `JWTViewer` in `docs/src/components/mdx/jwt-viewer.tsx` to
decode JWTs (header, payload, signature), show time-based indicators,
and load current user token via `useUser()`.
> - Export and register in MDX: `docs/src/components/mdx/index.ts`,
`docs/src/mdx-components.tsx`.
> - **Dependencies**:
> - Add `jose` to `docs/package.json` (lockfile updated).
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for f25e369599. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[ad34cfe..a135bbd](ad34cfecc2...a135bbdd77)_
✨ No bugs found, your code is sparkling clean
<details>
<summary>✅ Files analyzed, no issues (3)</summary>
• `docs/src/components/mdx/jwt-viewer.tsx`
• `docs/src/mdx-components.tsx`
• `docs/src/components/mdx/index.ts`
</details>
<details>
<summary>⏭️ Files skipped (trigger manually) (4)</summary>
| Locations | Trigger Analysis |
|-----------|:------------------:|
`docs/docs-platform.yml` |
[
`docs/templates-python/meta.json` |
[
`docs/templates/concepts/jwt.mdx` |
[
`docs/templates/meta.json` |
[
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Interactive JWT Viewer in the docs: paste or auto-load a token to
inspect header, payload, signature with live decoding, validity/time
indicators, per-field copy controls, and "load my token".
* **Documentation**
* New "JWT" concept page covering structure, claims, examples,
client/server/manual usage, security, troubleshooting, and best
practices.
* JWT page added to site navigation and enabled across Next, React, JS,
and Python docs.
* **Chores**
* Added runtime dependency to support JWT decoding in the docs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Adds a new JWT concepts page and an interactive `JWTViewer` component,
integrating it into MDX and navigation, with `jose` added for decoding.
>
> - **Docs**:
> - Add `concepts/jwt.mdx` with JWT structure, claims, examples,
verification, security, and best practices.
> - Include JWT page in navigation: `docs-platform.yml`,
`templates/meta.json`, and Python `templates-python/meta.json`.
> - **UI Component**:
> - Add `JWTViewer` in `docs/src/components/mdx/jwt-viewer.tsx` to
decode JWTs (header, payload, signature), show time-based indicators,
and load current user token via `useUser()`.
> - Export and register in MDX: `docs/src/components/mdx/index.ts`,
`docs/src/mdx-components.tsx`.
> - **Dependencies**:
> - Add `jose` to `docs/package.json` (lockfile updated).
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
837fffb848. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<img width="324" height="252" alt="image"
src="https://github.com/user-attachments/assets/b7096a0c-9764-4fe7-b521-458d6e1d47b5"
/>
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds two new interactive components to the documentation pages:
a "Copy Markdown" button that allows users to copy the raw markdown
content of a page, and an "Open" dropdown menu that provides options to
open the current page in various AI tools (Scira AI, ChatGPT, Claude,
and T3 Chat). The implementation includes a new `page-actions.tsx`
component file with the `LLMCopyButton` and `ViewOptions` components,
and updates the documentation page layout to incorporate these new
buttons in the header alongside the page title.
⏱️ Estimated Review Time: 5-15 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `docs/src/components/page-actions.tsx` |
| 2 | `docs/src/app/docs/[[...slug]]/page.tsx` |
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Adds `LLMCopyButton` and `ViewOptions` to documentation pages for
copying markdown and opening in AI tools.
>
> - **New Features**:
> - Added `LLMCopyButton` in `page-actions.tsx` to copy markdown content
to clipboard.
> - Added `ViewOptions` in `page-actions.tsx` to open pages in AI tools
(Scira AI, ChatGPT, Claude, T3 Chat).
> - **Integration**:
> - Integrated `LLMCopyButton` and `ViewOptions` into `page.tsx` header
layout.
> - Adjusted header layout in `page.tsx` to align title and new buttons.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for b51bb98d4e. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[e48ffa6..3cbe5a5](e48ffa67ee...3cbe5a5861)_
✨ No bugs found, your code is sparkling clean
<details>
<summary>✅ Files analyzed, no issues (2)</summary>
• `docs/src/components/page-actions.tsx`
• `docs/src/app/docs/[[...slug]]/page.tsx`
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added header actions on docs pages: a button to copy the page Markdown
to clipboard and an “Open” menu to launch external AI chat tools or view
the source.
* **Documentation**
* Updated docs page header layout so the title is left-aligned with
action controls on the right for easier access.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Adds header actions to docs pages: copy raw Markdown and open the page
in external AI tools.
>
> - **Docs UI**:
> - **New components** in `docs/src/components/page-actions.tsx`:
> - `LLMCopyButton`: copies raw Markdown to clipboard with simple
caching.
> - `ViewOptions`: popover with links to external AI tools (Scira,
ChatGPT, Claude, T3 Chat).
> - **Integration** in `docs/src/app/docs/[[...slug]]/page.tsx`:
> - Wraps `DocsTitle` with a header row and adds `LLMCopyButton` and
`ViewOptions`.
> - Passes `markdownUrl` as ``${page.url}.mdx`` for both actions.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
5578cc9d37. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR enhances the initialization script for Stack Auth by adding
support for `projectId` and `publishableClientKey` (pck) parameters when
initializing a Next.js client application. The changes include: 1)
Adding logic to pass these parameters from environment variables or
directly from arguments to the Next.js client configuration, 2) Updating
the layout template to use the client-side Stack app instead of the
server-side app in the provider component, and 3) Improving Bun lock
file detection by checking for both `bun.lockb` and `bun.lock` formats.
These changes ensure proper configuration of Next.js client applications
with the required Stack Auth credentials.
⏱️ Estimated Review Time: 5-15 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `packages/init-stack/src/index.ts` |
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Enhances Stack Auth init script with `projectId` and
`publishableClientKey` support, updates Next.js layout, and improves Bun
detection.
>
> - **Behavior**:
> - Adds `projectId` and `publishableClientKey` support to Next.js
client configuration in `index.ts`.
> - Updates layout template to use client-side Stack app in
`getUpdatedLayout()`.
> - Improves Bun lock file detection in `promptPackageManager()`.
> - **Options**:
> - Introduces `--on-question` option to control interactive prompts in
`index.ts`.
> - **Scripts**:
> - Standardizes test scripts to use `--on-question error` in
`package.json`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 67a98f5aba. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[7a0bf86..0b443e4](7a0bf86cb3...0b443e460f)_
✨ No bugs found, your code is sparkling clean
<details>
<summary>✅ Files analyzed, no issues (1)</summary>
• `packages/init-stack/src/index.ts`
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a new --on-question option to control interactive prompt
behavior; client-oriented layout generation now emits client-side config
(public env keys supported).
* **Bug Fixes**
* Improved Bun detection (recognizes both lockfile variants) and
clearer, mode-aware guidance for ambiguous project/package-manager
detection.
* **Chores**
* Test/init scripts updated to use --on-question error for deterministic
non-interactive runs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR fixes a test in the internal metrics endpoint by replacing a
simple wait timer with a more robust retry mechanism. Instead of waiting
for a fixed 3000ms delay to allow for asynchronous event logging, the PR
implements a `Result.retry` approach that attempts to fetch metrics up
to 5 times with exponential backoff, only proceeding when the metrics
response differs from the initial state. This change makes the test more
reliable by ensuring proper test conditions are met before assertions
are made rather than relying on an arbitrary timeout.
⏱️ Estimated Review Time: 5-15 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `apps/e2e/tests/backend/endpoints/api/v1/internal-metrics.test.ts`
|
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Tests**
* Improved backend metrics verification with a retry-based approach to
handle eventual consistency, reducing test flakiness.
* Replaced static waits with structured retries for faster, more
reliable execution.
* Strengthened assertions on metrics fields (e.g., totals and recent
activity) for clearer validation.
* Maintains checks to ensure anonymous users remain excluded from
metrics.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Add Convex integration with new auth helpers, update access token
handling, and include documentation, examples, and tests for the new
features.
>
> - **Features**:
> - Add Convex integration with new auth helpers for Convex clients and
HTTP in `client-app-impl.ts` and `server-app-impl.ts`.
> - Support for Convex context in user APIs and partial user retrieval.
> - Access tokens now include `is_anonymous` for better anonymous
handling in `tokens.tsx`.
> - **Documentation**:
> - Add Convex integration guide in `docs/templates/others/convex.mdx`.
> - Update docs navigation in `docs/docs-platform.yml` and
`docs/templates/meta.json`.
> - **Examples**:
> - Add Convex + Next.js example app in `examples/convex` with auth
wiring, functions, schema, and UI.
> - **Tests**:
> - Add E2E tests for Convex auth flows in `convex.test.ts`.
> - Update JWT payload checks in `backend-helpers.ts` and
`anonymous-comprehensive.test.ts`.
> - **Chores**:
> - Add Convex dependencies in `package.json` files.
> - Update CI steps for example environments in `e2e-api-tests.yaml` and
`e2e-source-of-truth-api-tests.yaml`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for aa0983a8b7. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Convex integration: auth helpers for Convex clients/HTTP, Convex-aware
user APIs, and partial-user retrieval (token/convex).
- Access tokens now surface is_anonymous for clearer anonymous handling.
- **Documentation**
- Added Convex integration guide and nav entries.
- **Examples**
- New Convex + Next.js example app with auth wiring, backend functions,
schema, and UI.
- **Tests**
- Added E2E tests covering Convex auth flows and JWT payload checks.
- **Chores**
- Added Convex deps, CI env steps, and workspace/test config updates.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds a toggle switch feature for the payments offers page,
allowing users to switch between two different view modes: a catalog
view (card-based layout) and a list view. The original code from
`page-client.tsx` has been split into two separate files -
`page-client-catalogs-view.tsx` for the existing card-based catalog view
and `page-client-list-view.tsx` for the new list-based view. The main
`page-client.tsx` file now acts as a simple router between these two
views, maintaining a view state and rendering the appropriate component
based on the selected view. Both view components include a toggle switch
in their header to allow users to switch between views.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page-client.tsx`
|
| 2 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page-client-catalogs-view.tsx`
|
| 3 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page-client-list-view.tsx`
|
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[872174d..a5ad8d9](872174d5b7...a5ad8d9fd1)_
✨ No bugs found, your code is sparkling clean
<details>
<summary>✅ Files analyzed, no issues (3)</summary>
•
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page-client-catalogs-view.tsx`
•
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page-client-list-view.tsx`
•
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page-client.tsx`
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- New Features
- Added revamped Payments Offers management with two views: List and
Catalogs.
- Grouping and sorting of offers by customer type, addons, and price.
- Inline create/edit/duplicate/delete for offers, prices, and items with
dialogs and validations.
- Search, filters, and hover-based highlighting with visual connections
between offers and items.
- Responsive layout (desktop and mobile), tooltips, and helpful
empty-state onboarding.
- Refactor
- Simplified page into dedicated List and Catalogs views with seamless
switching for a clearer, faster experience.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds a new `priceId` field to the `OneTimePurchase` and
`Subscription` models in the database to store Stripe price identifiers.
The change includes database schema updates, corresponding migration
files, and modifications to payment processing logic to properly track
and store price IDs throughout the purchase flow. The implementation
consistently propagates the price ID from Stripe's API responses through
various payment processing endpoints and webhooks handlers, ensuring the
data is properly stored and synced with the database models.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `apps/backend/prisma/schema.prisma` |
| 2 |
`apps/backend/prisma/migrations/20250917193043_store_price_id/migration.sql`
|
| 3 | `apps/backend/src/lib/stripe.tsx` |
| 4 |
`apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx`
|
| 5 |
`apps/backend/src/app/api/latest/internal/payments/test-mode-purchase-session/route.tsx`
|
| 6 |
`apps/backend/src/app/api/latest/integrations/stripe/webhooks/route.tsx`
|
| 7 | `apps/e2e/tests/backend/endpoints/api/v1/stripe-webhooks.test.ts`
|
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Add `priceId` field to track Stripe price identifiers in purchase and
subscription models, updating schema, payment logic, and tests.
>
> - **Database Changes**:
> - Add `priceId` field to `OneTimePurchase` and `Subscription` models
in `schema.prisma`.
> - Update database schema with migration
`20250917193043_store_price_id/migration.sql`.
> - **Payment Processing**:
> - Update `processStripeWebhookEvent()` in `webhooks/route.tsx` to
handle `priceId`.
> - Modify `POST` handlers in `purchase-session/route.tsx` and
`test-mode-purchase-session/route.tsx` to include `priceId` in metadata.
> - Update `syncStripeSubscriptions()` in `stripe.tsx` to sync
`priceId`.
> - **Testing**:
> - Add tests in `stripe-webhooks.test.ts` to validate `priceId`
handling in webhook and purchase flows.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 4950494d62. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[e48ffa6..4950494](e48ffa67ee...4950494d62)_
| Severity | Location | Issue
| Delete |
|:----------:|----------|-------|:--------:|
|  |
[apps/e2e/tests/backend/endpoints/api/v1/stripe-webhooks.test.ts:153](https://github.com/stack-auth/stack-auth/pull/900#discussion_r2356623574)
| The field `priceId` uses camelCase instead of the required snake_case
for API parameters |
[
|
|  |
[apps/e2e/tests/backend/endpoints/api/v1/stripe-webhooks.test.ts:245](https://github.com/stack-auth/stack-auth/pull/900#discussion_r2356623664)
| The field `priceId` uses camelCase instead of the required snake_case
for API parameters |
[
|
|  |
[apps/e2e/tests/backend/endpoints/api/v1/stripe-webhooks.test.ts:358](https://github.com/stack-auth/stack-auth/pull/900#discussion_r2356623721)
| The field `priceId` uses camelCase instead of the required snake_case
for API parameters |
[
|
<details>
<summary>✅ Files analyzed, no issues (4)</summary>
• `apps/backend/src/lib/stripe.tsx`
•
`apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx`
•
`apps/backend/src/app/api/latest/integrations/stripe/webhooks/route.tsx`
•
`apps/backend/src/app/api/latest/internal/payments/test-mode-purchase-session/route.tsx`
</details>
<details>
<summary>⏭️ Files skipped (trigger manually) (2)</summary>
| Locations | Trigger Analysis |
|-----------|:------------------:|
`apps/backend/prisma/migrations/20250917193043_store_price_id/migration.sql`
|
[
`apps/backend/prisma/schema.prisma` |
[
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- New Features
- Persist the selected price ID with one-time purchases and
subscriptions.
- Carry the price ID through payment flows and Stripe metadata for
better tracking and reporting.
- Test mode purchases now also record the price ID.
- Chores
- Database migration adds a price ID field to purchase and subscription
records.
- Tests
- Updated end-to-end tests to validate price ID handling in webhook and
purchase flows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds an optional `returnTo` parameter to the `signInWithOAuth`
function in the Stack Auth SDK. This allows developers to specify a
custom redirect URL after OAuth authentication instead of always using
the default OAuth callback URL. The change updates both the interface
definition and the implementation to support this new optional
parameter.
⏱️ Estimated Review Time: 0h 15m
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 |
`packages/template/src/lib/stack-app/apps/interfaces/client-app.ts` |
| 2 |
`packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts`
|
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Add optional `returnTo` parameter to `signInWithOAuth` for custom
redirect URLs in `client-app-impl.ts` and update interface in
`client-app.ts`.
>
> - **Behavior**:
> - `signInWithOAuth` in `client-app-impl.ts` now accepts an optional
`options` parameter with `returnTo` for custom redirect URLs.
> - Default redirect URL is `this.urls.oauthCallback` if `returnTo` is
not provided.
> - **Interfaces**:
> - Updated `signInWithOAuth` signature in `client-app.ts` to include
optional `options` parameter with `returnTo`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for eb748cbe77. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[2d2a6d7..eb748cb](2d2a6d7cd5...eb748cbe77)_
✨ No bugs found, your code is sparkling clean
<details>
<summary>✅ Files analyzed, no issues (2)</summary>
•
`packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts`
• `packages/template/src/lib/stack-app/apps/interfaces/client-app.ts`
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* signInWithOAuth now accepts an optional options parameter with
returnTo, allowing apps to override the post-login redirect URL.
* Defaults remain unchanged; if returnTo isn’t provided, the existing
OAuth callback is used.
* Backwards compatible: existing calls without options continue to work.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
