elevenlabs-webhook-nodejs 1.0.0

package/docs/AUTH_API.md

@@ -0,0 +1,252 @@
+# Auth API
+
+Base URL: `/auth`
+
+## Token Flow
+
+1. **Register** or **Login** returns an `access_token` (15min) and `refresh_token` (7d).
+2. Use `access_token` in the `Authorization: Bearer <token>` header for protected routes.
+3. When the access token expires, call **Refresh** with the `refresh_token` to get a new pair.
+4. Old refresh tokens are revoked on each refresh (rotation).
+5. Refresh tokens are stored in MongoDB with a TTL index and auto-expire after 7 days.
+
+### Access Token Payload
+
+```json
+{
+  "id": "user_id",
+  "tenant_id": "tenant_id",
+  "role": "admin",
+  "enabled_features": ["inbound_agent", "whatsapp_notifications"]
+}
+```
+
+### Refresh Token Payload
+
+```json
+{
+  "id": "user_id",
+  "type": "refresh"
+}
+```
+
+---
+
+## Endpoints
+
+### POST /auth/register
+
+Creates a new tenant and the first admin user.
+
+**Auth:** None
+
+**Request Body:**
+
+```json
+{
+  "email": "user@example.com",
+  "password": "min8chars",
+  "name": "John Doe",
+  "tenant_name": "Acme Corp"
+}
+```
+
+**201 Created:**
+
+```json
+{
+  "user": {
+    "id": "664f1a...",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "admin"
+  },
+  "tenant": {
+    "id": "664f1a...",
+    "name": "Acme Corp",
+    "plan": "free",
+    "enabled_features": ["inbound_agent", "whatsapp_notifications"]
+  },
+  "access_token": "eyJhbGciOi...",
+  "refresh_token": "eyJhbGciOi..."
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing required fields |
+| 400 | Password shorter than 8 characters |
+| 409 | Email already registered |
+
+---
+
+### POST /auth/login
+
+Authenticates a user and returns a new token pair.
+
+**Auth:** None
+
+**Request Body:**
+
+```json
+{
+  "email": "user@example.com",
+  "password": "min8chars"
+}
+```
+
+**200 OK:**
+
+```json
+{
+  "user": {
+    "id": "664f1a...",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "admin"
+  },
+  "tenant": {
+    "id": "664f1a...",
+    "name": "Acme Corp",
+    "plan": "free",
+    "enabled_features": ["inbound_agent", "whatsapp_notifications"]
+  },
+  "access_token": "eyJhbGciOi...",
+  "refresh_token": "eyJhbGciOi..."
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing email or password |
+| 401 | Invalid email or password |
+
+---
+
+### POST /auth/refresh
+
+Exchanges a valid refresh token for a new access + refresh token pair. The old refresh token is revoked (rotation).
+
+**Auth:** None
+
+**Request Body:**
+
+```json
+{
+  "refresh_token": "eyJhbGciOi..."
+}
+```
+
+**200 OK:**
+
+```json
+{
+  "access_token": "eyJhbGciOi...",
+  "refresh_token": "eyJhbGciOi..."
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing refresh_token |
+| 401 | Invalid, expired, or already-revoked refresh token |
+| 401 | User no longer exists |
+
+---
+
+### POST /auth/logout
+
+Revokes refresh tokens. If `refresh_token` is provided in the body, only that token is revoked. Otherwise, all refresh tokens for the authenticated user are revoked.
+
+**Auth:** `Authorization: Bearer <access_token>`
+
+**Request Body (optional):**
+
+```json
+{
+  "refresh_token": "eyJhbGciOi..."
+}
+```
+
+**200 OK:**
+
+```json
+{
+  "success": true
+}
+```
+
+| Behavior | Body |
+|----------|------|
+| Revoke single token | `{ "refresh_token": "..." }` |
+| Revoke all user tokens | `{}` or omit body |
+
+---
+
+### GET /auth/me
+
+Returns the current user's profile and tenant information.
+
+**Auth:** `Authorization: Bearer <access_token>`
+
+**200 OK:**
+
+```json
+{
+  "user": {
+    "id": "664f1a...",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "role": "admin"
+  },
+  "tenant": {
+    "id": "664f1a...",
+    "name": "Acme Corp",
+    "plan": "free",
+    "enabled_features": ["inbound_agent", "whatsapp_notifications"],
+    "settings": {
+      "kvkk_consent": false,
+      "notification_recipients": [],
+      "default_language": "tr"
+    }
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 401 | Missing or invalid access token |
+| 404 | User or tenant not found |
+
+---
+
+## RBAC Middleware
+
+Available for use on any protected route:
+
+- **`requireRole(...roles)`** - Restricts access by user role. Roles: `superadmin`, `admin`, `manager`, `viewer`.
+- **`requireFeature(...features)`** - Restricts access by tenant features. Features: `inbound_agent`, `outbound_campaigns`, `survey_builder`, `whatsapp_notifications`.
+
+```
+403 { "error": "Insufficient role" }
+403 { "error": "Feature not available on your plan" }
+```
+
+---
+
+## Configuration
+
+| Env Variable | Default | Description |
+|---|---|---|
+| `JWT_SECRET` | - | Access token signing secret |
+| `JWT_REFRESH_SECRET` | - | Refresh token signing secret |
+| `JWT_ACCESS_EXPIRY` | `15m` | Access token TTL |
+| `JWT_REFRESH_EXPIRY` | `7d` | Refresh token TTL |

package/docs/BILLING_SMS_ALERTS.md

@@ -0,0 +1,94 @@
+# Billing SMS Alerts
+
+## Overview
+
+The system sends SMS notifications to tenants when their usage approaches quota limits or their billing period is about to expire. Alerts are sent via NetGSM SMS service.
+
+## Prerequisites
+
+- Tenant must have `sms_notifications` in `enabled_features`
+- `settings.whatsapp_agent.sms_notification_enabled` must be `true`
+- `settings.whatsapp_agent.sms_notification_phones[]` must have at least one phone number
+- Tenant must have an active subscription payment (`period_start <= now <= period_end`)
+
+## Alert Types
+
+### Usage Threshold Alerts
+
+Triggered when any service quota reaches 75%, 90%, or 100%. Only the highest crossed threshold fires per service per billing period.
+
+| Threshold | Message |
+|-----------|---------|
+| 75% | `[Asistan7/24] Kullaniminiz %75'e ulasti. Detaylar icin panele bakin.` |
+| 90% | `[Asistan7/24] Kullaniminiz %90'a ulasti. Detaylar icin panele bakin.` |
+| 100% | `[Asistan7/24] Kullaniminiz %100'e ulasti. Detaylar icin panele bakin.` |
+
+Monitored services (only if quota > 0 on plan):
+- **Inbound call minutes**: `inbound_used_minutes` vs `included_inbound_minutes`
+- **Inbound call count**: `inbound_used_calls` vs `included_inbound_calls`
+- **WhatsApp chats**: `wa_used_chats` vs `included_wa_chats` (unique chats where AI responded)
+
+### Period Expiry Alert
+
+Triggered when the billing period ends within 3 days AND no future payment exists.
+
+| Condition | Message |
+|-----------|---------|
+| <= 3 days left, no renewal | `[Asistan7/24] Fatura doneminiz 3 gun icinde sona erecek. Detaylar icin panele bakin.` |
+
+## Schedule
+
+Runs daily at **09:00 Europe/Istanbul** via scheduled timeout in `src/index.ts`.
+
+## Deduplication
+
+Each alert is recorded in the `BillingAlert` collection with a unique index on `(tenant_id, alert_type, service, payment_id)`. The same alert will never be sent twice for the same billing period.
+
+### BillingAlert Schema
+
+```typescript
+{
+  tenant_id: ObjectId,
+  alert_type: 'usage_75' | 'usage_90' | 'usage_100' | 'period_expiring',
+  service: 'inbound_minutes' | 'inbound_calls' | 'wa_chats' | 'billing_period',
+  payment_id: ObjectId,
+  createdAt: Date,
+}
+```
+
+## Billable WhatsApp Chat Definition
+
+A chat is "billable" only if the AI responded at least once (`sender_name === 'AI'`) during the billing period. Chats where only the patient messaged (no AI response) are not counted.
+
+## How Usage Period is Resolved
+
+1. Find active subscription: `Payment` where `period_start <= now <= period_end`
+2. If none: use most recent payment's `period_end` as start, `now` as end
+3. If no payments: use `tenant.createdAt` as start, `now` as end
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/modules/billing/billing-alert.model.ts` | Deduplication model |
+| `src/modules/billing/billing.service.ts` | `checkAndSendBillingAlerts()` + `getUsageSummary()` |
+| `src/services/netgsm.service.ts` | SMS sending via NetGSM API |
+| `src/index.ts` | Daily 09:00 Istanbul scheduler |
+
+## Configuration
+
+### Environment Variables
+
+```
+NETGSM_USERNAME=...
+NETGSM_PASSWORD=...
+NETGSM_MSGHEADER=...
+```
+
+### Per-Tenant Settings (Admin Panel)
+
+- Enable `sms_notifications` feature flag
+- Set `sms_notification_enabled: true`
+- Add phone numbers to `sms_notification_phones[]`
+- Assign a plan with quotas (`included_inbound_minutes`, `included_wa_chats`, etc.)
+- Create a subscription payment with `period_start` and `period_end`

package/docs/CHAT_ASSIGNMENT_SYSTEM.md

@@ -0,0 +1,118 @@
+# Chat Assignment System
+
+## Overview
+
+Chat assignment allows managers to distribute incoming conversations to specific staff members (sales reps, receptionists). Assignment is **chat-level** — it persists across sessions, so when a patient messages again weeks later, the same rep sees it in their inbox.
+
+## Permission Model
+
+| Permission | Roles | Effect |
+|---|---|---|
+| `chats:read` | Owner, Admin, Receptionist | See ALL chats |
+| `chats:read_own` | Sales, (+ custom) | See only chats assigned to you |
+| `chats:assign` | Owner, Admin | Assign/unassign chats to users |
+| `chats:takeover` | Owner, Admin, Receptionist | Take over from AI |
+| `chats:send` | Sales, Owner, Admin, Receptionist | Send messages |
+| `chats:resolve` | Owner, Admin, Receptionist | Close sessions |
+
+Custom permissions can be added per-user via the Users page permissions grid.
+
+## Database Schema
+
+Assignment lives on `WhatsappChat` (not session):
+
+```
+WhatsappChat {
+  chat_assigned_to_id   String?   // FK → User (who handles this chat)
+  chat_assigned_by_id   String?   // FK → User (who made the assignment)
+  chat_assigned_at      DateTime? // when the assignment was made
+}
+```
+
+Why chat-level, not session-level:
+- Sessions are temporary (resolve after conversation ends)
+- A new session starts when the patient messages again
+- Chat-level assignment means "this contact belongs to you" permanently
+- Manager can reassign or unassign at any time
+
+## API Endpoints
+
+### Assign Chat
+```
+POST /whatsapp/chats/:id/assign
+Permission: chats:assign
+Body: { "userId": "target-user-id" }
+```
+
+### Unassign Chat
+```
+POST /whatsapp/chats/:id/unassign
+Permission: chats:assign
+```
+
+### List Chats (with assignment filter)
+```
+GET /whatsapp/chats?assignedTo=userId&status=active&q=search
+```
+
+When a user has `chats:read_own` but NOT `chats:read`, the controller forces `assignedTo = currentUser.id`. They cannot override this filter.
+
+## Events
+
+| Event | Payload | When |
+|---|---|---|
+| `chat:assigned` | `{ tenantId, chatId, assignedToId, assignedById }` | Chat assigned to user |
+| `chat:unassigned` | `{ tenantId, chatId }` | Assignment removed |
+
+## User Flow
+
+### Manager assigns a chat:
+1. Opens inbox → sees all chats (has `chats:read`)
+2. Clicks a chat → sees conversation with patient
+3. Selects "Ahmet" from the assign dropdown in the header
+4. Chat is now assigned to Ahmet
+
+### Sales rep handles assigned chat:
+1. Logs in → sees only their assigned chats (has `chats:read_own`)
+2. Opens the assigned chat → reads AI conversation history
+3. Clicks "Take Over" → AI stops, rep types directly
+4. Handles the patient, clicks "Release" (AI resumes) or "Resolve" (session ends)
+
+### Patient messages again (days/weeks later):
+1. New session starts automatically, AI handles it
+2. Chat still assigned to Ahmet → appears in his inbox
+3. Ahmet can take over again, or manager can reassign
+
+### Unassign:
+1. Manager selects "Unassigned" from dropdown
+2. Chat goes back to general pool — visible to all managers
+3. Sales rep no longer sees it
+
+## Frontend UI
+
+### Inbox Layout
+- **Left sidebar** (320px): Searchable chat list with status filter (All/Active/Waiting)
+- **Right panel**: Message view with bubbles + action buttons
+
+### Chat List Item Shows:
+- Contact name (or patient display name)
+- Last message preview + time ago
+- Session status badge: AI / Human / Waiting
+- Assignee name badge (if assigned)
+- Channel indicator (IG badge for Instagram)
+
+### Chat View Header Actions:
+- **Assign dropdown** — always visible, select staff user or "Unassigned"
+- **Take Over** — visible when AI is active (requires `chats:takeover`)
+- **Release** — visible when human has taken over
+- **Resolve** — visible when session is active
+
+### Message Bubbles:
+- **Contact** (gray, left-aligned)
+- **AI** (blue outline, right-aligned, with Bot icon)
+- **Human** (primary color, right-aligned, with sender name)
+
+### Auto-refresh:
+- Chat list polls every 10 seconds
+- Messages poll every 5 seconds
+- (Socket.IO real-time updates planned for future)