@iqauth/sdk 2.0.0

package/docs/guides/auth-flows.md

@@ -0,0 +1,168 @@
+# Auth Flows
+
+Authentication flow guidance depends on the environment.
+
+## Environment Rules
+
+### First-party browser apps
+
+Use a backend-managed session:
+
+- backend receives credentials
+- backend calls IQAuth
+- backend stores tokens in `httpOnly` cookies
+- browser restores auth from `/auth/me`
+
+Do not use the browser as the durable owner of the refresh token.
+
+### Native mobile apps
+
+Use authorization code + PKCE, then secure storage.
+
+### Server-side apps
+
+Direct token handling is acceptable.
+
+### Service clients
+
+Prefer API keys.
+
+## Shared Login State Machine
+
+The underlying auth flow still has three outcomes:
+
+```typescript
+type LoginResult =
+  | { status: "authenticated"; authMode: "token"; tokens: TokenPair; user: UserProfile }
+  | { status: "authenticated"; authMode: "session"; user: SessionUser }
+  | { status: "mfa_required"; mfaChallengeToken: string; availableMethods: string[] }
+  | { status: "tenant_selection"; tenantSelectionToken: string; tenants: Tenant[] };
+```
+
+This state machine is directly useful in server, mobile, and backend-proxy layers.
+
+## Browser Flow
+
+Recommended first-party browser sequence:
+
+1. `POST /auth/login` on your backend
+2. if MFA is required, complete MFA through your backend
+3. if tenant selection is required, complete tenant selection through your backend
+4. backend sets auth cookies
+5. frontend calls `/auth/me`
+6. frontend calls your protected backend APIs with `credentials: "include"`
+
+The browser should receive user/session state, not raw refresh tokens.
+
+## Server / Trusted Client Flow
+
+If your runtime is trusted and can safely hold credentials:
+
+```typescript
+const result = await client.auth.login(email, password);
+
+if (result.status === "authenticated") {
+  if (result.authMode !== "token") throw new Error("Expected token-authenticated result");
+  client.setTokens(result.tokens);
+}
+```
+
+### MFA
+
+```typescript
+const mfaResult = await client.auth.completeMfa(mfaChallengeToken, code);
+client.setTokens(mfaResult.tokens);
+```
+
+### Backup codes
+
+```typescript
+const mfaResult = await client.auth.completeMfaWithBackup(
+  mfaChallengeToken,
+  backupCode,
+);
+client.setTokens(mfaResult.tokens);
+```
+
+### Tenant selection
+
+```typescript
+const result = await client.auth.selectTenant(tenantSelectionToken, tenantId);
+
+if (result.status === "authenticated") {
+  if (result.authMode !== "token") throw new Error("Expected token-authenticated result");
+  client.setTokens(result.tokens);
+}
+```
+
+### OAuth code exchange
+
+```typescript
+const result = await client.auth.exchangeOAuthCode(code);
+
+if (result.status === "authenticated") {
+  if (result.authMode !== "token") throw new Error("Expected token-authenticated result");
+  client.setTokens(result.tokens);
+}
+```
+
+## Mobile Flow
+
+For native mobile:
+
+1. create PKCE verifier/challenge
+2. redirect to authorization endpoint in system browser
+3. receive authorization code via deep link / universal link
+4. exchange code
+5. store tokens in secure storage
+6. refresh from secure storage when needed
+
+If you use the SDK as a token-owning client on mobile, pair it with secure storage and a PKCE-based login only.
+
+## Refresh Behavior
+
+### Browser
+
+- backend should own refresh
+- browser should not send a JS-managed refresh token as its default first-party pattern
+
+### Server and mobile
+
+`client.auth.refreshTokens(refreshToken)` is appropriate when the refresh token is held by a trusted server or secure mobile storage.
+
+```typescript
+const tokens = await client.auth.refreshTokens(currentRefreshToken);
+client.setTokens(tokens);
+```
+
+## Logout Behavior
+
+### Browser
+
+- call your backend logout endpoint
+- backend clears cookies and terminates the session
+
+### Server and mobile
+
+```typescript
+await client.auth.logout();
+```
+
+## Error Handling
+
+| Error Code | Meaning |
+|--------|--------|
+| `INVALID_CREDENTIALS` | Wrong email/password |
+| `ACCOUNT_LOCKED` | Too many failed attempts |
+| `ACCOUNT_INACTIVE` | Account disabled |
+| `MFA_INVALID_CODE` | Wrong MFA code |
+| `MFA_RATE_LIMITED` | Too many MFA attempts |
+| `TOKEN_EXPIRED` | Access token expired |
+| `PASSWORD_EXPIRED` | Password change required |
+
+## Recommendation Summary
+
+- browser first-party: backend cookie session
+- mobile: PKCE + secure storage
+- server: direct token handling allowed
+- service: API key

package/docs/guides/branding.md

@@ -0,0 +1,160 @@
+# Branding
+
+## Purpose
+
+Manage per-vendor branding configuration for login pages and UI customization. Upload assets, map custom domains, and control publish state.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `vendor_admin` or `platform_admin` role for branding management
+- No auth required for public branding endpoints
+
+## Environment Note
+
+These management examples assume a trusted runtime. First-party browser apps should route branding administration through a backend-managed session layer.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `branding` | `get(vendorId)` | Get branding config → `BrandingConfig` |
+| `branding` | `updateBranding(vendorId, data)` | Update branding config |
+| `branding` | `publishBranding(vendorId)` | Publish branding |
+| `branding` | `unpublishBranding(vendorId)` | Unpublish branding |
+| `branding` | `resetBranding(vendorId)` | Reset to defaults |
+| `branding` | `uploadAsset(vendorId, data)` | Upload asset (base64) |
+| `branding` | `listAssets(vendorId)` | List assets |
+| `branding` | `deleteAsset(vendorId, assetId)` | Delete asset |
+| `branding` | `listDomains(vendorId)` | List domain mappings |
+| `branding` | `addDomain(vendorId, domain)` | Add domain mapping |
+| `branding` | `removeDomain(vendorId, domainId)` | Remove domain mapping |
+| `tenants` | `getPublicBranding(params?)` | Public branding (no auth) |
+| `tenants` | `getPublicBrandingBySlug(slug)` | Public branding by slug (no auth) |
+
+## Step-by-Step
+
+### 1. Update Branding
+
+```typescript
+await client.branding.updateBranding(vendorId, {
+  primaryColor: "#1E40AF",
+  secondaryColor: "#3B82F6",
+  companyName: "Acme Disposal",
+  headline: "Welcome to Acme Portal",
+  subheadline: "Sign in to manage your operations",
+  supportEmail: "support@acme.com",
+  termsUrl: "https://acme.com/terms",
+  privacyUrl: "https://acme.com/privacy",
+  customCss: ".login-form { border-radius: 12px; }",
+});
+```
+
+### 2. Publish
+
+```typescript
+await client.branding.publishBranding(vendorId);
+await client.branding.unpublishBranding(vendorId);
+```
+
+### 3. Upload Assets
+
+```typescript
+const asset = await client.branding.uploadAsset(vendorId, {
+  filename: "logo.png",
+  mimeType: "image/png",
+  data: base64EncodedData,
+  purpose: "logo",
+});
+```
+
+### 4. Domain Mapping
+
+```typescript
+await client.branding.addDomain(vendorId, "login.acme.com");
+const domains = await client.branding.listDomains(vendorId);
+```
+
+### 5. Public Branding (No Auth)
+
+```typescript
+const vendorBranding = await client.tenants.getPublicBranding({ vendor: "acme" });
+const slugBranding = await client.tenants.getPublicBrandingBySlug("acme-disposal");
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | Vendor or asset not found | Check IDs |
+| `UPLOAD_ERROR` | Asset upload failed | Retry or check data format |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `vendor_admin`+ |
+| `VALIDATION_ERROR` | Invalid branding data | Check field formats |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.branding.uploadAsset(vendorId, assetData);
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.UPLOAD_ERROR) {
+    console.error("Failed to upload asset:", err.message);
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  // Trusted runtime example
+  accessToken: vendorAdminToken,
+  refreshToken: vendorAdminRefreshToken,
+});
+
+async function setupBranding(vendorId: string) {
+  await client.branding.updateBranding(vendorId, {
+    primaryColor: "#1E40AF",
+    companyName: "Acme Disposal",
+    headline: "Welcome to Acme",
+    supportEmail: "support@acme.com",
+  });
+
+  const logoAsset = await client.branding.uploadAsset(vendorId, {
+    filename: "logo.png",
+    mimeType: "image/png",
+    data: logoBase64,
+    purpose: "logo",
+  });
+  console.log("Logo uploaded:", logoAsset.url);
+
+  await client.branding.addDomain(vendorId, "login.acme.com");
+  await client.branding.publishBranding(vendorId);
+
+  const config = await client.branding.get(vendorId);
+  console.log("Published:", config.isPublished);
+
+  // Public access (login page):
+  const publicBranding = await client.tenants.getPublicBranding({ vendor: "acme" });
+  console.log("Public branding:", publicBranding?.companyName);
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `get(vendorId)` | GET | `/api/v1/branding/:vendorId` |
+| `updateBranding(vendorId, data)` | PUT | `/api/v1/branding/:vendorId` |
+| `publishBranding(vendorId)` | POST | `/api/v1/branding/:vendorId/publish` |
+| `unpublishBranding(vendorId)` | POST | `/api/v1/branding/:vendorId/unpublish` |
+| `resetBranding(vendorId)` | POST | `/api/v1/branding/:vendorId/reset` |
+| `uploadAsset(vendorId, data)` | POST | `/api/v1/branding/:vendorId/upload` |
+| `listAssets(vendorId)` | GET | `/api/v1/branding/:vendorId/assets` |
+| `deleteAsset(vendorId, assetId)` | DELETE | `/api/v1/branding/:vendorId/assets/:assetId` |
+| `listDomains(vendorId)` | GET | `/api/v1/branding/:vendorId/domains` |
+| `addDomain(vendorId, domain)` | POST | `/api/v1/branding/:vendorId/domains` |
+| `removeDomain(vendorId, domainId)` | DELETE | `/api/v1/branding/:vendorId/domains/:domainId` |

package/docs/guides/entitlements.md

@@ -0,0 +1,115 @@
+# Entitlements
+
+## Purpose
+
+Control which products a tenant has access to (e.g., `iqcapture`, `iqreuse`, `iqvalidate`). Entitlements are included in the JWT `entitlements[]` claim.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `platform_admin` role for granting/revoking entitlements
+- Any authenticated user for checking entitlements client-side
+
+## Environment Note
+
+Administrative entitlement examples are intended for trusted server-side or administrative runtimes.
+
+## SDK Methods
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| `entitlements` | `list(tenantId)` | List entitlements → `Entitlement[]` |
+| `entitlements` | `grant(tenantId, data)` | Grant entitlement → `Entitlement` |
+| `entitlements` | `revoke(tenantId, product)` | Revoke entitlement |
+| `permissions` | `hasEntitlement(ent)` | Client-side check → `boolean` |
+| `permissions` | `hasAllEntitlements(ents)` | Client-side AND check → `boolean` |
+| `permissions` | `hasAnyEntitlement(ents)` | Client-side OR check → `boolean` |
+
+## Step-by-Step
+
+### 1. Grant Entitlement
+
+```typescript
+const entitlement = await client.entitlements.grant(tenantId, {
+  product: "iqcapture",
+  expiresAt: "2027-12-31T23:59:59Z",  // optional
+});
+```
+
+### 2. List Entitlements
+
+```typescript
+const entitlements = await client.entitlements.list(tenantId);
+```
+
+### 3. Revoke Entitlement
+
+```typescript
+await client.entitlements.revoke(tenantId, "iqcapture");
+```
+
+### 4. Check Client-Side
+
+```typescript
+client.permissions.hasEntitlement("iqcapture");
+client.permissions.hasAllEntitlements(["iqcapture", "iqreuse"]);
+```
+
+### 5. Check in Middleware
+
+```typescript
+app.use("/api/capture", iqAuthMiddleware(client, {
+  requiredEntitlements: ["iqcapture"],  // AND logic
+}));
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | Tenant or entitlement not found | Check IDs |
+| `ALREADY_EXISTS` | Product already entitled | No action needed |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `platform_admin` |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.entitlements.grant(tenantId, { product: "iqcapture" });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ALREADY_EXISTS) {
+    console.log("Product already entitled for this tenant");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient, iqAuthMiddleware } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: platformAdminToken,
+  refreshToken: platformAdminRefreshToken,
+});
+
+async function setupTenantEntitlements(tenantId: string) {
+  await client.entitlements.grant(tenantId, { product: "iqcapture" });
+  await client.entitlements.grant(tenantId, { product: "iqreuse" });
+
+  const all = await client.entitlements.list(tenantId);
+  console.log("Active entitlements:", all.map(e => e.product));
+
+  // After user logs in, check client-side:
+  // client.permissions.hasEntitlement("iqcapture") → true
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `list(tenantId)` | GET | `/api/v1/tenants/:tenantId/entitlements` |
+| `grant(tenantId, data)` | POST | `/api/v1/tenants/:tenantId/entitlements` |
+| `revoke(tenantId, product)` | DELETE | `/api/v1/tenants/:tenantId/entitlements/:product` |

package/docs/guides/entity-hierarchy.md

@@ -0,0 +1,200 @@
+# Entity Hierarchy
+
+## Purpose
+
+Manage the three-level organizational hierarchy: **Vendor → Source → Client**. Create entities, link them into a graph, and query the full hierarchy.
+
+## Prerequisites
+
+- `@iqauth/sdk` installed
+- `vendor_admin` or `platform_admin` role for entity management
+- Tenant with vendor hierarchy set up
+
+## Environment Note
+
+These examples assume a trusted runtime with direct token access. They are not first-party browser storage guidance.
+
+## SDK Methods
+
+### VendorsModule
+
+| Method | Description |
+|--------|-------------|
+| `list()` | List all vendors → `Vendor[]` |
+| `get(vendorId)` | Get vendor → `Vendor` |
+| `create(data)` | Create vendor → `Vendor` |
+| `update(vendorId, data)` | Update vendor → `Vendor` |
+| `delete(vendorId)` | Delete vendor |
+
+### SourcesModule
+
+| Method | Description |
+|--------|-------------|
+| `create(vendorId, data)` | Create source under vendor → `Source` |
+| `listForVendor(vendorId)` | List sources for vendor → `Source[]` |
+| `get(sourceId)` | Get source → `Source` |
+| `update(sourceId, data)` | Update source → `Source` |
+| `delete(sourceId)` | Delete source |
+| `createClient(sourceId, data)` | Create client under source → `Client` |
+| `listClients(sourceId)` | List clients for source → `Client[]` |
+
+### ClientsModule
+
+| Method | Description |
+|--------|-------------|
+| `get(clientId)` | Get client → `Client` |
+| `update(clientId, data)` | Update client → `Client` |
+| `delete(clientId)` | Delete client |
+
+### HierarchyModule
+
+| Method | Description |
+|--------|-------------|
+| `getGraph()` | Full hierarchy graph → `HierarchyVendor[]` |
+| `linkVendorSource(vendorId, sourceId)` | Link vendor to source |
+| `unlinkVendorSource(vendorId, sourceId)` | Unlink vendor from source |
+| `linkSourceClient(sourceId, clientId)` | Link source to client |
+| `unlinkSourceClient(sourceId, clientId)` | Unlink source from client |
+
+## Step-by-Step
+
+### 1. Create Entities
+
+```typescript
+const vendor = await client.vendors.create({
+  name: "Acme Disposal",
+  slug: "acme-disposal",
+  status: "active",
+  metadata: { region: "northeast" },
+});
+
+const source = await client.sources.create(vendor.id, {
+  name: "North MRF",
+  slug: "north-mrf",
+  status: "active",
+});
+
+const clientEntity = await client.sources.createClient(source.id, {
+  name: "City of Springfield",
+  slug: "springfield",
+  clientType: "municipal",
+  status: "active",
+});
+```
+
+### 2. Link Hierarchy
+
+```typescript
+await client.hierarchy.linkVendorSource(vendor.id, source.id);
+await client.hierarchy.linkSourceClient(source.id, clientEntity.id);
+```
+
+Note: Unlink operations send entity IDs in the request body (unconventional but matches server). See [DECISION-012](../../DECISIONS.md).
+
+### 3. Query Full Graph
+
+```typescript
+const graph = await client.hierarchy.getGraph();
+// HierarchyVendor[] — each with nested sources and clients
+```
+
+### 4. Update / Delete
+
+```typescript
+await client.vendors.update(vendor.id, { name: "Acme Waste Solutions" });
+await client.clients.update(clientEntity.id, { status: "inactive" });
+await client.hierarchy.unlinkSourceClient(source.id, clientEntity.id);
+await client.clients.delete(clientEntity.id);
+```
+
+## Error Handling
+
+| Error Code | Meaning | Recovery |
+|------------|---------|----------|
+| `NOT_FOUND` | Entity does not exist | Check entity ID |
+| `ALREADY_EXISTS` | Slug already taken | Use different slug |
+| `INSUFFICIENT_PERMISSIONS` | Caller lacks admin role | Requires `vendor_admin`+ |
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.vendors.create({ name: "Test", slug: "test" });
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ALREADY_EXISTS) {
+    console.log("Vendor slug already exists");
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: adminToken,
+  refreshToken: adminRefreshToken,
+});
+
+async function buildHierarchy() {
+  const vendor = await client.vendors.create({
+    name: "Regional Waste Co",
+    slug: "regional-waste",
+  });
+
+  const mrfNorth = await client.sources.create(vendor.id, {
+    name: "MRF North",
+    slug: "mrf-north",
+  });
+
+  const mrfSouth = await client.sources.create(vendor.id, {
+    name: "MRF South",
+    slug: "mrf-south",
+  });
+
+  const springfield = await client.sources.createClient(mrfNorth.id, {
+    name: "Springfield",
+    slug: "springfield",
+  });
+
+  const shelbyville = await client.sources.createClient(mrfSouth.id, {
+    name: "Shelbyville",
+    slug: "shelbyville",
+  });
+
+  await client.hierarchy.linkVendorSource(vendor.id, mrfNorth.id);
+  await client.hierarchy.linkVendorSource(vendor.id, mrfSouth.id);
+  await client.hierarchy.linkSourceClient(mrfNorth.id, springfield.id);
+  await client.hierarchy.linkSourceClient(mrfSouth.id, shelbyville.id);
+
+  const graph = await client.hierarchy.getGraph();
+  console.log("Hierarchy:", JSON.stringify(graph, null, 2));
+}
+```
+
+## API Reference
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `vendors.list()` | GET | `/api/v1/vendors` |
+| `vendors.get(id)` | GET | `/api/v1/vendors/:id` |
+| `vendors.create(data)` | POST | `/api/v1/vendors` |
+| `vendors.update(id, data)` | PATCH | `/api/v1/vendors/:id` |
+| `vendors.delete(id)` | DELETE | `/api/v1/vendors/:id` |
+| `sources.create(vendorId, data)` | POST | `/api/v1/vendors/:vendorId/sources` |
+| `sources.listForVendor(vendorId)` | GET | `/api/v1/vendors/:vendorId/sources` |
+| `sources.get(id)` | GET | `/api/v1/sources/:id` |
+| `sources.update(id, data)` | PATCH | `/api/v1/sources/:id` |
+| `sources.delete(id)` | DELETE | `/api/v1/sources/:id` |
+| `sources.createClient(sourceId, data)` | POST | `/api/v1/sources/:sourceId/clients` |
+| `sources.listClients(sourceId)` | GET | `/api/v1/sources/:sourceId/clients` |
+| `clients.get(id)` | GET | `/api/v1/clients/:id` |
+| `clients.update(id, data)` | PATCH | `/api/v1/clients/:id` |
+| `clients.delete(id)` | DELETE | `/api/v1/clients/:id` |
+| `hierarchy.getGraph()` | GET | `/api/v1/hierarchy` |
+| `hierarchy.linkVendorSource(v, s)` | POST | `/api/v1/hierarchy/link/vendor-source` |
+| `hierarchy.unlinkVendorSource(v, s)` | DELETE | `/api/v1/hierarchy/link/vendor-source` |
+| `hierarchy.linkSourceClient(s, c)` | POST | `/api/v1/hierarchy/link/source-client` |
+| `hierarchy.unlinkSourceClient(s, c)` | DELETE | `/api/v1/hierarchy/link/source-client` |