@iqauth/sdk 2.0.0

package/docs/guides/error-handling.md

@@ -0,0 +1,251 @@
+# Error Handling
+
+## Purpose
+
+Handle all SDK errors using `IQAuthError` and `ErrorCodes`. Understand error codes, HTTP status mapping, and implement recovery patterns.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+
+## Environment Note
+
+Refresh-and-retry examples in this guide apply to token-owning runtimes such as servers and native mobile apps with secure storage.
+
+For first-party browser apps, the backend should own refresh and session recovery.
+
+## SDK Methods
+
+| Export | Description |
+|--------|-------------|
+| `IQAuthError` | Error class thrown by all SDK API calls |
+| `ErrorCodes` | Constant object with all error code strings |
+| `ErrorCode` | TypeScript type for error code values |
+
+### IQAuthError Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `code` | `string` | Machine-readable error code |
+| `message` | `string` | Human-readable description |
+| `status` | `number \| undefined` | HTTP status code |
+| `raw` | `unknown` | Full raw response body |
+| `name` | `string` | Always `"IQAuthError"` |
+
+## Step-by-Step
+
+### 1. Basic Error Handling
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.auth.login(email, password);
+} catch (err) {
+  if (err instanceof IQAuthError) {
+    console.error(`[${err.code}] ${err.message} (HTTP ${err.status})`);
+  }
+}
+```
+
+### 2. Switch on Error Codes
+
+```typescript
+try {
+  await client.auth.login(email, password);
+} catch (err) {
+  if (err instanceof IQAuthError) {
+    switch (err.code) {
+      case ErrorCodes.INVALID_CREDENTIALS:
+        showError("Wrong email or password");
+        break;
+      case ErrorCodes.ACCOUNT_LOCKED:
+        showError("Account locked — try again later");
+        break;
+      case ErrorCodes.ACCOUNT_INACTIVE:
+        showError("Account deactivated");
+        break;
+      case ErrorCodes.PASSWORD_EXPIRED:
+        redirectToPasswordChange();
+        break;
+      default:
+        showError("An error occurred");
+    }
+  }
+}
+```
+
+### 3. Token Error Recovery
+
+```typescript
+try {
+  await client.users.getCurrent();
+} catch (err) {
+  if (err instanceof IQAuthError) {
+    if (err.code === ErrorCodes.TOKEN_EXPIRED) {
+      const newTokens = await client.auth.refreshTokens(client.getRefreshToken()!);
+      client.setTokens(newTokens);
+      return client.users.getCurrent(); // Retry
+    }
+    if (err.code === ErrorCodes.REFRESH_TOKEN_REUSED) {
+      // Security: possible token theft — force re-login
+      forceReLogin();
+    }
+  }
+}
+```
+
+## Error Handling
+
+All SDK API calls throw `IQAuthError` on failure. The error object carries a machine-readable `code`, human-readable `message`, HTTP `status`, and the `raw` response body. Use `ErrorCodes` constants for reliable comparisons.
+
+## Error Codes Reference
+
+### Authentication
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `INVALID_CREDENTIALS` | 401 | Wrong email or password |
+| `ACCOUNT_INACTIVE` | 403 | User account is deactivated |
+| `ACCOUNT_LOCKED` | 403 | Account locked (too many failed attempts) |
+| `AUTH_REQUIRED` | 401 | No authentication provided |
+| `PASSWORD_EXPIRED` | 403 | Password must be changed |
+| `PASSWORD_POLICY_VIOLATION` | 400 | New password doesn't meet policy |
+
+### Tokens
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `TOKEN_INVALID` | 401 | Malformed or fails verification |
+| `TOKEN_EXPIRED` | 401 | `exp` claim is in the past |
+| `TOKEN_REVOKED` | 401 | Token revoked server-side |
+| `REFRESH_TOKEN_REUSED` | 401 | Refresh token reuse (possible theft) |
+
+### Sessions
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `SESSION_INVALID` | 401 | Session does not exist |
+| `SESSION_EXPIRED` | 401 | Session has expired |
+
+### MFA
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `MFA_INVALID_CODE` | 401 | Wrong MFA code |
+| `MFA_METHOD_UNAVAILABLE` | 400 | Method not available |
+| `MFA_RATE_LIMITED` | 429 | Too many attempts |
+| `MFA_ENROLLMENT_REQUIRED` | 403 | MFA must be enrolled |
+
+### Authorization
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `INSUFFICIENT_PERMISSIONS` | 403 | Lacks required role/entitlement |
+| `FORBIDDEN` | 403 | Action not allowed |
+| `USER_INACTIVE` | 403 | User inactive in tenant |
+
+### API Keys
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `API_KEY_REQUIRED` | 401 | Endpoint requires API key |
+| `API_KEY_INVALID` | 401 | Invalid or expired API key |
+
+### Resources
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `NOT_FOUND` | 404 | Resource doesn't exist |
+| `ALREADY_EXISTS` | 409 | Duplicate identifier |
+| `VALIDATION_ERROR` | 400 | Failed request validation |
+
+### PIN
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `PIN_EXPIRED` | 401 | PIN has expired |
+
+### Invitations
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `INVALID_CODE` | 400 | Invalid invite code |
+| `CODE_ALREADY_USED` | 400 | Code already accepted |
+| `CODE_EXPIRED` | 400 | Code has expired |
+| `CODE_IP_MISMATCH` | 403 | IP mismatch |
+
+### External Services
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `OAUTH_NOT_CONFIGURED` | 500 | OAuth not configured |
+| `EMAIL_SERVICE_UNAVAILABLE` | 503 | Email service down |
+| `UPLOAD_ERROR` | 500 | Upload failed |
+
+### Other
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `INTERNAL_ERROR` | 500 | Server-side error |
+| `UNKNOWN_PAYLOAD` | 500 | Unexpected response |
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: storedToken,
+  refreshToken: storedRefreshToken,
+});
+
+async function safeApiCall<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (!(err instanceof IQAuthError)) throw err;
+
+    switch (err.code) {
+      case ErrorCodes.TOKEN_EXPIRED: {
+        const refreshToken = client.getRefreshToken();
+        if (!refreshToken) throw new Error("Session expired — please log in again");
+        const newTokens = await client.auth.refreshTokens(refreshToken);
+        client.setTokens(newTokens);
+        return fn(); // Retry
+      }
+
+      case ErrorCodes.REFRESH_TOKEN_REUSED:
+        throw new Error("Session compromised — log in again");
+
+      case ErrorCodes.INSUFFICIENT_PERMISSIONS:
+        throw new Error("You don't have permission for this action");
+
+      case ErrorCodes.NOT_FOUND:
+        throw new Error("The requested resource was not found");
+
+      default:
+        throw err;
+    }
+  }
+}
+
+// Usage
+const user = await safeApiCall(() => client.users.getCurrent());
+```
+
+## HTTP Response Envelope
+
+The server wraps all responses:
+
+```json
+// Success
+{ "success": true, "data": { ... } }
+
+// Error
+{ "success": false, "error": { "code": "...", "message": "..." } }
+```
+
+The SDK automatically unwraps success responses and throws `IQAuthError` for errors.

package/docs/guides/gdpr-compliance.md

@@ -0,0 +1,123 @@
+# GDPR Compliance
+
+## Purpose
+
+Implement GDPR data subject rights: personal data export (right of access) and account deletion (right to erasure).
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- Authenticated user (access token set on client)
+
+## Environment Note
+
+This guide's token examples assume a trusted runtime or secure mobile storage, not browser-local token ownership for first-party web apps.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `gdpr` | `exportData()` | Export all personal data → `GdprExportData` |
+| `gdpr` | `deleteAccount(confirmEmail)` | Permanently delete account |
+
+## Step-by-Step
+
+### 1. Export Personal Data
+
+```typescript
+const exportData = await client.gdpr.exportData();
+```
+
+Returns `GdprExportData`:
+
+```typescript
+interface GdprExportData {
+  exportedAt: string;
+  user: Record<string, unknown>;
+  memberships: Record<string, unknown>[];
+  sessions: Record<string, unknown>[];
+  linkedAccounts: Record<string, unknown>[];
+  mfaEnrollments: Record<string, unknown>[];
+  auditLog: Record<string, unknown>[];
+}
+```
+
+The export includes: user profile, tenant memberships, session history, linked OAuth accounts, MFA enrollments, and audit log entries.
+
+### 2. Delete Account
+
+```typescript
+await client.gdpr.deleteAccount("user@example.com");
+```
+
+The `confirmEmail` must match the authenticated user's email as a confirmation step. This action is **irreversible** — all user data is permanently deleted.
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `TOKEN_INVALID` | Not authenticated | Re-authenticate |
+| `VALIDATION_ERROR` | Email doesn't match | Pass correct email |
+| `INTERNAL_ERROR` | Server error during export/delete | Retry |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.gdpr.deleteAccount(email);
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.VALIDATION_ERROR) {
+    console.error("Email confirmation doesn't match your account");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: userToken,
+  refreshToken: userRefreshToken,
+});
+
+async function handleDataExportRequest() {
+  const data = await client.gdpr.exportData();
+  console.log("Export generated at:", data.exportedAt);
+  console.log("Sessions:", data.sessions.length);
+  console.log("Memberships:", data.memberships.length);
+  console.log("MFA enrollments:", data.mfaEnrollments.length);
+
+  // Provide as downloadable JSON
+  return JSON.stringify(data, null, 2);
+}
+
+async function handleAccountDeletionRequest(userEmail: string) {
+  // Confirm with user first (this is irreversible)
+  // promptUserConfirmation() is your app's UI function — show a confirmation dialog
+  const confirmed = await promptUserConfirmation(
+    "This will permanently delete your account and all data. Are you sure?",
+  );
+  if (!confirmed) return;
+
+  try {
+    await client.gdpr.deleteAccount(userEmail);
+    console.log("Account deleted successfully");
+    // Redirect to goodbye page
+  } catch (err) {
+    if (err instanceof IQAuthError) {
+      console.error("Deletion failed:", err.message);
+    }
+    throw err;
+  }
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `exportData()` | GET | `/api/v1/gdpr/export` |
+| `deleteAccount(confirmEmail)` | POST | `/api/v1/gdpr/delete` |

package/docs/guides/invitations.md

@@ -0,0 +1,143 @@
+# Invitations
+
+## Purpose
+
+Invite users to join a tenant. Supports both new users (who create an account) and existing users (who join the tenant directly).
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `tenant_admin` role for creating invitations
+- No auth required for `validate()` and `accept()`
+
+## Environment Note
+
+These administrative examples assume a trusted runtime. First-party browser apps should execute invitation management through a backend cookie session.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `invites` | `create(data)` | Create invitation → `{ invitation, inviteToken?, warning? }` |
+| `invites` | `validate(token)` | Validate invite token → `InviteValidation` |
+| `invites` | `accept(token, data)` | Accept invitation |
+
+## Step-by-Step
+
+### 1. Create an Invitation
+
+```typescript
+const result = await client.invites.create({
+  email: "newuser@example.com",
+  tenantId: "tenant-uuid",
+  role: "user",
+  vendorId: "vendor-uuid",        // optional
+  products: ["iqcapture"],         // optional product access
+});
+// result.inviteToken — for programmatic flows
+// In production, user receives email with invite link
+```
+
+### 2. Validate Token
+
+```typescript
+const validation = await client.invites.validate(inviteToken);
+// { valid: true, email: "user@example.com", role: "user" }
+```
+
+### 3. Accept Invitation
+
+```typescript
+// New user
+await client.invites.accept(inviteToken, {
+  name: "New User",
+  password: "securePassword123",
+});
+
+// Existing Google user
+await client.invites.accept(inviteToken, {
+  googleId: "google-uid-123",
+});
+```
+
+### Alternative: Tenant-Level Invite
+
+```typescript
+await client.tenants.inviteUser(tenantId, {
+  email: "user@example.com",
+  role: "user",
+  products: ["iqcapture"],
+});
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `INVALID_CODE` | Invite code is invalid | Check token |
+| `CODE_ALREADY_USED` | Invite already accepted | Create new invitation |
+| `CODE_EXPIRED` | Invite has expired | Create new invitation |
+| `CODE_IP_MISMATCH` | IP doesn't match invite | Security restriction |
+| `ALREADY_EXISTS` | User already in tenant | No action needed |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.invites.accept(token, { name: "User", password: "pass" });
+} catch (err) {
+  if (err instanceof IQAuthError) {
+    if (err.code === ErrorCodes.CODE_EXPIRED) {
+      console.error("Invitation has expired — request a new one");
+    }
+    if (err.code === ErrorCodes.CODE_ALREADY_USED) {
+      console.error("This invitation was already used");
+    }
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+const adminClient = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: adminToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function inviteAndAccept(tenantId: string, email: string) {
+  const { invitation, inviteToken } = await adminClient.invites.create({
+    email,
+    tenantId,
+    role: "user",
+    products: ["iqcapture"],
+  });
+  console.log("Invitation created:", invitation.id);
+
+  // In a real app, the user clicks an email link containing inviteToken
+  // For programmatic flows:
+
+  const validation = await adminClient.invites.validate(inviteToken!);
+  if (!validation.valid) {
+    throw new Error("Invalid invitation");
+  }
+
+  await adminClient.invites.accept(inviteToken!, {
+    name: "New User",
+    password: "SecurePass123!",
+  });
+  console.log("Invitation accepted");
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `create(data)` | POST | `/api/v1/invites` |
+| `validate(token)` | GET | `/api/v1/invites/:token/validate` |
+| `accept(token, data)` | POST | `/api/v1/invites/:token/accept` |

package/docs/guides/mfa-enrollment.md

@@ -0,0 +1,170 @@
+# MFA Enrollment
+
+## Purpose
+
+Manage multi-factor authentication enrollment for the current user. Supports TOTP (authenticator app), SMS, and email methods, with backup code management.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- Authenticated user (access token set on client)
+- For SMS enrollment: a valid phone number
+
+## Environment Note
+
+The token-owning examples in this guide fit trusted runtimes or native mobile secure storage. First-party browser apps should drive MFA through backend-managed session endpoints.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `mfa` | `getAvailableMethods()` | Available MFA methods |
+| `mfa` | `enrollTotp()` | Start TOTP enrollment → QR code + secret |
+| `mfa` | `verifyTotpEnrollment(code, secret)` | Verify TOTP → enrollment + backup codes |
+| `mfa` | `enrollSms(phone)` | Start SMS enrollment |
+| `mfa` | `verifySmsEnrollment(code, phone)` | Verify SMS enrollment |
+| `mfa` | `startEmailEnrollment()` | Start email enrollment |
+| `mfa` | `verifyEmailEnrollment(code)` | Verify email enrollment |
+| `mfa` | `listEnrollments()` | List enrollments → `MfaEnrollment[]` |
+| `mfa` | `setPrimaryEnrollment(id)` | Set primary method |
+| `mfa` | `deactivateEnrollment(id)` | Remove enrollment |
+| `mfa` | `regenerateBackupCodes()` | Regenerate backup codes |
+| `mfa` | `getBackupCodeCount()` | Get remaining count |
+
+## Step-by-Step
+
+### 1. Check Available Methods
+
+```typescript
+const { available } = await client.mfa.getAvailableMethods();
+// ["totp", "sms", "email"]
+```
+
+### 2. TOTP Enrollment
+
+```typescript
+const { secret, qrCodeUri, qrCodeDataUrl } = await client.mfa.enrollTotp();
+// Display qrCodeDataUrl as <img src="..."> for the user to scan
+
+const { enrollment, backupCodes, backupCodesWarning } = await client.mfa.verifyTotpEnrollment(
+  userEnteredCode,
+  secret,
+);
+// Show backupCodes to user — they won't be shown again
+```
+
+### 3. SMS Enrollment
+
+```typescript
+const { sent } = await client.mfa.enrollSms("+15551234567");
+const { enrollment } = await client.mfa.verifySmsEnrollment(smsCode, "+15551234567");
+```
+
+### 4. Email Enrollment
+
+```typescript
+const { sent } = await client.mfa.startEmailEnrollment();
+const { enrollment } = await client.mfa.verifyEmailEnrollment(emailCode);
+```
+
+### 5. Manage Enrollments
+
+```typescript
+const enrollments = await client.mfa.listEnrollments();
+await client.mfa.setPrimaryEnrollment(enrollmentId);
+await client.mfa.deactivateEnrollment(enrollmentId);
+```
+
+### 6. Backup Codes
+
+```typescript
+const { backupCodes, warning } = await client.mfa.regenerateBackupCodes();
+const { remainingBackupCodes } = await client.mfa.getBackupCodeCount();
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `MFA_INVALID_CODE` | Wrong verification code | Let user retry |
+| `MFA_METHOD_UNAVAILABLE` | Method not supported | Check available methods |
+| `MFA_RATE_LIMITED` | Too many attempts | Wait and retry |
+| `MFA_ENROLLMENT_REQUIRED` | MFA must be enrolled | Redirect to enrollment |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.mfa.verifyTotpEnrollment(code, secret);
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.MFA_INVALID_CODE) {
+    console.error("Wrong code — please try again");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: userToken,
+  refreshToken: userRefreshToken,
+});
+
+async function setupTotp() {
+  const { available } = await client.mfa.getAvailableMethods();
+  if (!available.includes("totp")) {
+    throw new Error("TOTP not available");
+  }
+
+  const { secret, qrCodeDataUrl } = await client.mfa.enrollTotp();
+  console.log("Show this QR code to user:", qrCodeDataUrl);
+
+  // User scans QR and enters the 6-digit code from their authenticator app
+  // promptUserForCode() is your app's UI function — show an input field and return the value
+  const code = await promptUserForCode();
+
+  try {
+    const { enrollment, backupCodes } = await client.mfa.verifyTotpEnrollment(code, secret);
+    console.log("TOTP enrolled:", enrollment.id);
+    console.log("Backup codes (save these!):", backupCodes);
+
+    await client.mfa.setPrimaryEnrollment(enrollment.id);
+  } catch (err) {
+    if (err instanceof IQAuthError && err.code === ErrorCodes.MFA_INVALID_CODE) {
+      console.error("Invalid code — scan QR again and retry");
+    }
+    throw err;
+  }
+}
+
+async function checkBackupCodes() {
+  const { remainingBackupCodes } = await client.mfa.getBackupCodeCount();
+  if (remainingBackupCodes < 3) {
+    console.warn("Low backup codes — consider regenerating");
+    const { backupCodes } = await client.mfa.regenerateBackupCodes();
+    console.log("New backup codes:", backupCodes);
+  }
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `getAvailableMethods()` | GET | `/api/v1/mfa/methods` |
+| `enrollTotp()` | POST | `/api/v1/mfa/enroll/totp` |
+| `verifyTotpEnrollment(code, secret)` | POST | `/api/v1/mfa/enroll/totp/verify` |
+| `enrollSms(phone)` | POST | `/api/v1/mfa/enroll/sms` |
+| `verifySmsEnrollment(code, phone)` | POST | `/api/v1/mfa/enroll/sms/verify` |
+| `startEmailEnrollment()` | POST | `/api/v1/mfa/enroll/email/start` |
+| `verifyEmailEnrollment(code)` | POST | `/api/v1/mfa/enroll/email/verify` |
+| `listEnrollments()` | GET | `/api/v1/mfa/enrollments` |
+| `setPrimaryEnrollment(id)` | PATCH | `/api/v1/mfa/enrollments/:id/primary` |
+| `deactivateEnrollment(id)` | DELETE | `/api/v1/mfa/enrollments/:id` |
+| `regenerateBackupCodes()` | POST | `/api/v1/mfa/backup-codes/regenerate` |
+| `getBackupCodeCount()` | GET | `/api/v1/mfa/backup-codes/count` |