npm package: @holokai/moku-sdk
Description: TypeScript SDK for the Moku API
Author: Holokai
Latest version: 1.3.2

# @holokai/moku-sdk

TypeScript SDK for the Moku API. Provides a typed client with namespace-based access to all Moku endpoints.

## Installation

```bash
npm install @holokai/moku-sdk @holokai/moku-types
```

## Quick Start

```typescript
import {MokuClient} from '@holokai/moku-sdk';

const client = new MokuClient({
    baseUrl: 'https://your-moku-instance.com',
    token: 'your-api-token',
});

const threads = await client.threads.list({page: 0, size: 10});
console.log(threads.content);
```

## Configuration

```typescript
interface MokuClientOptions {
    baseUrl: string;
    token?: string | (() => string | Promise<string>);
    fetch?: typeof globalThis.fetch;
    timeout?: number; // default: 10000ms
}
```

### Dynamic Token

Pass a function to resolve the token at request time (useful for OAuth refresh flows):

```typescript
const client = new MokuClient({
    baseUrl: 'https://your-moku-instance.com',
    token: async () => {
        const session = await getSession();
        return session.accessToken;
    },
});
```

## Namespaces

All API endpoints are organized into namespaces on the client:

| Namespace | Description |
|-----------|-------------|
| `auth` | Authentication, user identity, OAuth providers |
| `applications` | Application CRUD, history, filters |
| `providers` | LLM provider configuration, connectivity tests, model sync |
| `models` | AI model management |
| `organizations` | Organization management, BYOK, segments |
| `teams` | Team hierarchy, user assignment, tree navigation |
| `users` | User accounts, roles, status |
| `credentials` | API credentials, vault secrets |
| `prompts` | Prompt templates, versioning, tag filtering |
| `projects` | Project management, members, roles |
| `pricing` | Pricing plans, sheets, per-model costs |
| `plugins` | Plugin discovery and metadata |
| `datasets` | Evaluation datasets, samples |
| `evaluations` | Evaluation plans, sessions, results, analytics |
| `dashboards` | Dashboard CRUD, generation, settings |
| `analytics` | Query execution, widget generation |
| `servers` | Server status and proxy info |
| `monitoring` | Request monitoring, RabbitMQ metrics, health |
| `audit` | Change history, user revisions |
| `schemas` | JSON schema management, versioning, migrations |
| `threads` | Conversation threads, messages |
| `agents` | AI agent configuration |
| `ref` | Reference data (teams, roles, providers, models) |

## Common Patterns

### Paged Responses

List endpoints return `PagedResponse<T>` with standard pagination metadata:

```typescript
const result = await client.applications.list({page: 0, size: 20, search: 'my-app'});
console.log(result.content);        // T[]
console.log(result.totalElements);   // total count
console.log(result.totalPages);      // total pages
```

### CRUD Convention

Most namespaces follow a standard pattern:

```typescript
// List
const items = await client.projects.list({page: 0, size: 10});

// Get by ID
const project = await client.projects.getById('uuid');

// Create
const created = await client.projects.create({name: 'New Project'});

// Update (PATCH where applicable)
const updated = await client.projects.update('uuid', {name: 'Renamed'});

// Delete
await client.projects.remove('uuid');
```

### Thread Management

```typescript
const thread = await client.threads.create({title: 'My Thread'});

// Update uses PATCH semantics — only send changed fields
await client.threads.update(thread.id!, {title: 'Renamed'});

// Filter by type
const personal = await client.threads.list({type: 'personal'});

// Get messages
const messages = await client.threads.getMessages(thread.id!, {page: 0, size: 50});

await client.threads.remove(thread.id!);
```

### Schema Versioning

```typescript
const schemas = await client.schemas.list({search: 'user-profile'});

const detail = await client.schemas.getById('schema-uuid');
const versions = await client.schemas.getVersions('schema-uuid');

// Get a version directly by ID
const version = await client.schemas.getVersionById('version-uuid');

// Suggest next version number
const suggestion = await client.schemas.suggestNextVersion({schemaId: 'uuid'});

// Create version with migration
const result = await client.schemas.createVersionWithMigration('schema-uuid', {
    version: '2.0.0',
    content: {/* schema JSON */},
    changeSummary: 'Added email field',
    migrationStrategy: 'AUTO',
});
```

## Error Handling

```typescript
import {MokuApiError, MokuTimeoutError} from '@holokai/moku-sdk';

try {
    await client.applications.getById('nonexistent');
} catch (err) {
    if (err instanceof MokuApiError) {
        console.error(`HTTP ${err.status}:`, err.body);
    } else if (err instanceof MokuTimeoutError) {
        console.error(`Timed out after ${err.timeoutMs}ms`);
    }
}
```

## License

MIT