Client SDK quickstart.

A small, self-contained TypeScript SDK for building Matilda clients. Ships a dual ESM + CommonJS build with bundled type definitions and zero @matilda/* runtime dependencies. Requires Node.js 20 or later. This guide covers SDK version 0.2.0.

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 or provider selection — Matilda core owns routing, safety, resumable SSE, server-side tool execution, and policy.

What's included

• Chat — non-streaming, full-event streaming, text-only streaming, schema-constrained structured output, and durable stream resume
• Conversations — list, retrieve, rename, and set message feedback
• Files — upload (single and parallel), retrieve metadata
• Feedback — report harmful content and submit response feedback
• Devices — register, list, and unregister push notification devices
• Auth — managed PKCE browser login, RFC 8628 device flow, token refresh, and persistent token storage
• API keys — create, list, and revoke mc_live_ API keys via SDK methods or the matilda-key CLI

What's not included

• Local tool-execution loop — for client-side tool execution (clientTools, local approval/sandbox loops, tool-result continuation), use the agent SDK
• Session class — multi-turn conversations are managed via conversationId; see Multi-turn conversations

Installation

npm install @maincode-ai/matilda-client-sdk

zod (v3.25+) is a required peer dependency — install it alongside the SDK. It is used by the structured-output helpers (Structured output):

npm install zod

ESM import

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

CommonJS require

const { Matilda } = require('@maincode-ai/matilda-client-sdk');

Auth subpath (Node-only)

The standalone auth helpers are available via a subpath import:

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

For the full Node auth surface (token manager, file store, loopback receiver, login flow controller):

import {
  createLoginFlow,
  createTokenManager,
  createFileTokenStore,
  fetchAuthServerMetadata,
  memoryStorage,
} from '@maincode-ai/matilda-client-sdk/auth/node';

Quick start

Send a message

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

const client = new Matilda({
  baseUrl: 'https://matilda.maincode.com/api',
  accessToken: process.env.MATILDA_ACCESS_TOKEN!,
});

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

Stream a response

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);
  }
}

Authenticated: device flow and chat

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

const client = new Matilda({ baseUrl: 'https://matilda.maincode.com/api' });

// Authenticate via RFC 8628 device flow — prints a code to stderr
await client.auth.loginWithDeviceFlow({ clientId: 'matilda-code' });

// Token is now managed automatically — no manual header wiring
const response = await client.chat.create({ input: 'Hello, Matilda!' });
console.log(response.outputText);

Environment URLs