Feat/crater implementation

.env.example

@@ -1,14 +1,17 @@
-# Build-Time
-NEXT_PUBLIC_APP_URL=https://localhost:3000
-NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
+GA_MEASUREMENT_ID=G-XXXXXXXXXX
+STRIPE_PUBLIC_KEY=pk_test_example
 
-# Build/Run-Time
 DATABASE_URL=postgresql://user:1234@localhost:5432/payload
 PAYLOAD_SECRET=secret_key
 PAYLOAD_USER_PASS=test_password123
 ACTIONS_IMPORT_SECRET=secret_import_key
 
-# Run-Time
+CRATER_GRAPHQL_URL=https://api.example.com/graphql
+
+SERVER_URL=http://localhost:3000
+SCULPTOR_URL=http://localhost:3001
+SCULPTOR_LOGIN_URL=http://localhost:3001/redirect
+
 SMTP_HOST=smtp.example.com
 SMTP_PORT=587
 SMTP_USER=your-smtp-user

.github/workflows/ci.yml

@@ -17,8 +17,7 @@ jobs:
     env:
       PAYLOAD_SECRET: build-secret
       DATABASE_URL: postgresql://postgres:postgres@localhost:5432/payload
-      NEXT_PUBLIC_APP_URL: https://codezero.build
-      NEXT_PUBLIC_GA_MEASUREMENT_ID: G-55EJVGDCLZ
+      SERVER_URL: https://codezero.build
 
     steps:
       - uses: actions/checkout@v7

.gitignore

@@ -24,6 +24,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+.next-dev-*.log
 
 # local env files
 .env*.local

AGENTS.md

@@ -0,0 +1,62 @@
+# Project Instructions
+
+These instructions apply to the entire repository.
+
+## Billing and Payment Service
+
+Crater is the billing service used by this project. Before changing any code
+related to billing, customers, authentication sessions, checkout, discounts,
+taxes, subscriptions, invoices, or licenses, read `docs/crater.md` completely.
+Treat that document as the primary project-level summary of the Crater API and
+domain model.
+
+If more detail is required, consult the source documentation referenced by
+`docs/crater.md`, especially the GraphQL schema documentation and database ERD.
+Do not infer undocumented fields, mutation arguments, authentication headers,
+or response shapes.
+
+## Crater Integration Rules
+
+- Access Crater through its GraphQL API using the Apollo client in
+  `src/lib/apolloClient.ts`.
+- Keep Crater requests on the server unless a task explicitly requires
+  client-side access and exposing that access is known to be safe.
+- Keep API URLs, tokens, session credentials, Stripe secrets, and other
+  sensitive values in environment variables. Never hard-code or commit them.
+- Use the Crater user session produced by `usersLogin` where an authenticated
+  operation requires it. A Sagittarius token is an input to login, not a
+  substitute for assumptions about Crater session authentication.
+- Use the exact GraphQL types, argument names, nullability, and response fields
+  documented by Crater.
+- Handle both transport-level GraphQL errors and the non-null `errors` field
+  returned by mutation payloads.
+- Preserve and surface documented Crater error codes where useful. Do not
+  reduce all domain failures to a generic checkout error.
+- Send monetary amounts as integers in the smallest currency unit. Do not use
+  floating-point values for amounts transferred to Crater.
+- Treat checkout tax quotes as non-binding previews.
+- For `checkoutCreateSession`, use either a regular plan checkout or a custom
+  checkout configuration as documented. Do not combine their semantics.
+- Only send `namespaceId` for cloud deployments.
+- Use the checkout redirect URL returned by Crater. Do not recreate Crater's
+  Stripe Checkout Session directly in this application unless the architecture
+  is explicitly changed.
+- Do not duplicate subscription, invoice, license, or Stripe webhook state that
+  is owned by Crater without a documented application requirement.
+- Avoid sharing cached customer or payment data between requests. Use
+  `no-cache` for sensitive or request-specific Apollo operations when
+  appropriate.
+
+## Implementation and Verification
+
+- Keep GraphQL operations close to the relevant billing integration code and
+  give operations descriptive names.
+- Add explicit TypeScript types for operation variables and relevant response
+  data unless generated GraphQL types are available.
+- Validate required environment variables and return safe errors that do not
+  expose credentials or sensitive payment information.
+- After changing TypeScript code, run `npm run typecheck`.
+- Add or update focused tests when changing billing calculations, request
+  mapping, error handling, or checkout behavior.
+- Do not modify generated Payload files or migrations unless the requested
+  change requires a schema or database change.

docs/checkout-testing.md

@@ -0,0 +1,38 @@
+# Checkout testing
+
+Run the automated checkout suite first:
+
+```sh
+npm run test:checkout
+```
+
+The automated suite covers B2C and B2B customer payloads, required contact and tax fields, incomplete and complete Stripe billing addresses, successful and failed confirmation results, discount session replacement, return identifiers, component remounts, and API error rendering.
+
+## Stripe sandbox verification
+
+Use only Stripe sandbox keys and synthetic test data. Start the application with a sandbox Crater instance and complete each scenario through the real Stripe Elements UI.
+
+For every scenario, verify that the browser returns to the localized `/checkout/success?session_id=cs_...` URL, the success page accepts the return identifier, and access is not granted until Crater processes the verified Stripe webhook.
+
+| Scenario | Test data and expected result |
+| --- | --- |
+| B2C card | Use card `4242 4242 4242 4242`, any future expiry, any CVC, and a complete billing address. Confirmation succeeds and returns to the success page. |
+| B2B card | Enter company contact data and a sandbox-valid tax ID, then use card `4242 4242 4242 4242`. The Customer and resulting subscription retain the business customer type. |
+| Incomplete address | Leave a required Stripe address field empty. The Payment Element and Payment step remain unavailable. |
+| Completed address | Complete all required address fields. The Payment Element appears and the stepper advances to Payment. |
+| 3D Secure | Use card `4000 0000 0000 3220`, complete the sandbox authentication challenge, and verify the return to the success page. Repeat once by failing the challenge and verify that no success or entitlement is produced. |
+| Redirect method | Enable a redirect-based sandbox payment method such as iDEAL for the Stripe account, authorize it on Stripe's test page, and verify the return URL. Repeat its failure path. |
+| Discount | Apply the configured sandbox promotion code before payment. Change and remove it after Elements loads and verify that a new Checkout Session is mounted with the updated total each time. |
+| Reload | Reload before confirmation. The local form safely restarts and does not display an unverified success state. |
+| Decline | Use card `4000 0000 0000 9995` and verify that Stripe's error is shown without advancing to success. |
+
+Finally, verify in Stripe and Crater that the completed Checkout Session, webhook event, subscription projection, and license state all reference the same customer and checkout configuration.
+# Guest checkout isolation
+
+The login choice is always displayed, including for signed-in self-hosted buyers. Guest creation never replaces the account session. Each purchase gets a random `guestCheckout` URL identifier and its own encrypted HttpOnly browser-session cookie. The identifier is not a credential. The existing `PAYLOAD_SECRET` seals the cookie; it must be configured and consistent across application instances.
+
+Guest checkout access has an absolute 24-hour deadline, even if the browser restores session cookies. Requests select the purchase explicitly, so account pages and other tabs retain their own identity. Missing or expired guest credentials never fall back to account credentials. Guest form drafts use sessionStorage, and contain no credentials.
+
+On Crater's verified `READY` response, the cookie loses its profile claim and checkout permissions. For at most another 30 minutes (bounded by the original deadline), it permits only the purchase confirmation and download of the returned license. Reloading does not extend this deadline. A `FAILED` checkout clears the guest cookie; expired cookies are cleared on the next request. Starting another guest purchase also removes expired or unreadable guest cookies and keeps at most five purchases per browser, dropping the oldest, so repeated attempts cannot overflow the Cookie header. No guest is automatically linked to the signed-in account, and the guest confirmation does not link to that account's license dashboard. Profile claiming/account linking remains a separate explicit flow.
+
+Manual checks: keep an account dashboard open, purchase as a guest in another tab, reload checkout, complete a redirect-based payment, download the license, and verify that the original dashboard still uses the account. Repeat with two guest purchases in separate tabs and with an expired guest cookie.