@qidcloud/sdk 1.2.3 → 1.2.4

package/README.md

@@ -1,257 +1,1660 @@
 # @qidcloud/sdk
 
-The official JavaScript/TypeScript SDK for QidCloud. Build PQC-secured, enclave-backed applications with ease.
+The official JavaScript/TypeScript SDK for **QidCloud** — build PQC-secured, enclave-backed applications with ease.
 
-## 🚀 Installation
+---
+
+## Installation
 
 ```bash
 npm install @qidcloud/sdk
 ```
 
-## 🛠️ Initialization
+---
+
+## Quick Start
 
 ```typescript
 import { QidCloud } from '@qidcloud/sdk';
 
 const qid = new QidCloud({
-  apiKey: 'your_api_key',   // Found in QidCloud Console -> Settings
-  tenantId: 'your_project_id' // Optional, for project-scoped operations
+  apiKey: 'your-api-key',       // From QidCloud Console → Project → Settings
+  tenantId: 'your-tenant-id',   // From QidCloud Console → Project → Overview
+  baseUrl: 'https://api.qidcloud.com' // Optional, defaults to production
+});
+```
+
+### Constructor — `QidConfig`
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `apiKey` | `string` | ✅ | — | Your project's API key. Found in QidCloud Console → Project → Settings. |
+| `tenantId` | `string` | ❌ | — | Your project's Tenant ID. Required for all data operations (DB, Edge, Vault). Found in Console → Project → Overview. |
+| `baseUrl` | `string` | ❌ | `https://api.qidcloud.com` | API server URL. Use `http://localhost:5000` for local development. |
+
+### Environment Variables (Vite / React)
+
+```env
+VITE_QID_API_KEY=your-api-key
+VITE_QID_TENANT_ID=your-tenant-id
+VITE_QID_BASE_URL=http://localhost:5000
+```
+
+```typescript
+const qid = new QidCloud({
+  apiKey: import.meta.env.VITE_QID_API_KEY,
+  tenantId: import.meta.env.VITE_QID_TENANT_ID,
+  baseUrl: import.meta.env.VITE_QID_BASE_URL,
 });
 ```
 
 ---
 
-## ⚠️ Prerequisite: CORS Configuration
+## Modules
 
-Before using the SDK, you **must whitelist your application's domain** in the QidCloud Console.
-1. Go to **Settings > Security**.
-2. Add your app's URL (e.g., `http://localhost:5173` or `https://myapp.com`) to the **Allowed Origins** list.
-3. Without this, browser requests will be blocked by CORS policy.
+After initialization, the SDK exposes the following modules on the `qid` instance:
+
+| Module | Accessor | Purpose |
+|--------|----------|---------|
+| [Authentication](#-authentication-qidauth) | `qid.auth` | Login, sessions, MFA, account recovery |
+| [Database](#-database-qiddb) | `qid.db` | SQL queries, schema setup, migrations |
+| [Edge Computing](#-edge-computing-qidedge) | `qid.edge` | Deploy & invoke serverless functions |
+| [Secure Vault](#-secure-vault-qidvault) | `qid.vault` | Encrypted file storage with recycle bin |
+| [Billing](#-billing--analytics-qidbilling) | `qid.billing` | Plans, transactions, usage analytics |
+| [Projects](#-project-management-qidprojects) | `qid.projects` | Create projects, manage members, service keys |
+| [Resources](#-resource-provisioning-qidresources) | `qid.resources` | Provision databases, storage, edge runtimes |
+| [Logs](#-observability-qidlogs) | `qid.logs` | Write & retrieve application logs |
+| [SDK Config](#-sdk-configuration-qidsdk) | `qid.sdk` | Manage allowed origins for CORS |
 
 ---
 
-## 🛡️ Authentication Guide
+## 🔐 Authentication (`qid.auth`)
 
-QidCloud uses a **Post-Quantum Cryptography (PQC)** handshake for authentication. Users strictly log in by scanning a QR code with their QidCloud Mobile App. **Password entry is NOT supported** in the SDK to ensure credentials never touch the client device.
+QidCloud supports **Post-Quantum Cryptography (PQC)** authentication via QR scanning, as well as traditional username/password login.
 
-### 1. Recommended: Using `QidCloudLogin` Component
-The easiest way to implement secure login.
-```tsx
-import { QidCloud, QidCloudLogin } from '@qidcloud/sdk';
+### `createSession()`
+
+Create a new handshake session. Returns a QR code payload for the mobile app to scan.
+
+```typescript
+const session = await qid.auth.createSession();
+// session.sessionId  → unique session identifier
+// session.qrData     → stringified QR code data for the mobile app
+// session.expiresAt  → expiry timestamp (ms since epoch)
+```
+
+**Returns:** [`QidAuthSession`](#qidauthsession)
+
+---
+
+### `listen(sessionId, onAuthorized, onDenied?)`
+
+Listen for mobile app authorization on a specific session via WebSocket.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sessionId` | `string` | ✅ | The session ID from `createSession()` |
+| `onAuthorized` | `(token: string) => void` | ✅ | Called when the user authorizes. Receives a JWT session token. |
+| `onDenied` | `(msg: string) => void` | ❌ | Called if the user denies or the session expires. |
+
+```typescript
+qid.auth.listen(
+  session.sessionId,
+  (token) => console.log('Logged in! Token:', token),
+  (err) => console.error('Denied:', err)
+);
+```
+
+---
+
+### `login(credentials)`
 
-const sdk = new QidCloud({
-  apiKey: 'your_api_key',
-  tenantId: 'your_project_id'
+Traditional login with username/email and password.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `credentials.username` | `string` | ❌ | Login username (either `username` or `email` required) |
+| `credentials.email` | `string` | ❌ | Login email |
+| `credentials.password` | `string` | ✅ | Account password |
+
+```typescript
+const { token, user } = await qid.auth.login({
+  username: 'jdoe',
+  password: 'my-secure-password'
 });
+```
 
-function App() {
-  return (
-    <QidCloudLogin 
-      sdk={sdk} 
-      onSuccess={(user, token) => {
-        console.log('Logged in:', user);
-        // Token is also automatically cached in localStorage by the component
-      }}
-      onError={(err) => console.error(err)}
-    />
-  );
-}
+**Returns:** `{ token: string; user: QidUser }`
+
+---
+
+### `register(data)`
+
+Register a new user identity.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.username` | `string` | ✅ | Desired username |
+| `data.email` | `string` | ✅ | User email address |
+| `data.password` | `string` | ✅ | Password |
+| `data.fullName` | `string` | ❌ | Full display name |
+
+```typescript
+const result = await qid.auth.register({
+  username: 'jdoe',
+  email: 'john@example.com',
+  password: 'secure-password',
+  fullName: 'John Doe'
+});
+// result.success → true
+// result.message → 'Registration successful'
 ```
 
-### 2. Custom UI: Using `useQidAuth` Hook
-For building your own UI while keeping the SDK's state management.
-```tsx
-import { useQidAuth } from '@qidcloud/sdk';
+**Returns:** `{ success: boolean; message: string }`
 
-function CustomLogin() {
-  const { 
-    login,    // Generates QR and starts polling
-    session,  // Contains { qrData } to display
-    user,     // Populated on success
-    logout 
-  } = useQidAuth(sdk);
+---
 
-  if (user) return <button onClick={logout}>Logout {user.username}</button>;
+### `initiateRegistration(email)`
 
-  return (
-    <div>
-      <button onClick={login}>Generate QR</button>
-      {session && <QRCode value={session.qrData} />}
-    </div>
-  );
-}
+Initiate an OTP-based registration flow.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | `string` | ✅ | Email to send OTP to |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `verify(data)`
+
+Verify an OTP or mobile verification code.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.email` | `string` | ❌ | Email for OTP verification |
+| `data.otp` | `string` | ❌ | The OTP code |
+| `data.token` | `string` | ❌ | Verification token (for mobile flows) |
+
+**Returns:** `{ success: boolean; token?: string }`
+
+---
+
+### `getProfile(token)`
+
+Fetch the current user's profile using their session token.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token from login or `listen()` |
+
+```typescript
+const user = await qid.auth.getProfile(token);
+// user.userId, user.username, user.email, user.role, etc.
 ```
 
-### 3. Raw Implementation (No SDK)
-If you prefer to hit the endpoints directly:
-1. **Create Session**: `POST /api/auth/session` (Headers: `x-api-key`, `x-tenant-id`) -> Returns `sessionId`, `qrData`.
-2. **Display QR**: Render `qrData` as a QR code.
-3. **Listen (Socket/Poll)**: Connect to `socket.io` specific to `sessionId` OR poll status.
-4. **Exchange**: When mobile app confirms, server sends auth token.
-5. **Get Profile**: `GET /api/me` (Header: `Authorization: Bearer <token>`).
-
-### 📱 Mobile-to-Mobile (App-to-App) Auth
-If you are building a mobile application that needs to authenticate users via the QidCloud Mobile App:
-
-1. **Initiate**: Call `sdk.auth.createSession()` to get a `sessionId`.
-2. **Deep Link**: Construct a deep link to the QidCloud app using the following format:
-   ```
-   qidcloud://authorize?data=<JSON_PAYLOAD>&callback=<YOUR_APP_SCHEME>
-   ```
-   - **data**: URL-encoded JSON containing `{ "sessionId": "..." }`.
-   - **callback**: Your app's deep link scheme (e.g., `myapp://auth-callback`).
-3. **Handle Callback**: The QidCloud app will redirect back to your callback URL with status results:
-   - **Success**: `myapp://auth-callback?status=accepted&userId=<APPROVER_ID>`
-   - **Rejection**: `myapp://auth-callback?status=rejected`
-4. **Finalize**: Your app should listen for the `authenticated` event on the socket (as shown in Step 2) to receive the final session token.
-
----
-### 🔐 Session Management
-- **Persistence**: The SDK automatically caches the token in `localStorage` under `qid_auth_token`.
-- **Restoration**: On page load, `useQidAuth` checks for this token and verifies it via `/api/me`.
-- **Expiry**: Tokens expire after **1 hour of inactivity**. The backend implements a sliding window, so active sessions automatically extend their validity. Handle 401 errors by calling `logout()`.
-
-### 🚪 Logout Handling
-Always use the SDK's `logout()` method to preventing "ghost sessions".
-```tsx
-const { logout } = useQidAuth(sdk);
-// ...
-<button onClick={logout}>Sign Out</button>
+**Returns:** [`QidUser`](#qiduser)
+
+---
+
+### `logout(token)`
+
+Terminate the active session on the server and disconnect WebSocket.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+
+```typescript
+await qid.auth.logout(token);
 ```
-**What `logout()` does:**
-1. Calls `POST /api/logout` to invalidate the session on the server.
-2. Removes the token from `localStorage`.
-3. Clears in-memory state.
 
 ---
 
-## 🗄️ Secure Vault (`qid.vault`)
+### `disconnect()`
+
+Stop listening on the WebSocket and disconnect. Does not invalidate the session server-side.
 
-### `upload(file, name, metadata?, userToken?)`
-Encrypt and upload a file to the secure enclave.
-- **Returns**: `Promise<QidUploadResponse>`
 ```typescript
-await qid.vault.upload(fileBlob, 'secret.pdf', { tag: 'confidential' }, userToken);
+qid.auth.disconnect();
 ```
 
-### `list(userToken?)`
-List all encrypted files.
-- **Returns**: `Promise<QidFile[]>`
+---
+
+### `refreshSession(token)`
+
+Refresh/extend the current JWT session.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | Current JWT session token |
+
 ```typescript
-const files = await qid.vault.list(userToken);
+const { token: newToken } = await qid.auth.refreshSession(token);
 ```
 
-### `download(fileId, userToken?)`
-Download a file as an ArrayBuffer.
+**Returns:** `{ token: string }`
+
+---
+
+### `getSessions(token)`
+
+List all active sessions (devices) for the current user.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+
 ```typescript
-const buffer = await qid.vault.download('file_123', userToken);
+const sessions = await qid.auth.getSessions(token);
+// sessions[0].token, sessions[0].lastActive, sessions[0].ip, sessions[0].userAgent
 ```
 
-### `delete(fileId, userToken?)`
-Soft delete a file (move to recycle bin).
+**Returns:** [`QidSession[]`](#qidsession)
+
+---
+
+### `revokeSession(token, sessionToken)`
+
+Revoke (force-logout) a specific session.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | Your current JWT session token |
+| `sessionToken` | `string` | ✅ | The session token to revoke (from `getSessions()`) |
+
 ```typescript
-await qid.vault.delete('file_123', userToken);
+await qid.auth.revokeSession(myToken, 'target-session-token');
 ```
 
+**Returns:** `{ success: boolean }`
+
 ---
 
-## ⚡ Edge Computing (`qid.edge`)
+### `requestPasswordReset(email)`
+
+Send a password reset OTP to the user's email.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | `string` | ✅ | Registered email address |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `confirmPasswordReset(data)`
+
+Confirm a password reset using the OTP.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.email` | `string` | ✅ | Registered email |
+| `data.otp` | `string` | ✅ | OTP from email |
+| `data.newPassword` | `string` | ✅ | New password |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `changePassword(token, data)`
+
+Change password for the currently logged-in user.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+| `data.currentPassword` | `string` | ✅ | Current password |
+| `data.newPassword` | `string` | ✅ | New password |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `deleteAccount(token)`
+
+Permanently delete the user's account.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `toggleMFA(token, data)`
+
+Enable or disable Multi-Factor Authentication.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+| `data.enabled` | `boolean` | ✅ | `true` to enable, `false` to disable |
+| `data.type` | `'email' \| 'totp' \| 'mobile'` | ✅ | MFA method |
 
-### `invoke(name, params?, userToken?)`
-Invoke a serverless edge function.
-- **Returns**: `Promise<QidEdgeResponse>`
 ```typescript
-const result = await qid.edge.invoke('secure-calc', { input: 42 }, userToken);
+await qid.auth.toggleMFA(token, { enabled: true, type: 'email' });
 ```
 
-### `list()`
-List all provisioned functions.
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `verifyMFA(token, otp)`
+
+Verify an MFA toggle request with the OTP sent to the user.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+| `otp` | `string` | ✅ | OTP code |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `initiateRecovery(email)`
+
+Initiate account recovery (password reset).
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | `string` | ✅ | Registered email |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `verifyRecovery(data)`
+
+Complete recovery with OTP and set a new password.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.email` | `string` | ✅ | Registered email |
+| `data.otp` | `string` | ✅ | OTP from recovery email |
+| `data.newPassword` | `string` | ✅ | New password |
+
+**Returns:** `{ success: boolean; token: string }`
+
+---
+
+### `exportUserData(token)`
+
+Export all user data (GDPR compliance).
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `token` | `string` | ✅ | JWT session token |
+
 ```typescript
-const functions = await qid.edge.list();
+const data = await qid.auth.exportUserData(token);
 ```
 
-### `getLogs(name, userToken?)`
-Get logs for a specific function.
+**Returns:** Full user data export object.
+
+---
+
+## 🗄️ Database (`qid.db`)
+
+Execute SQL queries against your project's isolated PostgreSQL enclave.
+
+### `query(sql, params?, userToken?)`
+
+Execute a parameterized SQL query.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `sql` | `string` | ✅ | — | SQL query string. Supports `$1`, `$2` placeholders. |
+| `params` | `any[]` | ❌ | `[]` | Parameterized values (prevents SQL injection) |
+| `userToken` | `string` | ❌ | — | JWT session token for user-scoped access |
+
+```typescript
+// SELECT
+const posts = await qid.db.query('SELECT * FROM posts WHERE user_id = $1', [userId]);
+// posts.success → true
+// posts.data    → [{ id: '...', title: '...' }, ...]
+// posts.count   → number of rows
+
+// INSERT
+await qid.db.query(
+  'INSERT INTO posts (title, body) VALUES ($1, $2)',
+  ['Hello World', 'My first post']
+);
+
+// CREATE TABLE
+await qid.db.query(`
+  CREATE TABLE IF NOT EXISTS users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+  )
+`);
+```
+
+**Returns:** [`QidDbResponse<T>`](#qiddbresponset--any)
+
+---
+
+### `setup(userToken?)`
+
+Initialize the project's enclave database schema. Useful for first-time project setup — creates the isolated schema for your tenant.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userToken` | `string` | ❌ | JWT session token |
+
+```typescript
+const { success, schemaName } = await qid.db.setup();
+```
+
+**Returns:** `{ success: boolean; schemaName: string }`
+
+---
+
+### `migrate(migrations, userToken?)`
+
+Run versioned migrations (Django-inspired). Only applies migrations that haven't been run yet. Tracks applied migrations in a `_qid_migrations` table that is automatically created.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `migrations` | [`QidMigration[]`](#qidmigration) | ✅ | Ordered array of versioned migrations |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**How it works:**
+1. Creates `_qid_migrations` tracking table if it doesn't exist
+2. Queries already-applied migrations
+3. Runs **only new** migrations in order
+4. Records each successful migration in the tracking table
+5. **Stops on first failure** (like Django)
+
+```typescript
+import { QidMigration } from '@qidcloud/sdk';
+
+const migrations: QidMigration[] = [
+  {
+    version: '001',
+    name: 'create_users_table',
+    up: async () => {
+      await qid.db.query(`
+        CREATE TABLE IF NOT EXISTS users (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          email VARCHAR(255) UNIQUE NOT NULL,
+          name VARCHAR(255),
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+      `);
+    }
+  },
+  {
+    version: '002',
+    name: 'add_avatar_column',
+    up: async () => {
+      await qid.db.query(`ALTER TABLE users ADD COLUMN IF NOT EXISTS avatar_url TEXT`);
+    }
+  },
+  {
+    version: '003',
+    name: 'create_posts_table',
+    up: async () => {
+      await qid.db.query(`
+        CREATE TABLE IF NOT EXISTS posts (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID REFERENCES users(id),
+          title TEXT NOT NULL,
+          body TEXT,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+      `);
+    }
+  }
+];
+
+// Run on app startup — safe to call every time
+const result = await qid.db.migrate(migrations);
+
+if (result.success) {
+  console.log(`Applied: ${result.applied.length}, Skipped: ${result.skipped.length}`);
+} else {
+  console.error(`Migration ${result.failed?.version} failed:`, result.failed?.error);
+}
+```
+
+**Returns:** [`QidMigrateResult`](#qidmigrateresult)
+
+---
+
+### `migrateStatus(migrations, userToken?)`
+
+Check which migrations have been applied and which are pending — without running anything.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `migrations` | [`QidMigration[]`](#qidmigration) | ✅ | Your full migration list |
+| `userToken` | `string` | ❌ | JWT session token |
+
+```typescript
+const status = await qid.db.migrateStatus(migrations);
+// status.applied → ['001', '002']
+// status.pending → ['003']
+// status.total   → 3
+```
+
+**Returns:** `{ applied: string[]; pending: string[]; total: number }`
+
+---
+
+## ⚡ Edge Computing (`qid.edge`)
+
+Deploy and invoke serverless functions inside your project's enclave.
+
+### `invoke(name, params?, userToken?)`
+
+Invoke a deployed edge function by name.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | `string` | ✅ | — | Function name (as deployed) |
+| `params` | `any` | ❌ | `{}` | Arguments passed to the function's `event.params` |
+| `userToken` | `string` | ❌ | — | JWT session token |
+
 ```typescript
-const logs = await qid.edge.getLogs('my-function', userToken);
+const result = await qid.edge.invoke('calculate-tax', {
+  amount: 1000,
+  region: 'US'
+}, userToken);
+// result.success     → true
+// result.result      → { tax: 80, total: 1080 }
+// result.computeTime → '12ms'
+// result.logs        → ['Tax calculated for region US']
 ```
 
+**Returns:** [`QidEdgeResponse`](#qidedgeresponse)
+
+---
+
 ### `deploy(data, userToken?)`
-Deploy or update a function.
+
+Deploy a new edge function or update an existing one.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `data.name` | `string` | ✅ | — | Function name (lowercase, hyphens allowed) |
+| `data.code` | `string` | ✅ | — | JavaScript source code with `exports.handler` |
+| `data.runtime` | `string` | ❌ | — | Runtime (e.g. `'nodejs20.x'`). See `getRuntimes()` |
+| `data.envVars` | `object` | ❌ | — | Environment variables for the function |
+| `data.overwrite` | `boolean` | ❌ | `false` | If `true`, replaces existing function with same name |
+| `userToken` | `string` | ❌ | — | JWT session token |
+
 ```typescript
-await qid.edge.deploy({ 
-  name: 'new-func', 
-  code: '...', 
-  runtime: 'node18' 
+await qid.edge.deploy({
+  name: 'send-welcome-email',
+  code: `
+    exports.handler = async (event) => {
+      const { email, name } = event.params;
+      // Your logic here
+      return { success: true, message: 'Email sent to ' + email };
+    };
+  `,
+  runtime: 'nodejs20.x',
+  overwrite: true
 }, userToken);
 ```
 
+**Returns:** `{ success: boolean; message: string }`
+
 ---
 
-## 📊 Observability (`qid.logs`)
+### `list()`
+
+List all deployed edge functions in the project.
 
-### `write(message, source?, level?, meta?)`
-Ingest custom telemetry into the enclave.
 ```typescript
-await qid.logs.write('User action detected', 'frontend', 'info', { userId: '123' });
+const functions = await qid.edge.list();
 ```
 
-### `fetch(query?)`
-Retrieve project logs.
+**Returns:** `any[]` — Array of function metadata objects.
+
+---
+
+### `delete(name, userToken?)`
+
+Delete a deployed function.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | ✅ | Function name to delete |
+| `userToken` | `string` | ❌ | JWT session token |
+
 ```typescript
-const logs = await qid.logs.fetch({ limit: 50, level: 'error' });
+await qid.edge.delete('old-function', userToken);
 ```
 
+**Returns:** `{ success: boolean }`
+
 ---
 
+### `getLogs(name, userToken?)`
+
+Get execution logs for a specific function.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | ✅ | Function name |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**Returns:** `any[]`
 
 ---
 
-## ✅ Production Readiness Checklist
+### `getProjectLogs(userToken?)`
 
-To ensure a secure and robust integration, verify the following before going live:
+Get all edge function logs across the entire project.
 
-- [ ] **HTTPS Only**: Ensure your application is served over HTTPS. The SDK's cryptographic features (and many browser security APIs) require a secure context.
-- [ ] **Environment Variables**: Store your `apiKey` and `tenantId` in environment variables (e.g., `VITE_QID_API_KEY`) ensuring they are not hardcoded in version control.
-- [ ] **Error Boundaries**: Wrap the `QidCloudLogin` component in a React Error Boundary to gracefully handle any unexpected runtime failures.
-- [ ] **Strict Mode**: If using React Strict Mode, ensure your `useEffect` logic handles double-invocation (The SDK's hooks are already optimized for this).
-- [ ] **CORS**: Double-check that all your production domains (including `www` and non-`www`) are whitelisted in the QidCloud Console.
+**Returns:** `any[]`
 
-## ⚛️ React Helpers
+---
 
-### `useQidAuth(sdk)`
-Hook for managing authentication state.
-```tsx
-const { user, login, logout } = useQidAuth(qid);
-```
+### `getRuntimes()`
 
-### `QidSignInButton`
-Pre-built component for PQC login.
-```tsx
-<QidSignInButton sdk={qid} onSuccess={(user) => console.log(user)} />
+List available serverless runtimes.
+
+```typescript
+const runtimes = await qid.edge.getRuntimes();
+// ['nodejs18.x', 'nodejs20.x', ...]
 ```
 
+**Returns:** `string[]`
+
+---
+
+### `toggleLogging(enabled, userToken?)`
+
+Enable or disable centralized logging for all edge functions in the project.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `enabled` | `boolean` | ✅ | `true` to enable, `false` to disable |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**Returns:** `{ success: boolean; loggingEnabled: boolean }`
+
 ---
 
-## ❓ Troubleshooting
+## 🔒 Secure Vault (`qid.vault`)
+
+Encrypted file storage within your project's enclave. Supports upload, download, soft delete with recycle bin, restore, and permanent purge.
 
-### "Invalid hook call" after linking the SDK locally
-If you are developing the SDK locally and linking it to your project (via `npm link` or `npm install ../sdk-path`), you might encounter an "Invalid hook call" error. This is usually caused by **Duplicate React** (the app and the SDK are using different React instances).
+### `upload(file, fileName, metadata?, userToken?, options?)`
 
-**Solution for Vite projects:**
-Add `resolve.dedupe` to your `vite.config.ts` to force both your app and the SDK to share the same React instance.
+Upload a file to the project's secure storage. Automatically uses **chunked upload** for files ≥ 10MB to support large files (up to 2GB) and progress tracking.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `file` | `Blob \| Buffer` | ✅ | — | File data |
+| `fileName` | `string` | ✅ | — | File name (e.g. `'photo.jpg'`) |
+| `metadata` | `object` | ❌ | `{}` | Custom metadata or E2EE tags |
+| `userToken` | `string` | ❌ | — | JWT session token |
+| `options` | [`QidUploadOptions`](#qiduploadoptions) | ❌ | — | Upload options (progress tracking, chunk size) |
 
 ```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
+// Single-shot upload (< 10MB)
+const result = await qid.vault.upload(fileBlob, 'secret.pdf');
 
-export default defineConfig({
-  // ... rest of config
-  resolve: {
-    dedupe: ['react', 'react-dom']
+// Chunked upload (Automatic for >= 10MB)
+const result = await qid.vault.upload(largeVideo, 'lecture.mp4', {}, token, {
+  onProgress: (p) => {
+    console.log(`Progress: ${p.percent}%`);
+    console.log(`Uploaded ${p.uploadedChunks} of ${p.totalChunks} chunks`);
   }
-})
+});
 ```
 
-**Manual Check:**
-Ensure that the `@qidcloud/sdk` folder does NOT have a `node_modules/react` directory. If it does, delete it manually so it defers to your project's React.
+**Returns:** [`QidUploadResponse`](#qiduploadresponse)
+
+---
+
+### `getUploadStatus(uploadId, userToken?)`
+
+Query the status of an ongoing or interrupted chunked upload. Useful for implementing resumable uploads.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `uploadId` | `string` | ✅ | The ID returned by the upload init phase |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**Returns:** `any` — Object containing `status`, `receivedChunks`, `missingChunks`, and `progress`.
+
+---
+
+### `resumeUpload(uploadId, file, userToken?, options?)`
+
+Resume a previously interrupted chunked upload session.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `uploadId` | `string` | ✅ | Session ID to resume |
+| `file` | `Blob \| Buffer` | ✅ | The SAME file data used in the initial upload |
+| `userToken` | `string` | ❌ | JWT session token |
+| `options` | [`QidUploadOptions`](#qiduploadoptions) | ❌ | Upload options |
+
+```typescript
+await qid.vault.resumeUpload(uploadId, file, token, {
+  onProgress: (p) => console.log(`Resuming: ${p.percent}%`)
+});
+```
+
+**Returns:** [`QidUploadResponse`](#qiduploadresponse)
+
+---
+
+### `list(userToken?)`
+
+List all files in the project enclave.
+
+```typescript
+const files = await qid.vault.list(userToken);
+// files[0].fileId, files[0].originalName, files[0].mimeType, files[0].size
+```
+
+**Returns:** [`QidFile[]`](#qidfile)
+
+---
+
+### `download(fileId, userToken?)`
+
+Download a file by its ID. Returns raw binary data.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fileId` | `string` | ✅ | File ID from `upload()` or `list()` |
+| `userToken` | `string` | ❌ | JWT session token |
+
+```typescript
+const data = await qid.vault.download('abc-123', userToken);
+const blob = new Blob([data]);
+const url = URL.createObjectURL(blob);
+```
+
+**Returns:** `ArrayBuffer`
+
+---
+
+### `delete(fileId, userToken?)`
+
+Soft delete a file. Moves it to the recycle bin — can be restored later.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fileId` | `string` | ✅ | File ID |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `listDeleted(userToken?)`
+
+List files in the recycle bin.
+
+```typescript
+const deletedFiles = await qid.vault.listDeleted(userToken);
+```
+
+**Returns:** [`QidFile[]`](#qidfile)
+
+---
+
+### `restore(fileId, userToken?)`
+
+Restore a file from the recycle bin.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fileId` | `string` | ✅ | File ID of the deleted file |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `purge(fileId, userToken?)`
+
+**Permanently** delete a file from the recycle bin. This action is irreversible.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fileId` | `string` | ✅ | File ID of the deleted file |
+| `userToken` | `string` | ❌ | JWT session token |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+## 💳 Billing & Analytics (`qid.billing`)
+
+Manage plans, transactions, usage analytics, and billing alerts.
+
+### `getPlans()`
+
+Retrieve all available plans and their pricing tiers.
+
+```typescript
+const plans = await qid.billing.getPlans();
+```
+
+**Returns:** Plan objects with tier details, pricing, and feature limits.
+
+---
+
+### `getProjectBillingInfo(userToken, tenantId)`
+
+Get detailed billing and resource usage info for a specific project.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userToken` | `string` | ✅ | JWT session token |
+| `tenantId` | `string` | ✅ | Project tenant ID |
+
+```typescript
+const billing = await qid.billing.getProjectBillingInfo(token, tenantId);
+// billing.plan             → 'pro'
+// billing.estimatedMonthly → 29.99
+// billing.activeEnclaves   → ['database', 'storage', 'edge']
+```
+
+**Returns:** [`QidBillingInfo`](#qidbillinginfo)
+
+---
+
+### `syncPaymentStatus(userToken, paymentId)`
+
+Sync payment status after a successful Razorpay transaction.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userToken` | `string` | ✅ | JWT session token |
+| `paymentId` | `string` | ✅ | Razorpay payment ID |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `getTransactions(userToken)`
+
+Get transaction history for the current user.
+
+```typescript
+const transactions = await qid.billing.getTransactions(token);
+// transactions[0].transactionId, .amount, .date, .status, .planId
+```
+
+**Returns:** [`QidTransaction[]`](#qidtransaction)
+
+---
+
+### `getUsageAnalytics(userToken)`
+
+Get usage analytics and resource consumption history.
+
+**Returns:** Usage analytics data.
+
+---
+
+### `getBillingAlerts(userToken, tenantId)`
+
+Get all billing alerts for a project.
+
+**Returns:** `any[]`
+
+---
+
+### `createBillingAlert(userToken, tenantId, data)`
+
+Create a billing threshold alert.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userToken` | `string` | ✅ | JWT session token |
+| `tenantId` | `string` | ✅ | Project tenant ID |
+| `data.resource` | `string` | ✅ | Resource type (e.g. `'egress'`, `'storage'`, `'compute'`) |
+| `data.threshold` | `number` | ✅ | Alert threshold in USD |
+
+```typescript
+await qid.billing.createBillingAlert(token, tenantId, {
+  resource: 'egress',
+  threshold: 50  // Alert at $50
+});
+```
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `deleteBillingAlert(userToken, alertId)`
+
+Delete a billing alert.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userToken` | `string` | ✅ | JWT session token |
+| `alertId` | `string` | ✅ | Alert ID from `getBillingAlerts()` |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `getConsolidatedReport(userToken, query?)`
+
+Generate a consolidated financial report.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userToken` | `string` | ✅ | JWT session token |
+| `query.year` | `number` | ❌ | Filter by year (e.g. `2026`) |
+| `query.startDate` | `string` | ❌ | Start date (ISO format) |
+| `query.endDate` | `string` | ❌ | End date (ISO format) |
+
+```typescript
+const report = await qid.billing.getConsolidatedReport(token, { year: 2026 });
+```
+
+---
+
+## 🏗️ Project Management (`qid.projects`)
+
+Create and manage projects, invite team members, rotate API keys, and manage service keys.
+
+### `getMyProjects(userToken)`
+
+List all projects owned by the currently authenticated user.
+
+```typescript
+const projects = await qid.projects.getMyProjects(token);
+// projects[0].name, .tenantId, .apiKey, .tier, .status
+```
+
+**Returns:** [`QidProject[]`](#qidproject)
+
+---
+
+### `createProject(userToken, data)`
+
+Create a new project.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `userToken` | `string` | ✅ | — | JWT session token |
+| `data.name` | `string` | ✅ | — | Project name |
+| `data.tier` | `string` | ❌ | `'free'` | Plan tier: `'free'`, `'pro'`, `'elite'`, `'enterprise'` |
+
+```typescript
+const project = await qid.projects.createProject(token, {
+  name: 'My Social App',
+  tier: 'pro'
+});
+// project.tenantId → 'abc-123'
+// project.apiKey   → 'qid_...'
+```
+
+**Returns:** [`QidProject`](#qidproject)
+
+---
+
+### `updateProject(userToken, tenantId, data)`
+
+Update project details (e.g. rename).
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.name` | `string` | ✅ | New project name |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `rotateApiKey(userToken, tenantId)`
+
+Rotate the API key for a project. The old key is immediately invalidated.
+
+```typescript
+const { apiKey } = await qid.projects.rotateApiKey(token, tenantId);
+// apiKey → new API key string
+```
+
+**Returns:** `{ success: boolean; apiKey: string }`
+
+---
+
+### `getSettings(userToken, tenantId)`
+
+Get project-specific settings.
+
+**Returns:** [`QidProjectSettings`](#qidprojectsettings)
+
+---
+
+### `updateSettings(userToken, tenantId, settings)`
+
+Update project settings.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `settings` | [`QidProjectSettings`](#qidprojectsettings) | ✅ | Settings object |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `inviteMember(userToken, tenantId, data)`
+
+Invite a new member to the project.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.email` | `string` | ✅ | Invitee's email |
+| `data.role` | `string` | ✅ | Role: `'developer'`, `'admin'`, `'viewer'` |
+
+```typescript
+await qid.projects.inviteMember(token, tenantId, {
+  email: 'dev@company.com',
+  role: 'developer'
+});
+```
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `removeMember(userToken, tenantId, userId)`
+
+Remove a member from the project.
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `getProjectUsers(userToken, tenantId)`
+
+Get all users/members associated with a project.
+
+**Returns:** `any[]`
+
+---
+
+### `getMyInvitations(userToken)`
+
+Get all pending project invitations for the current user.
+
+**Returns:** `any[]`
+
+---
+
+### `handleInvitationAction(userToken, tenantId, action)`
+
+Accept or reject a project invitation.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | `'accept' \| 'reject'` | ✅ | Invitation action |
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `updateMemberPermissions(userToken, tenantId, userId, permissions)`
+
+Update a member's permissions within a project.
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `updateProjectUserStatus(userToken, tenantId, regUserId, status)`
+
+Update a project user's status (`'active'` or `'suspended'`).
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `unlinkProjectUser(userToken, tenantId, regUserId)`
+
+Remove a user from the project's identity enclave.
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `generateServiceKey(userToken, tenantId, data)`
+
+Generate a service key for server-to-server authentication.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data.name` | `string` | ✅ | Key name/label |
+| `data.permissions` | `object` | ✅ | Permission scopes |
+
+**Returns:** Service key object with the generated key.
+
+---
+
+### `revokeServiceKey(userToken, tenantId, keyId)`
+
+Revoke an existing service key.
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `wipeProjectEnclave(userToken, tenantId)`
+
+⚠️ **DANGER**: Permanently erases all identity data within the project enclave. This action is irreversible.
+
+```typescript
+await qid.projects.wipeProjectEnclave(token, tenantId);
+```
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `getProjectSecurityLogs(userToken, tenantId)`
+
+Retrieve security and audit logs for the project.
+
+**Returns:** `any[]`
+
+---
+
+## 🚀 Resource Provisioning (`qid.resources`)
+
+Provision and manage infrastructure resources (database, storage, edge runtime) for your project.
+
+### `getStatus(userToken, tenantId)`
+
+Get the status of all provisioned resources.
+
+```typescript
+const resources = await qid.resources.getStatus(token, tenantId);
+// resources[0].resourceType → 'database'
+// resources[0].status       → 'active'
+// resources[0].endpoint     → 'db-endpoint.qidcloud.com'
+```
+
+**Returns:** [`QidResourceStatus[]`](#qidresourcestatus)
+
+---
+
+### `provision(userToken, tenantId, resourceType)`
+
+Provision a new resource for the project.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `resourceType` | `string` | ✅ | `'database'`, `'storage'`, or `'edge'` |
+
+```typescript
+await qid.resources.provision(token, tenantId, 'database');
+```
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `dissolve(userToken, tenantId, resourceType)`
+
+Dissolve (permanently delete) a provisioned resource.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `resourceType` | `string` | ✅ | `'database'`, `'storage'`, or `'edge'` |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+## 📊 Observability (`qid.logs`)
+
+Write and retrieve structured application logs.
+
+### `write(message, source?, level?, metadata?)`
+
+Write a custom application log entry.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `message` | `string` | ✅ | — | Log message |
+| `source` | `string` | ❌ | `'app'` | Source label (e.g. `'auth-service'`, `'payment'`) |
+| `level` | `string` | ❌ | `'info'` | Log level: `'info'`, `'warn'`, `'error'` |
+| `metadata` | `object` | ❌ | `{}` | Structured data for searching/filtering |
+
+```typescript
+await qid.logs.write('User signed up', 'auth-service', 'info', {
+  userId: 'abc-123',
+  method: 'email'
+});
+
+await qid.logs.write('Payment failed', 'billing', 'error', {
+  orderId: 'ord-789',
+  reason: 'insufficient_funds'
+});
+```
+
+**Returns:** `{ success: boolean }`
+
+---
+
+### `fetch(query?)`
+
+Retrieve application logs with optional filters.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `query.limit` | `number` | ❌ | — | Max number of logs to return |
+| `query.level` | `string` | ❌ | — | Filter by level |
+
+```typescript
+const logs = await qid.logs.fetch({ level: 'error', limit: 50 });
+```
+
+**Returns:** `any[]`
+
+---
+
+## 🌐 SDK Configuration (`qid.sdk`)
+
+Manage allowed origins for CORS — control which domains can make SDK requests to your project.
+
+### `getOrigins(userToken, tenantId)`
+
+List all allowed origins for the project.
+
+```typescript
+const origins = await qid.sdk.getOrigins(token, tenantId);
+// ['http://localhost:5173', 'https://myapp.com']
+```
+
+**Returns:** `string[]`
+
+---
+
+### `addOrigin(userToken, tenantId, domain)`
+
+Add an allowed origin.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | `string` | ✅ | Origin URL (e.g. `'https://myapp.com'`) |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `removeOrigin(userToken, tenantId, domain)`
+
+Remove an allowed origin.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | `string` | ✅ | Origin URL to remove |
+
+**Returns:** `{ success: boolean; message: string }`
+
+---
+
+### `testOrigin(userToken, tenantId, domain)`
+
+Test if a specific origin is allowed.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | `string` | ✅ | Origin URL to test |
+
+```typescript
+const { allowed } = await qid.sdk.testOrigin(token, tenantId, 'https://myapp.com');
+```
+
+**Returns:** `{ allowed: boolean }`
+
+---
+
+## ⚛️ React Components
+
+The SDK ships with pre-built React components for Post-Quantum authentication.
+
+### `<QidCloudLogin />`
+
+A complete, styled login modal with QR scanning.
+
+```tsx
+import { QidCloudLogin } from '@qidcloud/sdk';
+
+<QidCloudLogin
+  sdk={qid}
+  onSuccess={(user, token) => {
+    console.log('Logged in as', user.username);
+    localStorage.setItem('token', token);
+  }}
+  onError={(error) => console.error(error)}
+  className="my-login-wrapper"
+/>
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `sdk` | `QidCloud` | ✅ | Your initialized SDK instance |
+| `onSuccess` | `(user: QidUser, token: string) => void` | ✅ | Called on successful login |
+| `onError` | `(error: string) => void` | ❌ | Called on error |
+| `className` | `string` | ❌ | CSS class for the wrapper div |
+
+> **Security Note**: This component only supports QR scanning (mobile app). Conventional login is intentionally excluded from the SDK to prevent password transmission in third-party apps.
+
+---
+
+### `<QidSignInButton />`
+
+A minimal sign-in button that opens a QR modal when clicked.
+
+```tsx
+import { QidSignInButton } from '@qidcloud/sdk';
+
+<QidSignInButton
+  sdk={qid}
+  onSuccess={(user, token) => { /* handle login */ }}
+  onError={(err) => console.error(err)}
+  buttonText="Sign in with QidCloud"
+  className="my-btn"
+/>
+```
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `sdk` | `QidCloud` | ✅ | — | SDK instance |
+| `onSuccess` | `(user: QidUser, token: string) => void` | ✅ | — | Success callback |
+| `onError` | `(error: string) => void` | ❌ | — | Error callback |
+| `buttonText` | `string` | ❌ | `'LOGIN WITH QIDCLOUD'` | Button label |
+| `className` | `string` | ❌ | — | CSS class |
+
+---
+
+### `useQidAuth(sdk)`
+
+A React hook for managing the full authentication lifecycle — handshake initialization, WebSocket listeners, session persistence, and auto-restore from localStorage.
+
+```tsx
+import { useQidAuth } from '@qidcloud/sdk';
+
+function App() {
+  const {
+    user,           // QidUser | null
+    token,          // string | null
+    loading,        // boolean — fetching profile
+    error,          // string | null
+    session,        // QidAuthSession | null — active QR session
+    initializing,   // boolean — creating handshake
+    isExpired,      // boolean — QR session expired
+    timeLeft,       // number — seconds until QR expires
+    login,          // () => Promise<void> — start handshake
+    logout,         // () => void — terminate session
+    cancel,         // () => void — cancel handshake
+    setAuthenticated // (user, token) => void — manual auth set
+  } = useQidAuth(qid);
+
+  if (user) return <div>Welcome, {user.username}!</div>;
+
+  return (
+    <div>
+      <button onClick={login}>Login</button>
+      {session && <p>Scan QR... {timeLeft}s remaining</p>}
+      {isExpired && <p>Session expired. <button onClick={login}>Retry</button></p>}
+      {error && <p>Error: {error}</p>}
+    </div>
+  );
+}
+```
+
+| Return Field | Type | Description |
+|-------------|------|-------------|
+| `user` | `QidUser \| null` | Current authenticated user, or `null` |
+| `token` | `string \| null` | JWT session token |
+| `loading` | `boolean` | `true` while fetching user profile |
+| `error` | `string \| null` | Error message if login failed |
+| `session` | `QidAuthSession \| null` | Active QR handshake session |
+| `initializing` | `boolean` | `true` while creating handshake |
+| `isExpired` | `boolean` | `true` if QR session expired |
+| `timeLeft` | `number` | Seconds until QR session expires |
+| `login()` | `() => Promise<void>` | Start a new handshake session |
+| `logout()` | `() => void` | Terminate session and clear state |
+| `cancel()` | `() => void` | Cancel in-progress handshake |
+| `setAuthenticated()` | `(user, token) => void` | Manually set auth state (e.g. traditional login) |
+
+---
+
+## 📋 Type Reference
+
+### `QidConfig`
+
+```typescript
+interface QidConfig {
+  apiKey: string;
+  tenantId?: string;
+  baseUrl?: string;   // Default: 'https://api.qidcloud.com'
+}
+```
+
+### `QidUser`
+
+```typescript
+interface QidUser {
+  userId: string;
+  regUserId: string;
+  username: string;
+  email?: string;
+  role: string;
+  fullName?: string;
+  mfaEnabled?: boolean;
+  createdAt?: Date;
+}
+```
+
+### `QidSession`
+
+```typescript
+interface QidSession {
+  token: string;
+  lastActive: Date;
+  ip?: string;
+  userAgent?: string;
+}
+```
+
+### `QidAuthSession`
+
+```typescript
+interface QidAuthSession {
+  sessionId: string;
+  qrData: string;      // Stringified QR data for mobile app scanning
+  expiresAt: number;    // Milliseconds since epoch
+}
+```
+
+### `QidDbResponse<T = any>`
+
+```typescript
+interface QidDbResponse<T = any> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  count?: number;
+  meta?: any;
+}
+```
+
+### `QidEdgeResponse`
+
+```typescript
+interface QidEdgeResponse {
+  success: boolean;
+  result: any;          // Return value from exports.handler
+  computeTime: string;  // e.g. '12ms'
+  logs?: string[];      // Console output from the function
+}
+```
+
+### `QidFile`
+
+```typescript
+interface QidFile {
+  fileId: string;
+  originalName: string;
+  mimeType: string;
+  size: number;           // bytes
+  createdAt: string;
+  clientMetadata?: any;
+}
+```
+
+### `QidUploadResponse`
+
+```typescript
+interface QidUploadResponse {
+  success: boolean;
+  message: string;
+  file: {
+    id: string;
+    name: string;
+    url: string;          // Relative URL, prefix with baseUrl to access
+  };
+}
+```
+
+### `QidProject`
+
+```typescript
+interface QidProject {
+  _id: string;
+  name: string;
+  tenantId: string;
+  apiKey: string;
+  owner: string;
+  tier: 'free' | 'pro' | 'elite' | 'enterprise';
+  status: 'active' | 'suspended' | 'pending';
+}
+```
+
+### `QidProjectSettings`
+
+```typescript
+interface QidProjectSettings {
+  displayName?: string;
+  allowedOrigins?: string[];
+  enclaveConfig?: any;
+}
+```
+
+### `QidResourceStatus`
+
+```typescript
+interface QidResourceStatus {
+  resourceType: string;
+  status: 'active' | 'provisioning' | 'failed' | 'dissolved';
+  endpoint?: string;
+  details?: any;
+}
+```
+
+### `QidBillingInfo`
+
+```typescript
+interface QidBillingInfo {
+  plan: string;
+  profile: string;
+  estimatedMonthly: number;
+  estimatedHourly: string;
+  infraValueUSD: string;
+  currency: string;
+  activeEnclaves: string[];
+  billingNote?: string;
+}
+```
+
+### `QidTransaction`
+
+```typescript
+interface QidTransaction {
+  transactionId: string;
+  amount: number;
+  date: string;
+  status: string;
+  planId: string;
+  currency?: string;
+}
+```
+
+### `QidBillingAlert`
+
+```typescript
+interface QidBillingAlert {
+  _id: string;
+  resource: string;
+  threshold: number;
+  status: string;
+}
+```
+
+### `QidMigration`
+
+```typescript
+interface QidMigration {
+  version: string;              // Unique version identifier (e.g. '001', '002')
+  name: string;                 // Human-readable name (e.g. 'create_users_table')
+  up: () => Promise<void>;      // Async function that applies the migration
+}
+```
+
+### `QidMigrateResult`
+
+```typescript
+interface QidMigrateResult {
+  success: boolean;
+  applied: string[];            // Versions applied this run
+  skipped: string[];            // Versions already applied previously
+  failed?: {
+    version: string;
+    error: string;
+  };
+  total: number;                // Total migrations in the registry
+}
+```
+
+---
+
+## ❌ Error Handling
+
+All SDK methods throw on network errors. Catch them with try/catch:
+
+```typescript
+try {
+  const result = await qid.db.query('SELECT * FROM users');
+} catch (err) {
+  // Network error, 401 Unauthorized, 403 Forbidden, etc.
+  console.error(err.response?.status, err.response?.data);
+}
+```
+
+For methods that return `{ success, error }`, check the `success` field:
+
+```typescript
+const result = await qid.db.query('SELECT * FROM nonexistent');
+if (!result.success) {
+  console.error('Query failed:', result.error);
+}
+```
+
+---
+
+## 📄 License
+
+ISC License — © 2026 QidCloud Enclave Security.