CodeCow/stack
1
0
Fork 0
mirror of https://github.com/stack-auth/stack.git synced 2026-06-04 21:04:37 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
db02f71b73
stack/AGENTS.md
BilalG1 db02f71b73
payments schema changes, ledger algo, stackable items (#862) 
<!--

Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md

-->

<!-- ELLIPSIS_HIDDEN -->


----

> [!IMPORTANT]
> Enhances payments system with stackable items, Stripe account
management, and improved purchase flow, including schema updates and new
tests.
> 
>   - **Behavior**:
> - Adds quantity support for stackable offers in
`apps/backend/src/lib/payments.tsx` and
`apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx`.
> - Introduces Stripe account info viewing and onboarding in
`apps/backend/src/app/api/latest/internal/payments/stripe/account-info/route.ts`.
> - Implements "Include by default" pricing and "Plans" group in
`apps/backend/prisma/seed.ts`.
>   - **Schema Changes**:
> - Adds `quantity` and `offerId` columns to `Subscription` table in
`apps/backend/prisma/migrations/20250821212828_subscription_quantity/migration.sql`
and
`apps/backend/prisma/migrations/20250822203223_subscription_offer_id/migration.sql`.
> - Adds `stripeAccountId` column to `Project` table in
`apps/backend/prisma/migrations/20250825221947_stripe_account_id/migration.sql`.
>   - **Improvements**:
> - Enhances purchase flow to return Stripe `client_secret` and handle
subscription upgrades/downgrades in
`apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx`.
> - Updates item management with new actions and protections in
`apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts`.
> - Tightens validation for customer type and offer conflicts in
`apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts`.
>   - **Testing**:
> - Adds extensive tests for new payment features in
`apps/e2e/tests/backend/endpoints/api/v1/internal/payments/setup.test.ts`
and
`apps/e2e/tests/backend/endpoints/api/v1/payments/purchase-session.test.ts`.
>   - **Misc**:
> - Removes unused `stripeAccountId` and `stripeAccountSetupComplete`
from `branchPaymentsSchema` in
`packages/stack-shared/src/config/schema.ts`.
> - Refactors currency constants into `currency-constants.tsx` in
`packages/stack-shared/src/utils`.
> 
> <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 264563541d. 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**
- Quantity support for stackable offers across checkout, test purchases,
and admin flows.
- View Stripe account info and interactive payments onboarding per
project.
- "Include-by-default" pricing and new "Plans" group (Free, Extra
Admins).

- **Improvements**
- Purchase flow returns Stripe client_secret and handles group-based
subscription upgrades/downgrades.
- Item management: Update Customer Quantity action, edit/delete
protections, and read-only form mode.
- Validation surfaces offer conflicts (already_bought_non_stackable,
conflicting_group_offers).

- **Changes**
  - Default item quantities now start at 0 unless explicitly granted.
  - Stripe account linkage is stored per project.

- **Tests**
- Expanded tests for quantities, stackable behavior, and group
transition scenarios.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
2025-08-27 20:13:22 +00:00

4.6 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Essential Commands

  • Install dependencies: pnpm install
  • Run tests: pnpm test run (uses Vitest). You can filter with pnpm test run <file-filters>. The run is important to not trigger watch mode
  • Lint code: pnpm lint. pnpm lint --fix will fix some of the linting errors, prefer that over fixing them manually.
  • Type check: pnpm typecheck

Extra commands

These commands are usually already called by the user, but you can remind them to run it for you if they forgot to.

  • Build packages: pnpm build:packages
  • Start dependencies: pnpm restart-deps (resets & restarts Docker containers for DB, Inbucket, etc. Usually already called by the user)
  • Run development: Already called by the user in the background. You don't need to do this. This will also watch for changes and rebuild packages, codegen, etc.
  • Run minimal dev: pnpm dev:basic (only backend and dashboard for resource-limited systems)

Testing

You should ALWAYS add new E2E tests when you change the API or SDK interface. Generally, err on the side of creating too many tests; it is super important that our codebase is well-tested, due to the nature of the industry we're building in.

  • Run all tests: pnpm test run
  • Run some tests: pnpm test run <file-filters>

Database Commands

  • Generate migration: pnpm db:migration-gen
  • Reset database (rarely used): pnpm db:reset
  • Seed database (rarely used): pnpm db:seed
  • Initialize database (rarely used): pnpm db:init
  • Run migrations (rarely used): pnpm db:migrate

Architecture Overview

Stack Auth is a monorepo using Turbo for build orchestration. The main components are:

Apps (/apps)

  • backend (/apps/backend): Next.js API backend running on port 8102
    • Main API routes in /apps/backend/src/app/api/latest
    • Database models using Prisma
  • dashboard (/apps/dashboard): Admin dashboard on port 8101
  • dev-launchpad: Development portal on port 8100
  • e2e: End-to-end tests

Packages (/packages)

  • stack (/packages/stack): Main Next.js SDK
  • stack-shared (/packages/stack-shared): Shared utilities and types
  • stack-ui (/packages/stack-ui): UI components
  • react (/packages/react): React SDK
  • js (/packages/js): JavaScript SDK

Key Technologies

  • Framework: Next.js (with App Router)
  • Database: PostgreSQL with Prisma ORM
  • Testing: Vitest
  • Package Manager: pnpm with workspaces
  • Build Tool: Turbo
  • TypeScript: Used throughout
  • Styling: Tailwind CSS

API Structure

The API follows a RESTful design with routes organized by resource type:

  • Auth endpoints: /api/latest/auth/*
  • User management: /api/latest/users/*
  • Team management: /api/latest/teams/*
  • OAuth providers: /api/latest/oauth-providers/*

Development Ports

To see all development ports, refer to the index.html of apps/dev-launchpad/public/index.html.

Important Notes

  • NEVER UPDATE packages/stack OR packages/js. Instead, update packages/template, as the others are simply copies of that package.
  • For blocking alerts and errors, never use toast, as they are easily missed by the user. Instead, use alerts.
  • Environment variables are pre-configured in .env.development files
  • Always run typecheck, lint, and test to make sure your changes are working as expected. You can save time by only linting and testing the files you've changed (and/or related E2E tests).
  • The project uses a custom route handler system in the backend for consistent API responses
  • Sometimes, the typecheck will give errors along the line of "Cannot assign Buffer to Uint8Array" or similar, on changes that are completely unrelated to your own changes. If that happens, tell the user to run pnpm clean && pnpm i && pnpm run codegen && pnpm build:packages, and restart the dev server (you cannot run this yourself). After that's done, the typecheck should pass.
  • When writing tests, prefer .toMatchInlineSnapshot over other selectors, if possible. You can check (and modify) the snapshot-serializer.ts file to see how the snapshots are formatted and how non-deterministic values are handled.
  • Whenever you learn something new, or at the latest right before you call the Stop tool, write whatever you learned into the ./claude/CLAUDE-KNOWLEDGE.md file, in the Q&A format in there. You will later be able to look up knowledge from there (based on the question you asked).

Code-related

  • Use ES6 maps instead of records wherever you can.