Update AGENTS.md

docs/ai/api.md

@@ -0,0 +1,235 @@
+# API Documentation
+
+Only read this file when modifying API routes, authentication, keys, or integrations.
+
+---
+
+# API Location
+
+API routes:
+
+src/routes/api/v1/
+
+---
+
+# Authentication
+
+Most API endpoints require:
+
+Authorization: Bearer <API key>
+
+API keys are:
+
+- generated randomly
+- hashed with SHA-256 before storage
+- displayed using stored prefix only
+
+Never store plaintext API keys.
+
+---
+
+# API Key Lifecycle
+
+Normal rotation:
+
+- New key generated.
+- Old key remains valid for 48 hours.
+- Old key expires using expiresAt.
+
+Emergency rotation:
+
+- Old key immediately invalidated.
+- revokedAt is set.
+
+---
+
+# API Routes
+
+## Categories
+
+GET:
+
+/api/v1/categories
+
+Requires API key.
+
+---
+
+## Frequencies
+
+GET:
+
+/api/v1/frequencies
+
+Requires API key.
+
+---
+
+## Proclamations
+
+GET:
+
+/api/v1/proclamations
+
+Supports:
+
+- optional key filtering
+- optional email filtering
+
+Requires API key.
+
+---
+
+## License Validation
+
+POST:
+
+/api/v1/license
+
+Payload:
+
+{
+	"license_key": "...",
+	"email_address": "..."
+}
+
+Requires API key.
+
+---
+
+# GHL Account Creation Webhook
+
+Endpoint:
+
+POST /api/v1/automations/create/account
+
+This endpoint does NOT require an API key.
+
+It is used by GoHighLevel automation.
+
+---
+
+# Account Creation Flow
+
+When a request arrives:
+
+1. Check whether the email already exists.
+
+If user does not exist:
+
+2. Create user through Better Auth.
+3. Generate temporary password.
+4. Retrieve verification token.
+5. Build verification URL.
+6. Send registration email.
+
+Then:
+
+7. Create LicenseKey.
+8. Send license key delivery email.
+
+If user already exists:
+
+1. Skip signup.
+2. Create license key.
+3. Send delivery email.
+
+---
+
+# Email Templates
+
+Controlled by:
+
+src/lib/server/resend.ts
+
+Templates:
+
+automated-user-registration
+
+Variables:
+
+- firstName
+- tempPassword
+- verifyUrl
+- loginUrl
+
+
+license-key-delivery
+
+Variables:
+
+- firstName
+- license_key
+
+
+email-verification-email
+
+Variables:
+
+- target_email_address
+- verification_link
+
+---
+
+# Better Auth
+
+Server:
+
+src/lib/auth.ts
+
+Client:
+
+src/lib/auth-client.ts
+
+Email callbacks:
+
+- sendVerificationEmail
+- sendResetPassword
+
+Failures should:
+
+- log errors
+- not crash requests
+
+Use:
+
+void promise.catch()
+
+pattern.
+
+---
+
+# Security Rules
+
+Never:
+
+- expose plaintext API keys
+- bypass authorization checks
+- trust client role information
+- skip validation
+
+Always:
+
+- validate input
+- check permissions
+- preserve existing security patterns
+
+---
+
+# API Change Workflow
+
+Before modifying an endpoint:
+
+1. Read the route.
+2. Read related auth middleware.
+3. Read database models involved.
+4. Check existing tests.
+
+After modifying:
+
+Run:
+
+npm run check
+npm run test
+
+Fix failures before completing.