@arbidocs/sdk 0.3.8 → 0.3.10

package/README.md

@@ -1,6 +1,6 @@
 # @arbidocs/sdk
 
-TypeScript SDK for the ARBI API — zero-knowledge auth, E2E encryption, and type-safe REST client.
+High-level TypeScript SDK for the ARBI platform. Wraps authentication, workspace encryption, and all API operations into a single `Arbi` class.
 
 ## Install
 
@@ -8,7 +8,7 @@ TypeScript SDK for the ARBI API — zero-knowledge auth, E2E encryption, and typ
 npm install @arbidocs/sdk
 ```
 
-For Node.js environments (no browser), also install the IndexedDB polyfill:
+For Node.js, also install the IndexedDB polyfill:
 
 ```bash
 npm install fake-indexeddb
@@ -17,279 +17,114 @@ npm install fake-indexeddb
 ## Quick Start
 
 ```typescript
-import { createArbiClient } from '@arbidocs/sdk'
+import 'fake-indexeddb/auto' // Node.js only
+import { Arbi } from '@arbidocs/sdk'
 
-const arbi = createArbiClient({
-  baseUrl: 'https://box-201.arbibox.com',
-  deploymentDomain: 'box-201.arbibox.com',
-})
+const arbi = new Arbi({ url: 'https://arbi.mycompany.com' })
 
 // Login
-const session = await arbi.auth.login({
-  email: 'user@example.com',
-  password: 'mypassword',
-})
-
-// Type-safe API calls — auto-injects Bearer token
-const { data: workspaces } = await arbi.fetch.GET('/api/user/workspaces')
-console.log(workspaces) // WorkspaceResponse[]
-```
+await arbi.login('user@example.com', 'password')
 
-## Examples
-
-### Register + Login (Node.js)
-
-```javascript
-// Polyfill IndexedDB for Node.js (must be first import)
-require('fake-indexeddb/auto')
-const { createArbiClient } = require('@arbidocs/sdk')
-
-async function main() {
-  const arbi = createArbiClient({
-    baseUrl: 'https://box-201.arbibox.com',
-    deploymentDomain: 'box-201.arbibox.com',
-    credentials: 'omit', // No cookies in Node.js
-  })
-
-  // Register a new user
-  const { signingPrivateKey } = await arbi.auth.register({
-    email: 'alice@example.com',
-    password: 'SecurePass123!',
-    verificationCode: '...', // From /api/user/verify-email flow
-    firstName: 'Alice',
-    lastName: 'Smith',
-  })
-
-  // Login
-  const session = await arbi.auth.login({
-    email: 'alice@example.com',
-    password: 'SecurePass123!',
-  })
-
-  console.log('Logged in as', session.userExtId)
-  console.log('Token:', session.accessToken.slice(0, 20) + '...')
-}
-
-main()
-```
+// Pick a workspace
+const workspaces = await arbi.workspaces.list()
+await arbi.selectWorkspace(workspaces[0].external_id)
 
-### Create a Workspace and Upload a Document
-
-```javascript
-require('fake-indexeddb/auto')
-const fs = require('fs')
-const {
-  createArbiClient,
-  getSession,
-  sealedBoxDecrypt,
-  deriveEncryptionKeypairFromSigning,
-  createWorkspaceKeyHeader,
-} = require('@arbidocs/sdk')
-
-async function main() {
-  const arbi = createArbiClient({
-    baseUrl: 'https://box-201.arbibox.com',
-    deploymentDomain: 'box-201.arbibox.com',
-    credentials: 'omit',
-  })
-
-  // Login
-  const { accessToken, serverSessionKey } = await arbi.auth.login({
-    email: 'alice@example.com',
-    password: 'SecurePass123!',
-  })
-
-  // Create workspace
-  const { data: workspace } = await arbi.fetch.POST('/api/workspace/create_protected', {
-    body: {
-      name: 'My Case Files',
-      description: 'Documents for Case #1234',
-      is_public: false,
-    },
-  })
-
-  // Decrypt the workspace key and generate the auth header.
-  // The server wraps the workspace symmetric key with your public key
-  // during creation. You unwrap it here to prove you own the workspace.
-  const session = await getSession()
-  const pubKey = session.signingPrivateKey.slice(32, 64)
-  const encKP = deriveEncryptionKeypairFromSigning({
-    publicKey: pubKey,
-    secretKey: session.signingPrivateKey,
-  })
-  const workspaceKey = sealedBoxDecrypt(workspace.wrapped_key, encKP.secretKey)
-  const wsHeader = await createWorkspaceKeyHeader(workspaceKey, serverSessionKey)
-
-  // Tell the SDK which workspace is active (middleware auto-injects the header)
-  arbi.session.setSelectedWorkspace(workspace.external_id)
-  arbi.session.setCachedWorkspaceHeader(workspace.external_id, wsHeader)
-
-  // Upload a PDF (multipart — use raw fetch since openapi-fetch
-  // doesn't handle multipart/form-data)
-  const formData = new FormData()
-  const pdf = fs.readFileSync('./contract.pdf')
-  formData.append('files', new Blob([pdf], { type: 'application/pdf' }), 'contract.pdf')
-
-  const uploadRes = await fetch(
-    `https://box-201.arbibox.com/api/document/upload?workspace_ext_id=${workspace.external_id}`,
-    {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        'workspace-key': wsHeader,
-      },
-      body: formData,
-    }
-  )
-
-  const { doc_ext_ids } = await uploadRes.json()
-  console.log('Uploaded document:', doc_ext_ids[0])
-
-  // List documents (workspace-key header injected automatically by middleware)
-  const { data: docs } = await arbi.fetch.GET(
-    '/api/workspace/{workspace_ext_id}/documents',
-    { params: { path: { workspace_ext_id: workspace.external_id } } }
-  )
-
-  for (const doc of docs) {
-    console.log(`  ${doc.file_name} — ${doc.status}`)
-  }
-}
-
-main()
+// Use it
+const docs = await arbi.documents.list()
+const tags = await arbi.tags.list()
+const conversations = await arbi.conversations.list()
 ```
 
-### Subscribe to Session State Changes
-
-The SDK's `SessionManager` supports a subscribe pattern for reactive updates:
+## Streaming AI Queries
 
 ```typescript
-const arbi = createArbiClient({ baseUrl, deploymentDomain })
-
-// React to session changes (useful for custom UI frameworks)
-const unsubscribe = arbi.session.subscribe((state) => {
-  console.log('Session changed:', {
-    loggedIn: !!state.accessToken,
-    email: state.userEmail,
-    workspace: state.selectedWorkspaceId,
-  })
+const result = await arbi.assistant.query('What does section 3 say?', {
+  docIds: [docs[0].external_id],
+  onToken: (token) => process.stdout.write(token),
+  onStreamStart: ({ assistant_message_ext_id }) => {
+    console.log('Stream started:', assistant_message_ext_id)
+  },
+  onComplete: () => console.log('\nDone'),
 })
-
-// Later: stop listening
-unsubscribe()
 ```
 
-## API Reference
-
-### `createArbiClient(options)`
+## Session Recovery
 
-Creates an SDK client instance.
+After login, the SDK automatically persists your signing key (encrypted) in IndexedDB. You can also recover a session using the raw private key:
 
 ```typescript
-interface ArbiClientOptions {
-  baseUrl: string              // ARBI API URL (e.g. "https://box-201.arbibox.com")
-  deploymentDomain: string     // Used for deterministic key derivation
-  credentials?: RequestCredentials  // Default: 'include'. Use 'omit' for Node.js
-  ssoTokenProvider?: { getToken(): Promise<string | null> } | null
-  onReloginSuccess?: (data) => void
-}
-```
+// Save the key after first login (e.g. the recovery key download)
+const signingKeyBase64 = '...'
 
-Returns an `ArbiClient` with these namespaces:
+// Later, recover without password:
+await arbi.loginWithKey('user@example.com', signingKeyBase64)
+```
 
-| Namespace | Description |
-|-----------|-------------|
-| `arbi.fetch` | Type-safe `openapi-fetch` client with auto-auth middleware |
-| `arbi.session` | In-memory session state (token, user, workspace) |
-| `arbi.auth` | High-level auth: `register`, `login`, `loginWithKey`, `logout`, `changePassword`, `relogin` |
-| `arbi.crypto` | Crypto utilities: key derivation, signing, encryption, base64 |
-| `arbi.storage` | IndexedDB session persistence: `getSession`, `saveSession` |
+## API Reference
 
-### Auth Methods
+### Constructor
 
 ```typescript
-// Register
-await arbi.auth.register({ email, password, verificationCode, firstName?, lastName? })
-
-// Login with password
-await arbi.auth.login({ email, password })
-
-// Login with recovery key (Uint8Array)
-await arbi.auth.loginWithKey({ email, signingPrivateKey })
-
-// Change password
-await arbi.auth.changePassword({ email, currentPassword, newPassword })
-
-// Logout (clears session + IndexedDB)
-await arbi.auth.logout()
-
-// Re-login using stored private key (auto-called by middleware on 401)
-await arbi.auth.relogin()
+const arbi = new Arbi({
+  url: 'https://arbi.mycompany.com',     // Required: backend URL
+  deploymentDomain: 'arbi.mycompany.com', // Optional: defaults to URL hostname
+  credentials: 'omit',                    // Optional: 'omit' | 'include' | 'same-origin'
+})
 ```
 
-### Middleware (Auto-Applied)
-
-The `arbi.fetch` client has three middleware layers applied automatically:
+### Lifecycle
 
-1. **Bearer Auth** — injects `Authorization: Bearer <token>` on every request
-2. **Workspace Key** — injects `workspace-key` header for workspace-scoped endpoints
-3. **Auto-Relogin** — on 401, re-derives credentials from stored key and retries
+| Method | Description |
+|--------|-------------|
+| `login(email, password)` | Authenticate with email and password |
+| `loginWithKey(email, signingKeyBase64)` | Authenticate with a stored signing key |
+| `selectWorkspace(workspaceId)` | Select a workspace (decrypts workspace key) |
+| `logout()` | Log out and securely clear key material |
 
-### Standalone Exports
+### Properties
 
-All building blocks are individually importable for advanced use:
+| Property | Type | Description |
+|----------|------|-------------|
+| `isLoggedIn` | `boolean` | Whether the user is authenticated |
+| `hasWorkspace` | `boolean` | Whether a workspace is selected |
 
-```typescript
-import {
-  // Crypto primitives
-  initSodium, signMessage, sealedBoxDecrypt, sealedBoxEncrypt,
-  deriveEncryptionKeypairFromSigning, createWorkspaceKeyHeader,
-  generateUserKeypairs, generateLoginCredentials,
-  encryptMessage, decryptMessage,
-  base64Encode, base64Decode, base64ToBytes, bytesToBase64,
+### Operations
 
-  // Storage
-  getSession, saveSession, clearAllData, hasSession,
+All operations are namespaced and require a workspace to be selected (except `workspaces` and `health`).
 
-  // Middleware (compose your own client)
-  createBearerAuthMiddleware, createWorkspaceKeyMiddleware, createAutoReloginMiddleware,
+| Namespace | Methods |
+|-----------|---------|
+| `arbi.workspaces` | `list()`, `create()`, `update()`, `delete()`, `listUsers()`, `addUsers()`, `removeUsers()`, `setUserRole()` |
+| `arbi.documents` | `list()`, `get()`, `upload()`, `update()`, `delete()` |
+| `arbi.conversations` | `list()`, `getThreads()`, `updateTitle()`, `share()`, `delete()` |
+| `arbi.assistant` | `query(question, options)`, `retrieve(messageExtId)` |
+| `arbi.tags` | `list()`, `create()`, `update()`, `delete()` |
+| `arbi.doctags` | `assign()`, `remove()` |
+| `arbi.contacts` | `list()`, `search()` |
+| `arbi.health` | `check()` |
 
-  // Relogin handler
-  createReloginHandler,
+### Browser Entry Point
 
-  // Session manager
-  createSessionManager,
+For browser environments (no Node.js APIs like `fs`), import from the browser entry:
 
-  // OpenAPI schema types
-  type paths, type components, type operations,
-} from '@arbidocs/sdk'
+```typescript
+import { Arbi } from '@arbidocs/sdk/browser'
 ```
 
-## How It Works
-
-### Zero-Knowledge Auth
-
-ARBI uses Ed25519 signatures for authentication. Your password never leaves the client:
+## Security
 
-1. **Key derivation**: `Argon2id(email + password + deploymentDomain)` → Ed25519 seed → signing keypair
-2. **Registration**: Public key sent to server, private key stays local
-3. **Login**: Client signs a timestamp, server verifies the signature
-4. **Session**: Server returns an encrypted session key for workspace operations
+- **Zero-knowledge auth**: Passwords never leave the client. Ed25519 keys are derived locally via Argon2id.
+- **E2E workspace encryption**: Each workspace has a symmetric key, wrapped with your public key.
+- **Encrypted key storage**: Private keys in IndexedDB are encrypted with a non-extractable Web Crypto AES-GCM key.
+- **Key zeroing on logout**: Signing and session keys are scrubbed from memory on logout.
 
-### Workspace Encryption
-
-Each workspace has a symmetric key (NaCl SecretBox). The key is:
-- Generated server-side on workspace creation
-- Wrapped with your X25519 public key (derived from your Ed25519 signing key)
-- Unwrapped client-side using `sealedBoxDecrypt`
-- Used to generate per-request `workspace-key` headers (HMAC proof of key possession)
-
-### IndexedDB Storage
+## Examples
 
-The SDK stores the signing private key and session key in IndexedDB, encrypted with a non-extractable AES-GCM key from the Web Crypto API. In Node.js, use `fake-indexeddb` as a polyfill.
+- **[Node.js Hello World](../../examples/node-hello-world/)** — Login, list docs, ask a streaming question (~40 lines)
+- **[React Chat App](../../examples/react-chat/)** — Login form, workspace selector, document picker, streaming chat
 
 ## Requirements
 
-- **Browser**: Any modern browser (Chrome, Firefox, Safari, Edge)
-- **Node.js**: v18+ (needs `fetch`, `FormData`, `Blob` globals). Install `fake-indexeddb` for IndexedDB.
-- **TypeScript**: 5.0+ (optional — works with plain JS too)
+- **Browser**: Any modern browser with Web Crypto API
+- **Node.js**: v18+ (needs `fetch`, `FormData`, `Blob` globals). Install `fake-indexeddb`.
+- **TypeScript**: 5.0+ (optional)