@getmodus/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+**Current npm release:** not yet published. Pre-release via `@beta` dist-tag when available.
+
+## [Unreleased]
+
+### Changed
+
+- npm package scope is **`@getmodus/sdk`** (npm org `getmodus`; `@modus` scope was unavailable). Install with `npm install @getmodus/sdk`.
+
+### Changed (BREAKING)
+
+- **MCP `get_context_data` batch + ACL (BREAKING)** — Renamed from `fetch_context_file`. Pass `{ items[], sessionId? }` instead of top-level `itemId`. Response `{ results[] }` with per-item `ok` / errors (max 20). ACL + scope surface authorization; optional `sessionId` for Mongo offload cache.
+- **`/scopes` + `/workflows` are now the only public surface.** `client.scopes` / `client.workflows` and `mgmt.scopes` / `mgmt.workflows` are canonical; they call the `/api/v1/scopes` and `/api/v1/workflows` routes and the `ScopesController_*` / `WorkflowsController_*` operationIds.
+- Run creation: `client.workflows.runs.createScope(scopeId, body)` replaces the old `createSkill(...)` (routes to `/agent/v1/scopes/:id/runs`).
+- Existing tokens that carry the legacy `skills:*` / `agents:*` scopes continue to authorize the renamed routes via server-side scope equivalence — no token re-issuance is required.
+
+### Removed (BREAKING)
+
+- **`client.skills` / `client.agents`** and **`mgmt.skills` / `mgmt.agents`** accessors — use `client.scopes` / `client.workflows` and `mgmt.scopes` / `mgmt.workflows`. The legacy `/api/v1/skills` and `/api/v1/agents` routes (and their `SkillsController_*` / `AgentsController_*` operationIds) no longer exist.
+- Placeholder `SECURITY.md` (no verified security contact yet).
+
+### Added
+
+- Shipped examples under `examples/scripts/` (`quickstart`, `modus_chat`, `chat`, `manage_skill`) with revenue / ARR analyst prompts.
+- `skills.conversations(id).get()` accepts an optional `{ messageLimit, beforeMessageIndex }` to request a bounded message window; the response gains an optional `messageWindow` field describing the returned slice. Omit both for the full conversation (unchanged default behavior).
+- **`client.suggestions`** — `list()` returns approved suggested questions (optional `skillId`/`skillIds` filter), `recordEvent()` records an impression/click/dismiss event against a suggestion.
+- **`client.workflows.runs.active(options)` / `activeBySession(sessionIds)`** — list active (queued/pending/running) conversation runs for the current user, or look up active runs for specific conversation thread ids.
+- **`claude-sonnet-4.6`** restored as an allowed run `model` value (scope/workflow run creation and chat).
+- **`mgmt.scopes.evaluations(scopeId)`** — `getConfig()` / `updateConfig()` manage a scope's evaluation schedule and judge settings; `triggerRun()` starts a manual evaluation run; `listRuns()` / `getRun(runId)` read run history and per-case results.
+
+### Fixed
+
+- Typed run event streams now recover from interrupted model providers and emit `assistant_content_reset` when previously streamed assistant content is replaced.
+
+## [0.1.0] — 2026-06-21
+
+### Added
+
+- **`@getmodus/sdk`** — official TypeScript client for Modus (Node.js 18+).
+- **`Modus`** client — read / invoke: skills, agents, context, connections, Modus assistant chat, runs.
+- **`ModusManagement`** (`@getmodus/sdk/management`) — configure: CRUD, deploy, context creators, usage, org admin.
+- Cursor-based **`Page<T>`** pagination with `autoPagingIter()` (AIP-158 `pageSize` / `pageToken`).
+- Automatic retry on 429 and 5xx with exponential backoff and `Retry-After` support.
+- SSE streaming chat via `ChatStream` (`textStream()`, `eventStream()`).
+- **58/58** public API operations covered; contract tests enforce OpenAPI parity.
+- Dual **ESM + CommonJS** build (`import` and `require()`).
+- Zero runtime dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Modus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @getmodus/sdk
+
+Official TypeScript client for Modus (pre-release).
+
+**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)
+
+```bash
+npm install @getmodus/sdk@beta
+```
+
+## Usage
+
+### ESM (`import`)
+
+```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 })
+
+const scopes = await client.scopes.list()
+const draft = await mgmt.scopes.create({ name: 'Analyst', model: 'claude-sonnet-5' })
+```
+
+### 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):
+
+- `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
+```
+
+From the Modus monorepo (after build):
+
+```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
+```
+
+## Development
+
+From the Modus monorepo root:
+
+```bash
+pnpm nx run modus-sdk-typescript:generate
+pnpm nx run modus-sdk-typescript:build
+pnpm nx run modus-sdk-typescript:test
+```
+
+See [`../dev-examples/`](../dev-examples/) for additional runnable scripts (monorepo only).
+
+```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
+```
+
+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.
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.