# @arbidocs/sdk

TypeScript SDK for the ARBI platform. Handles authentication, workspace encryption, and streaming AI queries.

## Quickstart

```bash
npm install @arbidocs/sdk
```

```typescript
import { Arbi } from '@arbidocs/sdk/browser'

const arbi = new Arbi({ url: 'https://www.arbidocs.com' })

// Login and select a workspace
await arbi.login('user@example.com', 'password')
const workspaces = await arbi.workspaces.list()
await arbi.selectWorkspace(workspaces[0].external_id)

// Ask a streaming question about your documents
const docs = await arbi.documents.list()
await arbi.assistant.query('Summarize this document', {
  docIds: [docs[0].external_id],
  onToken: (token) => process.stdout.write(token),
})
```

For Node.js, install `fake-indexeddb` and import it first:

```typescript
import 'fake-indexeddb/auto'
import { Arbi } from '@arbidocs/sdk'
```

## Lifecycle

```typescript
const arbi = new Arbi({ url: 'https://www.arbidocs.com' })

await arbi.login(email, password)            // or arbi.loginWithKey(email, keyBase64)
await arbi.selectWorkspace(workspaceId)
// ... use the SDK ...
await arbi.logout()
```

| Property | Description |
|----------|-------------|
| `arbi.isLoggedIn` | Whether the user is authenticated |
| `arbi.hasWorkspace` | Whether a workspace is selected |

## Operations

| Namespace | Key methods |
|-----------|-------------|
| `arbi.workspaces` | `list()`, `create()`, `update()`, `delete()`, `listUsers()`, `addUsers()`, `removeUsers()` |
| `arbi.documents` | `list()`, `get()`, `uploadFile()`, `uploadUrl()`, `update()`, `delete()`, `download()` |
| `arbi.conversations` | `list()`, `getThreads()`, `updateTitle()`, `share()`, `delete()` |
| `arbi.assistant` | `query(question, options)`, `retrieve(query, docIds)`, `respond(messageId, answer)` |
| `arbi.tags` | `list()`, `create()`, `update()`, `delete()` |
| `arbi.doctags` | `assign()`, `remove()`, `generate()` |
| `arbi.contacts` | `list()`, `add()`, `remove()` |
| `arbi.health` | `check()`, `models()`, `mcpTools()` |

## Streaming AI queries

```typescript
const result = await arbi.assistant.query('What does section 3 say?', {
  docIds: [docId],
  previousResponseId: lastMessageId,   // for multi-turn conversations
  onToken: (token) => { /* append to UI */ },
  onStreamStart: ({ assistant_message_ext_id }) => { /* save for follow-ups */ },
  onAgentStep: (step) => { /* agent tool usage */ },
  onError: (message) => { /* handle error */ },
  onComplete: () => { /* done */ },
})

// result.text — full accumulated response
// result.assistantMessageExtId — use as previousResponseId for follow-ups
```

## Session recovery

The SDK persists the signing key (encrypted) in IndexedDB. Recover a session without a password:

```typescript
await arbi.loginWithKey('user@example.com', signingKeyBase64)
```

The SDK also auto-recovers on 401 responses using the stored key.

## Security

- **Zero-knowledge auth** — passwords never leave the client
- **E2E workspace encryption** — symmetric keys wrapped with your public key
- **Encrypted key storage** — private keys in IndexedDB encrypted with non-extractable AES-GCM
- **Key zeroing on logout** — signing and session keys scrubbed from memory

## React

For React apps, use `@arbidocs/react` instead — it wraps this SDK with hooks and a context provider. See the [@arbidocs/react README](../arbi-react/README.md).

## Requirements

- **Browser**: Any modern browser with Web Crypto API
- **Node.js**: v18+ (install `fake-indexeddb`)
- **TypeScript**: 5.0+ (optional)