# Client SDK quickstart

> Install the client SDK, send your first message, and stream a response.

Source: https://maincode.com/docs/client-sdk-overview
Section: Client SDK · Matilda documentation

---

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](https://maincode.com/docs/agent-sdk-agent)
- **Session class** — multi-turn conversations are managed via `conversationId`; see [Multi-turn conversations](https://maincode.com/docs/client-sdk-multi-turn)

## Installation

**npm**

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

**pnpm**

```bash
pnpm add @maincode-ai/matilda-client-sdk
```

**yarn**

```bash
yarn add @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](https://maincode.com/docs/client-sdk-structured-output)):

```bash
npm install zod
```

### ESM import

```ts title="index.ts"
import Matilda from '@maincode-ai/matilda-client-sdk';
```

### CommonJS require

```js title="index.js"
const { Matilda } = require('@maincode-ai/matilda-client-sdk');
```

### Auth subpath (Node-only)

The standalone auth helpers are available via a subpath import:

```ts title="node.ts"
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):

```ts title="node.ts"
import {
  createLoginFlow,
  createTokenManager,
  createFileTokenStore,
  fetchAuthServerMetadata,
  memoryStorage,
} from '@maincode-ai/matilda-client-sdk/auth/node';
```

## Quick start

### Send a message

```ts title="chat.ts"
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);
```

> **Note** — The `accessToken` option above is fine for quick testing, but for production use we recommend the managed auth flows (`loginWithBrowser` or `loginWithDeviceFlow`), which auto-wire a `TokenManager` with automatic token refresh. See [Authentication](https://maincode.com/docs/client-sdk-authentication).

### Stream a response

```ts title="stream.ts"
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

```ts title="device-flow.ts"
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

| Environment | Base URL |
| - | - |
| Production | `https://matilda.maincode.com/api` |