@relipay/node 0.1.0-beta.0

package/AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md — @relipay/node
+
+You are an AI agent looking at `@relipay/node`. This file tells you how to use it correctly on the first try.
+
+## When to use this package
+
+The user wants to add **auth, billing, or both** to a server-side TypeScript project (Express, Fastify, Nest, Hono, raw Node, Bun, Deno). Strong signals:
+
+- They asked to add login / signup / sessions, and the project doesn't already have a working auth solution.
+- They asked to add Stripe / PayPal / subscriptions / checkout / a billing flow.
+- They say "Clerk", "Auth0", "Supabase Auth", "Stripe Checkout" — and they want a self-hostable alternative.
+- They have a hand-rolled `users` table, `password_hash` column, and bespoke session middleware. ReliPay replaces this.
+
+**Do NOT use this package** when:
+
+- They want auth in the *browser*. Reach for `@relipay/react` (or `@relipay/nextjs`) instead — never call ReliPay with a secret key from browser code.
+- They're building the ReliPay server itself. This SDK calls ReliPay; it's not the implementation.
+
+## Five-line happy path
+
+```ts
+import { ReliPay } from '@relipay/node';
+
+const relipay = new ReliPay({
+  apiUrl: process.env.RELIPAY_URL!,
+  secretKey: process.env.RELIPAY_SECRET!, // rp_live_… or rp_test_…
+});
+
+// Smoke test: verifies the credentials and returns the Application DTO.
+const me = await relipay.applications.me();
+```
+
+That's it for setup. Everything else hangs off `relipay.applications.*`, `relipay.auth.*`, and `relipay.billing.*`.
+
+`applications.me()` is the canonical "did my setup work?" call — if it throws `RelipayError` with `code: "API_KEY_INVALID"`, the secret key is wrong/revoked/expired. If it throws with `code: "CONFIG_INVALID_SECRET_KEY"`, the constructor caught a bad `secretKey` arg before any network call.
+
+## Required env vars
+
+| Name | Example | Where to get it |
+|---|---|---|
+| `RELIPAY_URL` | `https://relipay.example.com` or `http://localhost:3030` | Their ReliPay deployment |
+| `RELIPAY_SECRET` | `rp_live_abc123…` | Panel → Application → API Keys |
+| `RELIPAY_PUBLIC` | `rp_pub_myapp_xyz…` | Panel → Application (browser-safe; only needed if also using `@relipay/react`) |
+
+Never hardcode any of these. Always read from `process.env`.
+
+## What you should always do
+
+1. **One client per Application.** Don't construct `new ReliPay()` per request — make it a module-level singleton.
+2. **Catch `RelipayError`** and surface `error.fix` to the user when debugging. The `fix` field is the single most useful piece of information.
+3. **Never log `secretKey`.** Treat it like a database password.
+4. **Use the typed methods.** Don't call `.request()` directly — that's the escape hatch, not the API.
+
+## What you should never do
+
+- Don't `npm install stripe` or `@paypal/checkout-server-sdk` alongside `@relipay/node`. ReliPay handles provider integration; calling provider SDKs in parallel will desync your data.
+- Don't store user passwords in your own DB. ReliPay's API owns the password hash.
+- Don't write your own session middleware. Use `relipay.auth.verifySession(token)` (lands in Phase 1).
+- Don't proxy ReliPay calls through your frontend with the secret key. Browser → your backend → ReliPay.
+
+## Errors that teach
+
+Every error from this SDK is a `RelipayError` with `code`, `message`, `fix`, and optionally `docs`. Examples:
+
+```
+code: PLAN_NOT_FOUND
+message: Plan "pro_monthly" not found in application "myapp-prod".
+fix: Run `relipay plans list` to see available plans, or create one in the panel.
+docs: https://relipay.dev/errors/PLAN_NOT_FOUND
+```
+
+When the user reports an error, **read `error.fix` first** — it tells you what to do. Don't guess.
+
+## Status
+
+Phase 1.1 — end-user auth works end-to-end. Public surface today:
+
+| Method | Status |
+|---|---|
+| `relipay.applications.me()` | ✅ Working |
+| `relipay.auth.signUp({ email, password, metadata? })` | ✅ Working — returns `{ accessToken, refreshToken, ... }` |
+| `relipay.auth.signIn({ email, password })` | ✅ Working — returns `{ accessToken, refreshToken, ... }` |
+| `relipay.auth.refresh(refreshToken)` | ✅ Working — single-use, returns new pair |
+| `relipay.auth.signOut(refreshToken)` | ✅ Working — idempotent |
+| `relipay.auth.signOutEverywhere(accessToken)` | ✅ Working — revokes all refresh tokens for the user |
+| `relipay.auth.getCurrentUser(accessToken)` | ✅ Working |
+| `relipay.auth.requestPasswordReset({ email })` | ✅ Working — never enumerates; **you email** the returned `resetToken` |
+| `relipay.auth.resetPassword({ token, newPassword })` | ✅ Working — single-use, kills all sessions on success |
+| `relipay.auth.changePassword(accessToken, { currentPassword, newPassword })` | ✅ Working — kills other sessions |
+| `relipay.billing.getPlans()` | ✅ Working |
+| `relipay.billing.getSubscription(accessToken)` | ✅ Working — returns `null` when none |
+| `relipay.billing.createCheckout(accessToken, { planSlug, successUrl, cancelUrl, couponCode? })` | ⚠️ Stub provider for outbound URL — webhook handling is real. Returns a real local PENDING Subscription + deterministic stub URL + `discountAmount`. |
+| `relipay.billing.validateCoupon(accessToken, { code, planSlug })` | ✅ Working — surfaces precise `COUPON_*` errors. |
+
+Don't invent imports for methods that don't exist. If you can't find a method via TypeScript autocomplete on `relipay.applications.`, `relipay.auth.`, or `relipay.billing.`, it isn't there yet.
+
+## Two-credential model (read this once)
+
+Per-user calls require **two** credentials together:
+
+1. The **Application secret key** (`rp_live_…`) — proves *which Application* is calling. Goes in `Authorization: Bearer …` automatically; you set it once at construction.
+2. The **user JWT** — proves *which end-user* this call is acting on behalf of. Returned from `signUp` / `signIn`. You pass it as the argument to `getCurrentUser(token)`; the SDK puts it in `X-Relipay-User-Token`.
+
+The server enforces a **cross-application guard**: if a JWT was issued by Application A, presenting it through Application B's secret key returns `USER_TOKEN_WRONG_APPLICATION` (401). This is by design. Don't try to "share users across apps" by re-signing tokens — those are deliberately different users.
+
+See [`docs/auth.md`](../../docs/auth.md) for the full flow diagram.

package/README.md

@@ -0,0 +1,49 @@
+# @relipay/node
+
+Server SDK for [ReliPay](https://relipay.dev) — auth + billing for your application.
+
+> **For AI coding agents:** start at [AGENTS.md](./AGENTS.md).
+
+## Install
+
+```bash
+pnpm add @relipay/node
+```
+
+## Use
+
+```ts
+import { ReliPay } from '@relipay/node';
+
+const relipay = new ReliPay({
+  apiUrl: process.env.RELIPAY_URL!,
+  secretKey: process.env.RELIPAY_SECRET!,
+});
+
+const user = await relipay.auth.getUser(userId);
+```
+
+## Errors
+
+Every error is a `RelipayError` with `code`, `message`, `fix`, and `docs`:
+
+```ts
+import { RelipayError } from '@relipay/node';
+
+try {
+  await relipay.billing.checkout({ /* ... */ });
+} catch (err) {
+  if (err instanceof RelipayError) {
+    console.error(err.code, err.fix); // ← read err.fix first
+  }
+  throw err;
+}
+```
+
+## Status
+
+Phase 0. Auth surface stubbed; billing methods land in Phase 1.
+
+## License
+
+MIT.