https://www.loom.com/share/bb7abfde507f40d386ee856f5ffbd506
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* USD-based refund system enabling partial and full refunds with
explicit USD amounts
* Per-entry refund selection with granular quantity controls in refund
dialogs
* **Bug Fixes**
* Stronger refund validation and error handling to prevent invalid or
out-of-bounds refunds
* **Tests**
* Expanded end-to-end coverage for refund edge cases and scenarios
* **Style**
* Improved refund dialog UI with contextual alerts and better controls
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
### Summary of Changes
Previously, on the Swift SDK, the `signInWithOAuth` function wasn't
working. In this PR, we fix it by having the `getOAuthUrl` function to
actually redirect correctly. Note that to do so, we updated the
`validRedirectUrl` check on the backend to accept app native redirects
(from our new trusted url scheme). Another thing to note is that we
added functionality to the `TokenStore` abstraction to conditionally
refresh the access token that the user is trying to fetch if it is
expired/close to expiring if possible. `getOAuthUrl` will attempt to get
a valid access token, and thus will rely on our algorithm documented in
`utilities.md`.
The specs serve as the source of truth.
We go further and implement Apple Native sign in. To do so, we have it
hit a new route on the backend and verify the `jwtToken` retrieved by
the sdk against an Apple-provided set of `jwks`. We use jose to do so,
in line with the rest of the codebase.
We take this opportunity to refactor the oauth provider route owing to
the amount of duplicated logic. Additionally, to enable the apple sign
in, users will have to update the Apple authentication method modal on
the dashboard and add accepted bundle ids. These are identifiers for
projects, and we will check the `JWT` on the backend to make sure the
audience is set to an accepted bundleId.
We also update the Apple modal to be more informative.
### Using the new Features
To use the Apple native sign in, users will have to 1) sign up with an
apple developer account, 2) set up their bundleids for their projects by
connecting them to the apple developer account, 3) update the Stack-Auth
Authentication Methods dashboard apple modal with the relevant fields.
Then, trying to sign in with apple with our Swift SDK will use the apple
native sign in.
### UI Changes
Renamed the fields in the apple modal. Added a new field for bundle ids.
See below.
https://github.com/user-attachments/assets/0e760c0e-3198-4818-ac7f-4900d7a125bb
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
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Security**
* Added client-side access checks on payments endpoints and expanded
customer-type handling (including a new "custom" type).
* **SDK / Client**
* Client interface methods now accept explicit request types
(client/server/admin) to route requests appropriately.
* **Server**
* New server-side product listing to support server requests and
caching.
* **Tests**
* E2E tests updated to use a fast sign-up flow and pass authentication
tokens for authorized requests.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<img width="553" height="471" alt="Screenshot 2026-01-14 at 12 16 36 PM"
src="https://github.com/user-attachments/assets/9f32473d-5294-4cf7-b527-0668fb04ae47"
/>
<img width="630" height="514" alt="Screenshot 2026-01-14 at 12 17 06 PM"
src="https://github.com/user-attachments/assets/b17f57f7-148d-4438-b337-df7516d1793e"
/>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Expanded Stripe webhooks: handles invoice and one‑time/subscription
events, sends templated payment receipt and failure emails, posts
chargeback alerts to Telegram.
* Customer invoices API plus client and UI support for listing invoices;
backend stores invoice status, total, and hosted URL.
* **Tests**
* Added end‑to‑end tests for new webhook scenarios (receipts, failures,
chargebacks) and invoices API with email outbox checks.
* **Chores**
* Centralized Telegram helpers and improved formatting, validation, and
reliability.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Introduces end-to-end invoice visibility and payment notifications.
>
> - **Emails:** Adds default `payment_receipt` and `payment_failed`
templates and sends them from Stripe webhooks for one-time and
subscription payments (skips non‑uncollectible failures); resolves
recipients for users/teams.
> - **Webhooks:** Expands handled events; upserts invoices on
`invoice.*`; stricter unknown-type handling; adds Telegram chargeback
alert; refactors init script Telegram sending.
> - **Data model:** Extends `SubscriptionInvoice` with `status`,
`amountTotal`, `hostedInvoiceUrl` and writes them via
`upsertStripeInvoice`.
> - **API/SDK/UI:** New paginated `GET
/payments/invoices/{customer_type}/{customer_id}`; client interface
(`listInvoices`, hooks) and template Payments panel render an invoices
table.
> - **Tests:** E2E for invoices access, webhook behaviors, and email
delivery.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
edc8fe5651. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
### Summary of Changes
We would like to setup a payment settings page. Here, developers should
be able to toggle test mode, see their stripe connection status, and
adjust the payment method configs.
## Test Mode Toggle
This will exist in concert with the test mode banner.
## Stripe Connection Status
While users cannot see the page unless they create a stripe account,
they can still see it if they've created the stripe connected account
but haven't finished onboarding. This is a handy place for them to
finish their onboarding.
## Payment Methods
We would like developers using our payments feature to be able to set
what payment options should be made available to their users.
Consequently, we create a route and a page on the dashboard which hits
that route to update what payment options are made available. The UI
stores "pending changes" which represent updates to be made to the
payment method configs corresponding to that project's connected stripe
account. These are then sent to the backend, validated with a schema,
and then updated using stripe.
We also note that some payment methods have dependencies on others: for
example, the "apple pay" method cannot be enabled if the "debit/credit
cards" method is not enabled. We note the two cases where it is observed
to happen and raise an alert using `toast` to make it clear to the
developer, and make it extensible in case other dependencies are added
in the future. To ensure synchronization between the frontend dashboard
UI and the backend route handler on the payment method names, we have
both pull from a shared utility file. This ensures only one update will
need to be made.
**NOTE 1:** We chose to build our own component rather than using the
Stripe embedded component as the Stripe component is still in
pre-release mode.
**NOTE 2:** To disable specific payment methods for all our users, we
should update the platform account config in Stripe for stack-auth. This
will prevent said payment method from being made available to them.
**NOTE 3:** We skip the multi-account method config isolation test
because the stripe mock server does not support testing with multiple
accounts. However, the logic of the test has been verified with a real
stripe account.
### UI Demo
For this demo, I had a pre-created checkout link for a one-time purchase
of a product for 100$.
https://github.com/user-attachments/assets/a0139ee8-a9ce-480c-b8b5-9b5fb1e9c15f
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Centralized email-theme operations (create/read/list/update/delete)
behind a unified handler, simplifying endpoints and improving
consistency.
* **New Features**
* Theme updates now validate and render template previews before
applying changes; create supports generated or provided IDs.
* **Chores**
* Added a reusable CRUD handler factory to standardize backend
data-operation patterns and error handling.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
### Summary of Changes
We had an issue with a test being exceedingly flaky. This was a result
of not enough time having passed between the email being put up for
rendering/ being evaluated for skipped status and it being checked.
Polling reduces our dependency on arbitrary timeout periods. This is in
line with how we poll the inbox in other tests (see
`waitForMessagesWithSubject` in `helpers.ts`). It doesn't solve
flakiness because flakiness is a result of the indeterminism of what
we're testing.
Previously, we were using an old version of `freestyle.sh` and
experienced issues with it failing. We want to update it to the latest
API and also introduce a fallback that can be used when freestyle fails
to improve reliability. We refactor the `freestyle.tsx` wrapper code
around `freestyle` to a `js-execution-engine`, which also offers
opportunities to extend the email rendering engine abstraction in the
future. If `freestyle` encounters runtime errors while running the code
or fails, we retry once and then default to `Vercel sandbox`. Note that
we also introduce a sanity test: 5% of the time, we will run the code
through both `freestyle` and the `Vercel Sandbox` and log it if the
results don't match.
As a chore, we also up the time limit on a `failed-email-digest.test.ts`
test to make it less flakey.
https://www.loom.com/share/f218c4d16b4d4306be93685aad7aed7a
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* One-click subscription switching (client + server) and UI dialog to
choose alternative plans
* Products now show available plan alternatives (switch options)
* **Improvements**
* More robust default payment-method handling, validation, and clearer
errors when none is set
* Improved payment-method retrieval and customer metadata persistence
* **Tests**
* End-to-end tests for plan switching and updated billing snapshots
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<img width="1193" height="827" alt="Screenshot 2026-01-09 at 1 46 38 PM"
src="https://github.com/user-attachments/assets/2703cb15-0be6-4df5-9c79-a45ac514444e"
/>
<img width="1192" height="750" alt="Screenshot 2026-01-09 at 1 49 01 PM"
src="https://github.com/user-attachments/assets/9cfd4936-ed2f-4e4d-a5f9-0c25c87623f1"
/>
<!
--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Manage and set default payment methods (user & team) via Setup
Intents; Payments page in Account Settings to view/update card and
active plans.
* Product listings now include type (one_time | subscription) and
subscription details (period end, cancelable, cancel-at-period-end).
* Client/SDK: new billing APIs and Customer methods to fetch billing,
create setup intents, and apply default payment methods.
* **Tests**
* New end-to-end tests for billing flows, setup-intent, and access
control.
* **Chores**
* Added Stripe frontend libraries.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- restricted users
- onboarding app
- waitlist app
- fixed an exception when setting primary email
- automatically update the JWT token on the client when the user object
changes
<img width="1299" height="967" alt="Screenshot 2025-12-12 at 5 26 23 PM"
src="https://github.com/user-attachments/assets/5a33482a-510c-464c-a770-e71222ffc336"
/>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a "Payouts" section to the Payments dashboard with a dedicated
page and navigation link.
* Integrated a Stripe Connect payouts UI, allowing users to manage and
configure payout options (instant payouts, standard payouts, edit payout
schedule, external account collection).
* **Chores**
* Internal module path updates (no user-facing behavior changes).
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- 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
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Fixed email template retention: custom templates are now only
preserved when using dedicated email servers, not shared configurations.
* **Tests**
* Added end-to-end test coverage for email template behavior across
different server configurations.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
https://www.loom.com/share/7628a0b5f14e4367bcde93e4817a50e8
<img width="811" height="437" alt="image"
src="https://github.com/user-attachments/assets/6b02aae0-c723-43d4-92ab-a26e97623d9c"
/>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Enhance email templates with project branding and dark-mode support,
update schemas and API responses for new logo fields.
>
> - **Behavior**:
> - Email templates now support project branding with compact/full logos
and dark-mode variants in `email-rendering.tsx` and `emails.ts`.
> - Project name displays beside logos in Light and Dark themes in
`email-rendering.tsx`.
> - Email rendering groups branding and unsubscribe data for consistent
theming.
> - **API Changes**:
> - Project payloads and admin/project schemas rename `full_logo` to
`logo_full` and add dark-mode logo fields in `projects.ts` and
`schema-fields.ts`.
> - Updates to `projects.tsx` and `page-client.tsx` to handle new logo
fields.
> - **Style**:
> - Improved unsubscribe link contrast in Dark theme in `emails.ts`.
> - **Database**:
> - Adds `logoFullUrl`, `logoDarkModeUrl`, and `logoFullDarkModeUrl`
columns to `Project` table in `migration.sql`.
>
> <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 0fbb79db5c. 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 dark‑mode logo support for projects with separate logo and
full‑logo variants.
* Email themes/templates now render project logos and automatically
select light/dark variants with fallbacks.
* **Refactor**
* Project logo fields and public payloads renamed/reorganized to support
the new dark‑mode variants and consistent naming.
* **Tests**
* Updated test snapshots to reflect the new project logo fields.
* **Chores**
* Database migration applied to add/rename logo columns.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Adds light/dark logo variants, renames full-logo fields, and passes
project logos into email themes; updates DB, schemas, API, UI, and
tests.
>
> - **Database/Prisma**:
> - Rename `Project.fullLogoUrl` to `logoFullUrl`; add `logoDarkModeUrl`
and `logoFullDarkModeUrl`.
> - **Backend**:
> - Email rendering now accepts `themeProps` with `projectLogos` and
spreads into `EmailTheme` (single/batched).
> - Provide project logo URLs to email render/send and internal template
preview routes.
> - Add `@stackframe/emails` components (`Logo`, `FullLogo`,
`ProjectLogo`) with light/dark fallbacks.
> - Projects CRUD: map/upload new logo fields; rename API fields to
`logo_full_url` and add dark-mode fields.
> - **Emails (themes)**:
> - Light/Dark themes render `<ProjectLogo>`; improve dark-theme
unsubscribe link contrast.
> - **Dashboard/UI**:
> - Project settings support `logoFullUrl`, `logoDarkModeUrl`,
`logoFullDarkModeUrl` uploads.
> - Code editor types: add `ThemeProps.projectLogos`, relax TS option,
and Tailwind DTS fix.
> - **Shared Schemas/Types**:
> - Update `schema-fields` and CRUD read/update models to new/extra logo
fields; propagate through template app types.
> - **Tests**:
> - Update snapshots for new project logo fields and theme source
output.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
4d97561839. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: Bilal Godil <bg2002@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Projects now expose a domains field in the client API.
- Cookie API expanded: domain and secure options added, plus getAll and
isSecure helpers.
- **Refactor**
- Domain-aware cookie and token handling for cross-domain refresh flows.
- Minor signature/formatting tweaks to IP and URL utilities.
- **Tests**
- E2E coverage added: refresh-cookie scenarios and a project scaffolding
test.
- Backend snapshot updated to include domains.
- **Chores**
- Added a new dependency for domain parsing.
<!-- 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
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Sign-in now rejects empty email values and returns a validation error
instead of accepting them.
* **Tests**
* Added an end-to-end test that verifies signing in with an empty email
returns a schema validation error (HTTP 400).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
https://www.loom.com/share/64ad2f97fdd9476ebe5b66202098ec60
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Project logos now display on the purchase page; API surfaces
project_logo_url for the UI.
* Redesigned purchase page with responsive split-panel layout,
selectable pricing grid, quantity controls, and clearer invalid-code
messaging.
* **Tests**
* Added/updated end-to-end tests to cover project logo handling and
validate-code responses.
* **Chores**
* Updated image-processing dependency to a newer version.
<!-- 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
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Invitation flow now derives the invitation link from a provided origin
rather than accepting a full callback URL.
* **Bug Fixes / Security**
* Enforced origin whitelist for invitation redirects to prevent
untrusted callback URLs.
* **Tests**
* Added a test ensuring untrusted callback URLs are rejected with a
proper error response.
<!-- 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
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Sign-up accepts an optional verification callback URL and a new
opt-out flag to disable email verification; when opted-out or absent,
URL checks and verification emails are skipped.
* Client APIs and runtime validation updated to forbid providing a
callback URL when opting out. Sign-up now retries without a callback if
a redirect URL is not whitelisted.
* **Tests**
* End-to-end tests added for sign-up without verification and for
conflicting verification settings.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Konsti Wohlwend <N2D4@users.noreply.github.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 support for custom `metadata` to inline products in the
payments system. The change allows developers to attach arbitrary
metadata to products created inline (without pre-configuration), which
Stack Auth will store and return with the product. This enables
applications to associate custom data such as feature flags, reference
IDs, or other application-specific attributes with products. The
implementation adds a new `productSchemaWithMetadata` schema, updates
the product type handling in the backend, and includes comprehensive e2e
tests verifying metadata is persisted and returned correctly through
purchase creation, validation, and listing endpoints.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `packages/stack-shared/src/schema-fields.ts` |
| 2 | `apps/backend/src/lib/payments.tsx` |
| 3 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/purchase-session.test.ts`
|
| 4 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/create-purchase-url.test.ts`
|
| 5 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/products.test.ts` |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Products now support custom metadata (client, client read-only, and
server) and expose these fields in inline product representations.
* Metadata is preserved and propagated through purchase creation,
validation, grants, and owned-product listings so it’s available after
purchase.
* **Tests**
* Added end-to-end tests verifying metadata is accepted, persisted, and
returned in purchase creation, validation, grant, and listing flows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Adds support for custom metadata in inline products, updating schemas
and functions to handle metadata, with comprehensive tests verifying the
changes.
>
> - **Behavior**:
> - Adds support for custom metadata in inline products, allowing
arbitrary metadata attachment.
> - Updates `ensureProductIdOrInlineProduct()` and
`productToInlineProduct()` in `payments.tsx` to handle metadata.
> - Metadata is preserved and returned in purchase creation, validation,
and listing endpoints.
> - **Schemas**:
> - Adds `productSchemaWithMetadata` in `schema-fields.ts` to include
`clientMetadata`, `clientReadOnlyMetadata`, and `serverMetadata`.
> - Updates `inlineProductSchema` to support metadata fields.
> - **Tests**:
> - Adds e2e tests in `purchase-session.test.ts`,
`create-purchase-url.test.ts`, and `products.test.ts` to verify metadata
handling.
>
> <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 1b5601c991. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
ONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR changes the default development ports for several background
services to avoid conflicts. PostgreSQL moves from port `5432` to
`8128`, Inbucket SMTP from `2500` to `8129`, Inbucket POP3 from `1100`
to `8130`, and the OpenTelemetry collector from `4318` to `8131`. All
references across configuration files, Docker Compose setups,
environment files, CI/CD workflows, test files, and documentation have
been updated to reflect these new port assignments. A knowledge base
document has been added to document the new port mappings.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
| --- | --- |
| 1 | `claude/CLAUDE-KNOWLEDGE.md` |
| 2 | `apps/dev-launchpad/public/index.html` |
| 3 | `docker/dependencies/docker.compose.yaml` |
| 4 | `docker/emulator/docker.compose.yaml` |
| 5 | `apps/backend/.env` |
| 6 | `apps/backend/.env.development` |
| 7 | `docker/server/.env.example` |
| 8 | `package.json` |
| 9 | `.devcontainer/devcontainer.json` |
| 10 | `apps/e2e/.env.development` |
| 11 | `.github/workflows/check-prisma-migrations.yaml` |
| 12 | `.github/workflows/docker-server-test.yaml` |
| 13 | `.github/workflows/e2e-api-tests.yaml` |
| 14 | `.github/workflows/e2e-source-of-truth-api-tests.yaml` |
| 15 | `.github/workflows/restart-dev-and-test.yaml` |
| 16 |
`apps/e2e/tests/backend/endpoints/api/v1/internal/email-drafts.test.ts`
|
| 17 | `apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts`
|
| 18 | `apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts` |
| 19 |
`apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts` |
| 20 | `apps/e2e/tests/backend/workflows.test.ts` |
| 21 | `docs/templates/others/self-host.mdx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> This PR introduces customizable development ports using
`NEXT_PUBLIC_STACK_PORT_PREFIX`, updating configurations, documentation,
and tests accordingly.
>
> - **Behavior**:
> - Default development ports for services are now customizable via
`NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - PostgreSQL port changed from `5432` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28`.
> - Inbucket SMTP port changed from `2500` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}29`.
> - Inbucket POP3 port changed from `1100` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}30`.
> - OpenTelemetry collector port changed from `4318` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}31`.
> - **Configuration**:
> - Updated `docker.compose.yaml` to use new port variables for services
like PostgreSQL, Inbucket, and OpenTelemetry.
> - Environment files in `apps/backend`, `apps/dashboard`, and
`apps/e2e` updated to use `NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - `package.json` scripts updated to reflect new port configurations.
> - **Documentation**:
> - Added `CLAUDE-KNOWLEDGE.md` to document new port mappings.
> - Updated `self-host.mdx` to reflect new port configurations.
> - **Testing**:
> - Updated test files in `apps/e2e/tests` to use new port
configurations.
> - Added `helpers/ports.ts` for port-related utilities in tests.
>
> <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 76ef55f58f. 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**
- Enable configurable development ports via a
NEXT_PUBLIC_STACK_PORT_PREFIX, allowing parallel local environments with
custom port prefixes.
- **Bug Fixes**
- Updated local service port mappings and CI/workflow settings so
tooling and tests use the new prefixed ports consistently.
- **Documentation**
- Added docs and contributor guidance for running multiple parallel
workspaces with custom port prefixes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: N2D4 <N2D4@users.noreply.github.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 warning mechanism for incomplete Stripe payments setup by
checking if `charges_enabled` is true on the connected Stripe account.
The backend now retrieves and passes the `charges_enabled` status
through the purchase flow, and the frontend checkout form displays an
error message when payments are not fully enabled, preventing users from
attempting purchases on misconfigured accounts. Additionally, minor
cleanup was performed including removing unused test mode toggle state
management and fixing a description typo.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 |
`apps/backend/src/app/api/latest/payments/purchases/verification-code-handler.tsx`
|
| 2 |
`apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts`
|
| 3 |
`apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts`
|
| 4 | `apps/dashboard/src/components/payments/checkout.tsx` |
| 5 | `apps/dashboard/src/app/(main)/purchase/[code]/page-client.tsx` |
| 6 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/validate-code.test.ts`
|
| 7 |
`apps/e2e/tests/backend/endpoints/api/v1/payments/before-offer-to-product-rename/outdated--validate-code.test.ts`
|
| 8 |
`apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx`
|
| 9 |
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/products/page-client-catalogs-view.tsx`
|
</details>
<details>
<summary>⚠️ Inconsistent Changes Detected</summary>
| File Path | Warning |
|-----------|---------|
|
`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/products/page-client-catalogs-view.tsx`
| Removes error handling and loading state management for test mode
toggle, which seems unrelated to the charges_enabled warning feature |
|
`apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx`
| Changes description from 'Stripe price ID' to 'Stack auth price ID'
which is a documentation change unrelated to the charges_enabled warning
|
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Checkout interface now displays a "Payments not enabled" message with
guidance when charges are not enabled on the payment account.
* **Documentation**
* Clarified price ID field description in payment session documentation.
* **Tests**
* Updated payment validation endpoint test expectations to reflect new
response fields.
<!-- 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 payment test mode behavior by changing the default test
mode setting to `true` and refactoring the test mode bypass UI. The
bypass functionality is moved from a floating card in the purchase page
into the checkout form itself, providing a cleaner and more integrated
experience. Additionally, the database migration configuration is
updated to increase the `maxWait` timeout to handle concurrent migration
attempts more gracefully in high-contention scenarios like CI
environments.
⏱️ Estimated Review Time: 5-15 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `packages/stack-shared/src/config/schema.ts` |
| 2 | `apps/dashboard/src/app/(main)/purchase/[code]/page-client.tsx` |
| 3 | `apps/dashboard/src/components/payments/checkout.tsx` |
| 4 | `apps/backend/src/auto-migrations/index.tsx` |
</details>
<details>
<summary>⚠️ Inconsistent Changes Detected</summary>
| File Path | Warning |
|-----------|---------|
| `apps/backend/src/auto-migrations/index.tsx` | Database migration
timeout configuration changes appear unrelated to payment test mode
fixes, which is the stated purpose of this PR |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Sets payment test mode to default true, integrates test mode bypass
into checkout form, and updates migration timeout.
>
> - **Behavior**:
> - Default `testMode` set to `true` in `schema.ts`.
> - Integrates test mode bypass into `CheckoutForm` in `checkout.tsx`.
> - Removes separate bypass panel from `page-client.tsx`.
> - **Database**:
> - Increases `maxWait` timeout in `index.tsx` to handle concurrent
migration attempts.
> - **Tests**:
> - Updates tests in `backend-helpers.ts` and `validate-code.test.ts` to
reflect test mode behavior.
>
> <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 6313c0bfed. 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 a test-mode checkout path with a “Complete test purchase” action
when test mode is active.
* **Refactor**
* Consolidated test-mode bypass into the checkout component and removed
the separate bypass UI.
* **Bug Fixes**
* Improved reliability of database migrations by extending the
transaction wait window, reducing timeout errors under load.
* **Chores**
* Payments now default to test mode enabled.
* **Tests**
* Updated tests and payload expectations to reflect test mode defaults
and behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
