@getmodus/sdk 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,8 +1,19 @@
 # Changelog
 
-**Current npm release:** [`0.2.0`](https://www.npmjs.com/package/@getmodus/sdk/v/0.2.0).
+**Current npm release:** [`0.2.2`](https://www.npmjs.com/package/@getmodus/sdk/v/0.2.2).
 
 
+## [Unreleased]
+
+## [0.2.2] — 2026-07-20
+
+## [0.2.1] — 2026-07-20
+
+### Changed
+
+- Public README brought to parity with the Python SDK guide (product framing, auth, Modus vs scopes, chat/stream/context, management, pagination, errors).
+- Added `assets/modus-logo.png` / `.svg` for GitHub mirror and package docs.
+
 ## [0.2.0] — 2026-07-20
 
 ### Added
@@ -26,8 +37,6 @@
 
 - Legacy **`client.skills` / `client.agents`** and **`mgmt.skills` / `mgmt.agents`** accessors — use `scopes` / `workflows`.
 
-## [Unreleased]
-
 ## [0.1.0] — 2026-07-20
 
 ### Added

package/README.md

@@ -1,79 +1,226 @@
-# @getmodus/sdk
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/modus-data/modus-sdk-typescript/main/assets/modus-logo.png"
+    alt="Modus"
+    width="280"
+  />
+</p>
 
-Official TypeScript client for Modus (pre-release).
+# Modus TypeScript SDK
+
+[![npm](https://img.shields.io/npm/v/@getmodus/sdk)](https://www.npmjs.com/package/@getmodus/sdk)
+[![Node.js](https://img.shields.io/node/v/@getmodus/sdk)](https://www.npmjs.com/package/@getmodus/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official TypeScript / JavaScript client for Modus — your organization's context layer for AI.
 
 **Runtime:** Node.js 18+. Ships **ESM** and **CommonJS**. Not intended for browsers or edge runtimes (uses Node APIs such as `process.env`).
 
-## Install (coming soon)
+## What is Modus?
+
+Modus is your organization's context layer: it connects assistants to curated knowledge about your data, systems, and workflows so answers use org-specific context instead of generic guesses.
+
+- **Modus** — your org-wide assistant (same capability as the Modus home page)
+- **Scopes** — published assistants you chat with, each with its own context and tools
+- **Workflows** — automations that run on a schedule or trigger
+- **Context items** — curated knowledge Modus composes at runtime when answering
+
+## Two clients in one package
+
+**`Modus`** is what most people need. Use it to chat with Modus, run scopes, browse context, and inspect workflow runs — the same things you do in the Modus app day to day.
+
+**`ModusManagement`** (`@getmodus/sdk/management`) is for org setup: create, update, and deploy scopes, workflows, and context — the CRUD operations you would use in the Modus UI as an admin.
+
+If you are getting started, use `Modus` only. Reach for `ModusManagement` when you are automating configuration.
+
+## Installation
 
 ```bash
-npm install @getmodus/sdk@beta
+npm install @getmodus/sdk
 ```
 
-## Usage
-
-### ESM (`import`)
+## Getting started
 
 ```ts
 import { Modus } from '@getmodus/sdk'
-import { ModusManagement } from '@getmodus/sdk/management'
 
-const client = new Modus({ apiKey: process.env.MODUS_API_KEY })
-const mgmt = new ModusManagement({ apiKey: process.env.MODUS_API_KEY })
+// Reads MODUS_API_KEY from the environment, or pass apiKey explicitly
+const client = new Modus()
+
+for await (const scope of (await client.scopes.list()).autoPagingIter()) {
+  console.log(scope.name, scope.status)
+}
+
+const scope = await client.scopes.get('revenue-analysis')
+console.log(scope.name, scope.description)
 
-const scopes = await client.scopes.list()
-const draft = await mgmt.scopes.create({ name: 'Analyst', model: 'claude-sonnet-5' })
+for await (const item of (await client.context.items.list()).autoPagingIter()) {
+  console.log(item.uid, item.contextType, item.description ?? item.uid)
+}
 ```
 
 ### CommonJS (`require`)
 
 ```js
 const { Modus } = require('@getmodus/sdk')
-const { ModusManagement } = require('@getmodus/sdk/management')
-
 const client = new Modus({ apiKey: process.env.MODUS_API_KEY })
 ```
 
-## Examples
-
-Runnable scripts (mirrored to the public GitHub repo):
+## Authentication
 
-- `examples/scripts/quickstart.ts` — list scopes and context (`Modus`)
-- `examples/scripts/modus_chat.ts` — buffered and streaming Modus chat, context compose, conversations
-- `examples/scripts/chat.ts` — buffered scope chat with thread follow-up
-- `examples/scripts/manage_skill.ts` — create and deploy a scope (`ModusManagement`, `--write` optional)
+Create an API token in the Modus app (**Settings → API Tokens** on your Modus home page). Prefer an environment variable over hardcoding keys in source:
 
 ```bash
 export MODUS_API_KEY=modus_xxx
-npx tsx examples/scripts/quickstart.ts
 ```
 
-From the Modus monorepo (after build):
+```ts
+const client = new Modus({ apiKey: 'modus_xxx' })
+```
 
-```bash
-pnpm nx run modus-sdk-typescript:build
-MODUS_API_KEY=modus_xxx node --import tsx distribution/clients/typescript/modus-sdk/examples/scripts/quickstart.ts
+## Using Modus
+
+### Modus vs scopes
+
+| Surface | SDK | Use when |
+|---------|-----|----------|
+| **Modus** (org-wide) | `client.modus.*` | Full-environment assistant — same as the Modus home page |
+| **Scope** | `client.scopes.*` | A specific published scope and its configured context/tools |
+
+Use `client.modus.chat()` for native Modus — not a scope-id shortcut.
+
+### Org-wide Modus assistant
+
+```ts
+const MODEL = 'claude-sonnet-5'
+
+const result = await client.modus.chat('What were our top revenue drivers last quarter?', {
+  model: MODEL,
+})
+console.log(result.content, result.threadId)
+
+const followUp = await client.modus.chat('Break that down by region.', {
+  model: MODEL,
+  threadId: result.threadId,
+})
+console.log(followUp.content)
+
+const stream = client.modus.chatStream('Summarize this week', { model: MODEL })
+for await (const chunk of stream.textStream()) {
+  process.stdout.write(chunk)
+}
+
+const ctx = await client.modus.getContext('What tables describe customer churn?', { limit: 10 })
+console.log(ctx.originalCount, ctx.sessionId)
+
+for await (const row of (
+  await client.modus.conversations.list({ kind: 'modus', pageSize: 10 })
+).autoPagingIter()) {
+  console.log(row.threadId, row.firstMessage)
+}
 ```
 
-## Development
+### Scopes
 
-From the Modus monorepo root:
+```ts
+const MODEL = 'claude-sonnet-5'
 
-```bash
-pnpm nx run modus-sdk-typescript:generate
-pnpm nx run modus-sdk-typescript:build
-pnpm nx run modus-sdk-typescript:test
+const result = await client.scopes.chat(scopeId, 'Hello', { model: MODEL })
+console.log(result.content, result.threadId)
+
+const stream = client.scopes.chatStream(scopeId, 'Hi', { model: MODEL })
+for await (const chunk of stream.textStream()) {
+  process.stdout.write(chunk)
+}
 ```
 
-See [`../dev-examples/`](../dev-examples/) for additional runnable scripts (monorepo only).
+### Context
 
-```bash
-# Batch smoke (from repo root; uses .env for MODUS_API_KEY / MODUS_BASE_URL)
-bash distribution/clients/typescript/dev-examples/run_all.sh
-bash distribution/clients/typescript/dev-examples/run_all.sh --write
-bash distribution/clients/typescript/dev-examples/run_all.sh --chat   # LLM credits; needs healthy agent backend
+```ts
+for await (const item of (await client.context.items.list()).autoPagingIter()) {
+  console.log(item.uid, item.description ?? item.uid)
+}
 ```
 
-Shipped `chat.ts` accepts optional `MODUS_SCOPE_ID` to pick the scope. Chat may return `INTERNAL_ERROR` when the target environment's agent runtime is down — that is not an SDK bug.
+### Workflows
+
+```ts
+const workflow = await client.workflows.get(workflowId)
+for await (const run of (await client.workflows.runs.list(workflowId, { pageSize: 20 })).autoPagingIter()) {
+  console.log(run.id, run.status)
+}
+```
+
+Workflow chat is not on the public PAT surface. Use `client.modus.chat()` for org-wide conversation or `client.scopes.chat()` for a published scope.
+
+## Managing your org
+
+```ts
+import { ModusManagement } from '@getmodus/sdk/management'
+
+const mgmt = new ModusManagement() // reads MODUS_API_KEY
+const scope = await mgmt.scopes.create({ name: 'Analyst', model: 'claude-sonnet-5' })
+await mgmt.scopes.deploy(scope.id)
+
+// Create returns contextItemId (also available as .uid); list/get use .uid
+const note = await mgmt.context.createNote('Title', 'Body')
+console.log(note.contextItemId, note.uid) // same UUID
+```
+
+Requires a token with write access to scopes and workflows (same as the Modus UI).
+
+## Pagination
+
+List endpoints return a `Page<T>`. Iterate the current page, or use `.autoPagingIter()` for all pages:
+
+```ts
+for await (const scope of (await client.scopes.list()).autoPagingIter()) {
+  console.log(scope.name)
+}
+```
+
+`client.modus.conversations.list()` accepts `kind: 'modus' | 'skills' | 'all'` (default `'all'`).
+
+## Error handling
+
+```ts
+import {
+  Modus,
+  NotFoundError,
+  AuthenticationError,
+  RateLimitError,
+  ModusError,
+} from '@getmodus/sdk'
+
+try {
+  await client.scopes.get(999)
+} catch (e) {
+  if (e instanceof NotFoundError) {
+    console.log('Scope not found')
+  } else if (e instanceof AuthenticationError) {
+    console.log('Check your MODUS_API_KEY')
+  } else if (e instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${e.retryAfter}s`)
+  } else if (e instanceof ModusError) {
+    console.log(`API error ${e.statusCode}: ${e.message}`)
+  } else {
+    throw e
+  }
+}
+```
+
+## Examples
+
+Runnable scripts ship in this repository:
+
+- `examples/scripts/quickstart.ts` — list scopes and context (`Modus`)
+- `examples/scripts/modus_chat.ts` — buffered and streaming Modus chat, context compose, conversations
+- `examples/scripts/chat.ts` — buffered scope chat with thread follow-up
+- `examples/scripts/manage_skill.ts` — create and deploy a scope (`ModusManagement`, `--write` optional)
+
+```bash
+export MODUS_API_KEY=modus_xxx
+npx tsx examples/scripts/quickstart.ts
+```
 
 See [CHANGELOG.md](./CHANGELOG.md) for release history.

package/assets/modus-logo.svg

@@ -0,0 +1,13 @@
+<svg width="285" height="61" viewBox="0 0 285 61" fill="none" color="#3262FF" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_286_163)">
+<path d="M55.2983 42.8834C54.751 42.8368 54.2105 42.808 53.6606 42.7975C43.9042 42.4159 33.1793 49.1184 31.4067 59.7994C31.3068 60.3796 31.2328 60.9615 31.186 61.5553H24.4956C24.4488 60.9615 24.3748 60.3796 24.2749 59.7994C22.5023 49.1183 11.7775 42.4158 2.021 42.7975C1.4711 42.808 0.930604 42.8368 0.383301 42.8834V33.9069C1.12817 33.9537 1.85781 34.0252 2.59521 34.1207C15.2942 35.53 26.8692 45.713 27.8403 58.0631C28.8114 45.7131 40.3875 35.5301 53.0864 34.1207C53.8238 34.0252 54.5535 33.9537 55.2983 33.9069V42.8834Z" fill="currentColor"/>
+<path d="M55.301 18.2284C54.7538 18.2751 54.2131 18.3038 53.6633 18.3143C43.9068 18.696 33.182 11.9935 31.4094 1.31238C31.3095 0.732203 31.2355 0.15036 31.1887 -0.443481H24.4983C24.4515 0.150316 24.3775 0.732243 24.2776 1.31238C22.505 11.9934 11.7802 18.6959 2.02368 18.3143C1.47379 18.3038 0.933275 18.2751 0.385986 18.2284V27.205C1.13082 27.1581 1.86052 27.0867 2.5979 26.9911C15.2955 25.5819 26.8698 15.4008 27.843 3.05261C28.8162 15.4009 40.3914 25.582 53.0891 26.9911C53.8264 27.0866 54.5562 27.1581 55.301 27.205V18.2284Z" fill="currentColor"/>
+<path d="M27.8416 15.1049C27.8416 15.1049 29.1317 23.1704 32.1291 26.1678C35.1265 29.1651 43.192 30.4553 43.192 30.4553C43.192 30.4553 35.1265 31.7455 32.1291 34.7428C29.1317 37.7402 27.8416 45.8057 27.8416 45.8057C27.8416 45.8057 26.5514 37.7402 23.554 34.7428C20.5567 31.7455 12.4911 30.4553 12.4911 30.4553C12.4911 30.4553 20.5567 29.1651 23.554 26.1678C26.5514 23.1704 27.8416 15.1049 27.8416 15.1049Z" fill="currentColor"/>
+<path d="M69.9199 53.5372V18.4094H76.2005V22.7183C78.2454 19.0667 81.4587 17.387 85.7675 17.387C90.5876 17.387 94.1661 19.724 95.8458 23.6677C98.1097 19.4319 101.761 17.387 106.362 17.387C114.469 17.387 118.924 22.2801 118.924 31.0438V53.5372H111.913V31.4089C111.913 26.5159 109.576 23.8137 105.121 23.8137C100.958 23.8137 97.9637 27.0271 97.9637 31.628V53.5372H90.8797V31.4089C90.8797 26.5159 88.5427 23.8137 84.2339 23.8137C79.9981 23.8137 77.0039 27.0271 77.0039 31.628V53.5372H69.9199ZM145.316 54.5597C134.653 54.5597 127.204 47.1105 127.204 35.9368C127.204 24.8361 134.653 17.387 145.316 17.387C156.051 17.387 163.427 24.8361 163.427 35.9368C163.427 47.1105 156.051 54.5597 145.316 54.5597ZM134.507 35.9368C134.507 43.2399 138.889 48.133 145.316 48.133C151.815 48.133 156.124 43.2399 156.124 35.9368C156.124 28.7068 151.815 23.8137 145.316 23.8137C138.889 23.8137 134.507 28.7068 134.507 35.9368ZM186.865 54.5597C176.86 54.5597 169.995 47.1105 169.995 35.9368C169.995 24.8361 176.86 17.387 186.865 17.387C191.978 17.387 196.14 19.2858 198.331 22.7183V2.41571H205.342V53.5372H199.062V48.6442C196.725 52.3687 192.343 54.5597 186.865 54.5597ZM177.298 35.9368C177.298 43.2399 181.607 48.133 187.961 48.133C194.315 48.133 198.477 43.2399 198.477 35.9368C198.477 28.7068 194.315 23.8137 187.961 23.8137C181.607 23.8137 177.298 28.7068 177.298 35.9368ZM229.692 54.5597C221.148 54.5597 215.89 49.3014 215.89 39.5884V18.4094H222.974V38.9311C222.974 45.2117 225.895 48.133 231.007 48.133C236.338 48.133 239.771 44.3354 239.771 38.712V18.4094H246.855V53.5372H240.574V49.5205C238.237 52.953 234.22 54.5597 229.692 54.5597ZM270.113 54.5597C260.619 54.5597 254.996 50.7621 254.631 43.532H261.934C262.299 47.0375 265.147 48.7902 270.259 48.7902C274.933 48.7902 277.781 46.8184 277.781 43.605C277.781 40.9759 275.81 39.4423 272.158 39.0771L266.535 38.4929C259.962 37.8356 255.799 34.1841 255.799 28.3416C255.799 21.6228 261.422 17.387 270.04 17.387C278.804 17.387 284.208 21.0385 284.646 28.1956H277.562C277.343 24.8361 274.568 23.1564 269.967 23.1564C265.585 23.1564 262.81 24.9822 262.81 27.9765C262.81 30.5325 264.709 31.9201 268.799 32.4313L274.495 33.0886C281.141 33.8189 284.938 37.5435 284.938 43.3129C284.938 50.1778 279.169 54.5597 270.113 54.5597Z" fill="currentColor"/>
+</g>
+<defs>
+<clipPath id="clip0_286_163">
+<rect width="285" height="61" fill="currentColor"/>
+</clipPath>
+</defs>
+</svg>