Initial working state: CL3.5 complete (Plesk sync + suspend/unsuspend)

README.md

@@ -0,0 +1,99 @@
+# Plesk Agency Management Portal (MVP)
+
+Next.js + Tailwind + Supabase + Stripe multi-tenant SaaS starter for agencies managing one or more Plesk instances.
+
+## Included MVP Features
+
+- Supabase Postgres schema + RLS (`supabase/schema.sql`)
+- Supabase Auth (magic-link login)
+- Agency tenancy context (`agency_members` based)
+- Dashboard with:
+  - Plesk instance connect + validation
+  - Plesk sync (subscriptions + domains)
+  - Subscription suspend / unsuspend actions
+  - Stripe checkout + billing portal launch
+- Stripe webhook endpoint to sync billing state
+
+## 1) Setup
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Create local env:
+
+```bash
+cp .env.example .env.local
+```
+
+3. Fill `.env.local` with your Supabase + Stripe values.
+
+4. In Supabase SQL Editor, run:
+
+```sql
+-- contents of supabase/schema.sql
+```
+
+5. In Supabase Auth settings, set site URL and redirect URL(s), e.g.:
+
+- `http://localhost:3000`
+- `http://localhost:3000/dashboard`
+
+6. Run dev server:
+
+```bash
+npm run dev
+```
+
+## 2) Seed Minimum Data
+
+After first login user is created in `auth.users`, then add membership rows (via SQL) so tenant context resolves:
+
+```sql
+insert into agencies (name) values ('My Agency') returning id;
+
+-- replace values
+insert into agency_members (agency_id, user_id, role)
+values ('<agency_uuid>', '<auth_user_uuid>', 'owner');
+```
+
+## 3) API Endpoints
+
+- `POST /api/plesk/instances` — create + validate Plesk connection
+- `POST /api/plesk/instances/:id/sync` — pull/sync subscriptions + domains from one Plesk instance
+- `POST /api/jobs/plesk-sync-all` — background sync job for all connected instances (requires `X-JOB-SECRET`)
+- `POST /api/plesk/subscriptions/:id/action` — suspend or unsuspend
+- `POST /api/stripe/checkout` — create Stripe Checkout session
+- `POST /api/stripe/portal` — create Stripe Customer Portal session
+- `POST /api/stripe/webhook` — Stripe webhook receiver
+
+## 4) Important Notes
+
+- Set a strong `ENCRYPTION_KEY`; it encrypts stored Plesk auth secrets.
+- Set a strong `PLESK_CRED_ENC_KEY` (32-byte base64 or 64-char hex) for Plesk credential encryption.
+- Set `JOB_SECRET` for internal cron-triggered job auth.
+- `/api/stripe/webhook` is excluded from auth middleware for Stripe signature verification.
+- Current implementation is intentionally MVP-focused; add stronger validation, retries, idempotency keys, and richer error observability for production.
+
+## 5) Automatic Plesk Auto-Sync (CL3.5)
+
+Background auto-sync endpoint:
+
+```bash
+curl -sS -X POST http://localhost:3000/api/jobs/plesk-sync-all \
+  -H "X-JOB-SECRET: <JOB_SECRET>"
+```
+
+Recommended cron (every 5 minutes):
+
+```cron
+*/5 * * * * curl -sS -X POST http://localhost:3000/api/jobs/plesk-sync-all -H "X-JOB-SECRET: ${JOB_SECRET}"
+```
+
+Notes:
+
+- Job uses DB lock (`job_locks`) to avoid overlapping runs.
+- Job processes at most 10 connected instances per run.
+- Instances synced in the last 3 minutes are skipped.