<img width="1920" height="969" alt="Screenshot 2026-02-04 at 9 47 16 AM"
src="https://github.com/user-attachments/assets/d7d0cd04-0051-4fc4-b857-e6f87ee97a59"
/>
**This PR revolves around the following components**
1. Sequencer - sequences the updates in the internal db
2. Poller - polls for the latest updates to sync with the external db
3. Outgoing Request Handler - essentially a trigger that can make http
requests based on a change in the internal db
4. Sync Engine - syncs with the latest changes from the internal db to
the external db
**What has been done**
- Added a global sequence id for ProjectUser, ContactChannel and
DeletedRow.
- Added the deletedRow table to keep track of the rows that were deleted
across ProjectUser and ContactChannel.
- Added the OutgoingRequest table to keep track of the outgoing requests
- Added function for the sequencer to call to sequence updates
- Added a sequencer that sequences all the changes in the internal db
every 50 ms
- Added a poller that polls for the latest changes in the internal db
every 50 ms, and adds to a queue
- Added a Vercel cron that calls sequencer and poller every minute
- Added a queue that fulfills the outgoing requests by making http calls
(for external db sync, it calls the sync engine endpoint)
- Added a sync engine that uses the defined sql mapping query in the
user's schema to pull in the changes for the user, and sync them with
the external db
- Added tests to test out each functionality
**How to review this PR:**
1. Review the migrations (sequence id, deletedRow, triggers, backlog
sync) (all files created under the migrations folder)
2. Review sequencer
3. Review poller
4. Review the changes in schema
5. Review sync-engine (the function, and it's helper file)
6. Review the schema changes, and query mappings
7. Review the tests (basic, advanced and race, along with the helper
file)
8. Review the changes made in Dockerfile to support local testing using
the postgres docker
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Introduces a cron-driven external DB sync pipeline with global
sequencing, internal poller and webhook sync engine, new DB
tables/functions, config schema/mappings, and comprehensive e2e tests.
>
> - **Database (Prisma/Migrations)**:
> - Add global sequence (`global_seq_id`) and
`sequenceId`/`shouldUpdateSequenceId` to `ProjectUser`,
`ContactChannel`, `DeletedRow` with partial indexes.
> - Create `DeletedRow` (capture deletes) and `OutgoingRequest` (queue)
tables; add unique/indexes.
> - Add triggers/functions: `log_deleted_row`,
`reset_sequence_id_on_update`, `backfill_null_sequence_ids`,
`enqueue_tenant_sync`.
> - **Backend/API**:
> - New internal routes: `GET
/api/latest/internal/external-db-sync/sequencer`, `GET /poller`, `POST
/sync-engine` (Upstash-verified) for sync orchestration.
> - Add cron wiring: `vercel.json` schedules and local
`scripts/run-cron-jobs.ts`; start in dev via `dev` script.
> - Tweak route handler (remove noisy logging) without behavior change.
> - **Sync Engine**:
> - Implement `src/lib/external-db-sync.ts` to read tenant mappings and
upsert to external Postgres (schema bootstrap, param checks,
sequencing).
> - Add default mappings `DEFAULT_DB_SYNC_MAPPINGS` and config schema
`dbSync.externalDatabases` in shared config.
> - **Testing/Infra**:
> - Add extensive e2e tests (basics, advanced, race conditions) for
sequencing, idempotency, deletes, pagination, multi-mapping, and
permissions.
> - Docker compose: add `external-db-test` Postgres for tests; e2e deps
for `pg` types.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3f2a8efcfb. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* External PostgreSQL sync: automatic, batched replication with
mappings, resume/idempotency, and on-demand enqueueing.
* **Admin UI**
* Real-time External DB Sync dashboard and status API showing
per-mapping backlog, sequencer/poller/sync-engine telemetry, and fusebox
controls.
* **Tests**
* Large e2e suite: basic, advanced, race, high-volume tests and test
utilities for external DB sync.
* **Chores**
* DB migrations, CI/workflow updates, background cron runner and
local/dev test support.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: Bilal Godil <bg2002@gmail.com>
<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **High Risk**
> Touches core sign-up/auth flows and user restriction semantics
(including new DB constraints) and introduces dynamic rule
evaluation/logging; misconfiguration or CEL/parser bugs could block
sign-ups or incorrectly restrict users.
>
> **Overview**
> Introduces **CEL-based sign-up rules** (config-driven) that are
evaluated during password/OTP/OAuth sign-ups and anonymous upgrades;
matching rules can reject sign-ups or mark users as admin-restricted,
and triggers are logged for analytics.
>
> Extends `ProjectUser` with `restrictedByAdmin` plus public/private
restriction details, updates restriction computation/filtering, and
exposes these fields via user CRUD (including validation + DB constraint
enforcing consistency when unrestricted).
>
> Adds a new dashboard **Sign-up Rules** page with a visual condition
builder (CEL <-> visual tree), drag-reorder by priority, per-rule 48h
sparkline analytics via a new hidden internal endpoint, and adds
user-page UI to view/edit manual restrictions. Also refactors ClickHouse
client initialization to require env vars (removing
`isClickhouseConfigured` checks) and adjusts CI container startup wait
time.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
2141e689e8c1b72303b805e9234f996010d0880. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Sign-up Rules: visual rule builder, in-project CRUD with drag-reorder,
per-rule analytics, backend evaluation, and admin UI.
* Admin user restrictions: dashboard controls, banners/status,
public/private admin details surfaced in user views.
* **APIs & Schema**
* Config and user schemas extended; new SignUpRejected error and sign-up
rule types added.
* **Tests**
* Extensive unit and E2E coverage for rules, parser, evaluator,
analytics, and restricted-user flows.
* **Docs**
* Editorial guidance added to AGENTS.md.
* **Chores**
* DB statement timeout, updated clean script, minor dependency
additions.
<!-- 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
* **New Features**
* Added a dedicated endpoint to retrieve query timing statistics using
query identifiers.
* Query responses now include a unique query_id for tracking and
reference.
* **Improvements**
* Query timeout validation now enforces a maximum limit of 2 minutes.
* Query response structure updated to support separate timing
information retrieval.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<img width="509" height="858" alt="image"
src="https://github.com/user-attachments/assets/520a1a01-f13f-4e20-a3e7-9e47a777b507"
/>
Full image view support:
<img width="2345" height="924" alt="image"
src="https://github.com/user-attachments/assets/f22f7a83-fc47-4d37-a251-56f1fbb62c8f"
/>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added interactive fullscreen image preview for changelog entries with
keyboard and click-to-close controls.
* **Improvements**
* Unified changelog date format to US M/D/YY for consistent display.
* Broadened external image loading so changelog images from common hosts
display reliably.
* Inserted image badge placeholders to enhance changelog visuals.
<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/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 -->
<!--
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**
* Changelog panel now fetches and displays recent releases with rich
Markdown rendering, per-release cards, and change-type labels.
* Visual cues (badge, glow, tooltip) indicate when unseen updates are
available; last-seen state tracked for users.
* **Chores**
* Configured external changelog data source and added a backend endpoint
to serve parsed changelog entries.
<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 -->
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
-->
# 🔒 Hidden Internal Endpoints from Public API Docs
Internal endpoints were incorrectly appearing in public API
documentation. Added hidden: true metadata to:
- /internal/init-script-callback - Telegram notification callback
- /internal/send-sign-in-invitation - Team invitation endpoint (public
equivalent: /team-invitations/send-code)
- /internal/projects/current - Internal project CRUD (adminRead,
adminUpdate, adminDelete)
- /internal/emails - Internal emails CRUD (adminList)
# 🏷️ Fixed Endpoint Categorization (moved from "Others")
Several endpoints were appearing in the "Others" category instead of
their proper sections:
- /emails/send-email -> Added tags: ["Emails"]
- Notification preferences CRUD -> Added complete docs with tags:
["Emails"]
- OAuth providers CRUD -> Changed tag from "OAuth Providers" → "Oauth"
to match naming convention; added missing clientUpdate docs
# 📝 API Documentation Improvements
- Fixed duplicate API Key titles: Updated handlers to use dynamic
summary (Create ${type} API key) instead of hardcoded "Create API key"
for both user and team keys
- Fixed empty Request section: API playground now only renders the
Request panel when there are actual parameters or request body fields to
display
# 🎨 UserButton Component Fixes
### Component (packages/template/src/components/user-button.tsx):
- Fixed hover effect centering (removed w-12 constraint, added p-1.5
padding)
- Fixed showUserInfo not displaying (changed flex-grow w-0 → min-w-0)
- Updated text styling with proper font sizes and theme-aware colors
- Added hover:transition-none for snappy UX
### Documentation Demo
(docs/src/components/stack-auth/stack-user-button-demo.tsx):
- Added not-prose class to fix avatar not rendering in MDX context
<img width="482" height="190" alt="image"
src="https://github.com/user-attachments/assets/c7c847c8-3ca5-4a40-bb33-f89949b6dbad"
/>
| Old | New |
|-----|-----|
| <img
src="https://github.com/user-attachments/assets/b0f2afe4-1499-49c0-946a-618a29876479"
width="180" /> | <img
src="https://github.com/user-attachments/assets/a358499c-f7e6-42c0-a0a0-2e6ad21728d2"
width="180" /> |
| Old | New |
|-----|-----|
| <img width="176" height="73" alt="image"
src="https://github.com/user-attachments/assets/1e17d77e-e4df-484d-adf4-19fcdaa0b471"
/> | <img width="198" height="76" alt="image"
src="https://github.com/user-attachments/assets/61d95ca8-61e5-48db-8fd8-75335751622f"
/> |
