@maincode-ai/matilda-client-sdk

Small public TypeScript SDK for Matilda clients. Ships a self-contained dual ESM + CommonJS build with bundled types; no @matilda/* runtime dependencies.

Installation

npm install @maincode-ai/matilda-client-sdk
# or: pnpm add @maincode-ai/matilda-client-sdk

Requires Node.js >= 20.

Usage

import Matilda from '@maincode-ai/matilda-client-sdk';

const client = new Matilda({ baseUrl: '/api' });

const response = await client.chat.create({ input: 'Summarize this thread.' });
console.log(response.outputText);

for await (const event of client.chat.stream({ input: 'Write a short plan.' })) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

The SDK follows the OpenAI client shape where it helps: constructor config, resource groups, request options, typed API errors, and async iterable streaming. It does not expose model/provider selection. Matilda core owns routing, safety, resumable SSE, server-side tool execution, and policy.

Auth helpers (/auth)

OAuth helpers (PKCE browser-login + RFC 8628 device flow) are also exposed as a standalone, Node-only subpath so integrators never reimplement the PKCE crypto, loopback server, or device-flow polling:

import { loginWithBrowser, loginWithDeviceFlow } from '@maincode-ai/matilda-client-sdk/auth';

They are additionally reachable via client.auth.* on a Matilda instance.

Configuration model

Each Matilda instance holds its own independent config — constructor options and configure() writes are scoped to that instance, not shared across instances in the same process:

const staging = new Matilda({ baseUrl: 'https://staging.example/api' });
const prod = new Matilda({ baseUrl: 'https://prod.example/api' });

// staging and prod are fully isolated — each keeps its own baseUrl:
console.log(staging.config.baseUrl); // https://staging.example/api
console.log(prod.config.baseUrl);    // https://prod.example/api

// Reconfiguring one never affects the other:
staging.configure({ baseUrl: 'https://override.example/api' });
console.log(staging.config.baseUrl); // https://override.example/api
console.log(prod.config.baseUrl);    // https://prod.example/api (unchanged)

This makes it safe to hold multiple differently configured clients (e.g. staging vs. prod, or per-tenant routing) in a single process. configure() returns the instance for chaining:

staging.configure({ baseUrl: 'https://staging.example/api' }).chat.create(/* … */);

Client-executed tools

This package targets app and browser-adjacent integrations. It intentionally exposes Matilda's normal chat/events surface, not the local client-tool loop used by terminal agents. If you need client-side tool execution (clientTools, local approval/sandbox loops, tool-result continuation), use the Matilda agent SDK.