@holokai/moku-sdk

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

Installation

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

Quick Start

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

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):

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:

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:

// 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

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

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

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