@m8tes/sdk 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to `@m8tes/sdk`.
+
+> **Release process** (mirrors `sdk/py`): every change to behaviour or public API
+> lands an entry under `## [Unreleased]` in the same commit. A RELEASE then bumps
+> `package.json` `version` (semver) and retitles that section. Entries are never
+> skipped — without one, a consumer cannot tell what changed. Publish via the `Publish @m8tes/sdk` workflow — never `npm publish` by
+> hand (it does not rewrite the pnpm `workspace:` protocol).
+>
+> While the version is a `-alpha.N` prerelease, publish with dist-tag `alpha`.
+> The first stable release is published with `--tag latest` deliberately.
+
+## [0.1.0-alpha.1]
+
+Initial release. TypeScript client for the m8tes V2 API, at parity with the
+Python SDK on the core loop.
+
+### Added
+
+- **`M8tes` client** — `runs`, `agents` (alias `teammates`), `tasks` (+ `tasks.triggers`),
+  `users`, `apps`, `webhooks`, `settings`. Reads `M8TES_API_KEY`, or pass `apiKey`.
+  `client.http` is the escape hatch for endpoints this version does not wrap yet.
+- **Streaming `RunStream`** — async-iterable of normalized events, plus `iterText()`,
+  `text()`, `runId`, `errors`, and `conversation` (the full accumulated
+  conversation: messages, tool calls, notices). `raiseOnError` turns a run that
+  emitted error events into a thrown `RunFailedError`, so a mid-run failure is
+  never mistaken for a successful empty run.
+- **Typed errors** — `M8tesApiError` plus a subclass per status
+  (`ValidationError`, `AuthenticationError`, `BillingError`,
+  `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `RateLimitError`,
+  `APIError`), each carrying `status`, `errorCode`, `requestId`, `docUrl`,
+  `retryAfter`, and `details`.
+- **Automatic retries** on 429/5xx for idempotent requests only, honouring
+  `Retry-After`. A `POST` is never retried: one that timed out may already have
+  started a billable run.
+- **Auto-paging** — every `list()` returns a `Page` you can `for await` straight
+  through; it fetches subsequent pages for you.
+- **`verifySignature()`** — HMAC-SHA256 webhook verification with optional replay
+  protection. Needs no client and no API key, and interoperates with the Python
+  SDK (same signing scheme, pinned by a shared test vector).
+- **`@m8tes/sdk/protocol`** — the wire protocol (event union, SSE decoder,
+  normalizer, conversation accumulator, error classes) as a browser-safe entry
+  point with no auth code. `@m8tes/react` consumes this, so there is ONE
+  implementation of the protocol rather than one per package.
+- **`@m8tes/sdk/fixtures`** — the recorded wire scenarios both packages test
+  against, exported so you can test your own protocol consumers.
+- **Base-URL diagnostics** — an HTML response or a 404 with no error envelope
+  produces an actionable message ("check your baseUrl includes the /api/v2
+  prefix") instead of a wall of HTML or a bare 404.
+
+### Corrections from review (before first publish)
+
+An adversarial Codex review plus a second live-backend pass caught these while
+the package was still unpublished. Each was verified against the backend schema,
+not assumed, and each is pinned by a test in `test/review-findings.test.ts`:
+
+- **Field names are the API's own snake_case** (`user_id`, `created_at`) in params
+  and responses, matching `/docs/api-reference` and the Python SDK. This removed
+  the case-mapping layer entirely — and with it the class of bug where a key
+  rewriter silently mangled caller-defined keys.
+- `apps.connectOauth` sends **`redirect_uri`** (not `redirect_url` — a 422) and
+  returns `{authorization_url, connection_id}`; `apps.connectComplete` requires
+  `connection_id`.
+- `runs.get()` sends **no query parameters** — `GET /runs/{id}` declares none, so
+  passing `user_id` was a 422.
+- `runs.cancel()` returns the updated `Run`, matching the Python SDK.
+- `PermissionMode` is `"autonomous" | "approval" | "plan"` — the previous type
+  offered the Claude Agent SDK's names, which the API rejects.
+- `tasks.create()` requires an owning agent; `POST /tasks/` requires `teammate_id`.
+- Update params carry **only** what each PATCH schema accepts. Create-only fields
+  sent to PATCH return 200 and change nothing, which reads as success.
+- Explicit `null` is expressible on update params — that is how a field is cleared.
+- An unmapped HTTP status maps to `APIError`, matching Python's
+  `STATUS_MAP.get(status, APIError)`.
+- Auto-pagination terminates if the cursor stops advancing instead of looping forever.
+- An abort is observed **during** retry backoff (a `Retry-After: 3600` no longer
+  strands a cancelled caller for an hour).
+- Constructing a client in a browser throws: the secret key would otherwise be
+  readable by every visitor.
+
+### Notes from validating against a live backend
+
+Two things the mocked unit suite could not have caught, both fixed before release:
+
+- `client.settings` is in v0.1 because strict multi-tenant mode is ON by default
+  for API accounts, and the backend's 422 tells you to call
+  `client.settings.update(...)`. Without the resource, that instruction dead-ends.
+- `apps.list()` sends only `user_id`. `GET /apps/` rejects `limit` /
+  `starting_after` with a 422 (`unknown_query_parameter`), so the endpoint is not
+  paginated and iterating one page terminates instead of looping.
+
+### Notes
+
+- Server-only: this package holds your secret key. To render an agent in a
+  browser use [`@m8tes/react`](https://www.npmjs.com/package/@m8tes/react).
+- Parameters and response fields are camelCase, matching `@m8tes/react`; the
+  snake_case wire mapping happens inside the SDK. Caller-defined keys
+  (`metadata`, `answers`, `outputSchema` properties, `triggerConfig`) are passed
+  through verbatim and never rewritten.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 m8tes.ai
+
+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,160 @@
+# @m8tes/sdk
+
+TypeScript client for the [m8tes](https://www.m8tes.ai) API. Create agents, schedule tasks, stream runs, and verify webhooks from Node, Deno, or Bun.
+
+> **Alpha.** Published under the `alpha` dist-tag. Method signatures may change before 1.0; the streaming wire protocol (`m8tes.stream.v2`) is semver-stable.
+
+```bash
+npm i @m8tes/sdk@alpha
+```
+
+Requires Node 18+, Deno, or Bun. No dependencies. (`verifySignature` uses `node:crypto`, so edge runtimes need Node compatibility enabled.)
+
+## Your first run
+
+```ts
+import { M8tes } from "@m8tes/sdk";
+
+const client = new M8tes(); // reads M8TES_API_KEY
+
+const run = client.runs.create({
+  message: "A customer asked to cancel. Draft a warm reply that offers to pause instead.",
+});
+
+for await (const chunk of run.iterText()) process.stdout.write(chunk);
+console.log("\nrun", run.runId, "cost", run.conversation.status);
+```
+
+No agent to create first: a brand-new key auto-provisions a default agent.
+
+Get a key at [m8tes.ai/developer](https://m8tes.ai/developer).
+
+## Multi-tenancy
+
+`user_id` is **your** id for one of your customers. Pass it and that person's memory, run history, and tool connections stay isolated — strictly, with no fallback to account-level data.
+
+```ts
+const run = client.runs.create({ message: "Summarize my open tickets", user_id: "customer_42" });
+```
+
+Register end-users explicitly when you want per-person budgets:
+
+```ts
+await client.users.create({ user_id: "customer_42", run_limit: 50, rate_per_minute: 5 });
+```
+
+## Not streaming
+
+```ts
+const run = await client.runs.createAsync({ message: "Prep the weekly recap" });
+// poll, or receive a webhook
+const done = await client.runs.get(run.id);
+console.log(done.status, done.output);
+```
+
+## Agents and scheduled tasks
+
+```ts
+const agent = await client.agents.create({
+  name: "Support Triage",
+  instructions: "Sort inbound tickets by urgency and draft first replies.",
+  tools: ["gmail"],
+});
+
+const task = await client.tasks.create({
+  agent_id: agent.id,
+  instructions: "Review yesterday's tickets and post a summary.",
+  schedule: "0 9 * * 1-5", // weekday mornings
+  schedule_timezone: "Europe/Copenhagen",
+});
+```
+
+Triggers beyond cron — webhook, email, and app events:
+
+```ts
+await client.tasks.triggers.create(task.id, { type: "app", app: "github", trigger_name: "pull_request_opened" });
+const { url } = await client.tasks.enableWebhook(task.id);
+```
+
+## Human-in-the-loop
+
+When a run pauses, the stream emits an `approval-request` or `question` event. Answer it and the run resumes.
+
+```ts
+const run = client.runs.create({ message: "Refund order 1234", human_in_the_loop: true });
+
+for await (const event of run) {
+  // run.runId is populated from the first event, so it's available by the time a gate arrives.
+  if (event.type === "approval-request" && run.runId) {
+    await client.runs.approve(run.runId, { request_id: event.requestId, decision: "allow" });
+  }
+  if (event.type === "question" && run.runId) {
+    const q = event.questions[0];
+    if (q) await client.runs.answer(run.runId, { answers: { [q.question]: "Yes" } });
+  }
+}
+```
+
+Every snippet in this README is mirrored by a compiled file in [`examples/`](./examples), so `tsc` fails if one of them stops type-checking.
+
+## Webhooks
+
+Verification needs no client and no API key. Pass the **raw** body: a parsed-then-restringified object will not match.
+
+```ts
+import { verifySignature } from "@m8tes/sdk";
+
+export async function POST(req: Request) {
+  const raw = await req.text();
+  if (!verifySignature(raw, req.headers, process.env.M8TES_WEBHOOK_SECRET!, { toleranceSeconds: 300 })) {
+    return new Response("bad signature", { status: 401 });
+  }
+  const event = JSON.parse(raw);
+  return new Response("ok");
+}
+```
+
+## Errors
+
+Every failure is a typed subclass of `M8tesApiError`, carrying `status`, `errorCode`, `requestId`, `docUrl`, and `retryAfter`.
+
+Field names throughout are the API's own **snake_case** (`user_id`, `created_at`) — the same names as the [API reference](https://www.m8tes.ai/docs/api-reference) and the Python SDK, so nothing is renamed in transit. Things the SDK owns rather than sends — client options, method names, `RunStream`, stream events — stay camelCase.
+
+```ts
+import { BillingError, RateLimitError } from "@m8tes/sdk";
+
+try {
+  await client.runs.createAsync({ message: "..." });
+} catch (err) {
+  if (err instanceof RateLimitError) await sleep((err.retryAfter ?? 1) * 1000);
+  else if (err instanceof BillingError) console.error(err.errorCode, err.docUrl);
+  else throw err;
+}
+```
+
+Retries are automatic on 429 and 5xx for idempotent requests only. A `POST` is **never** retried: one that timed out may already have started a billable run.
+
+## Pagination
+
+Every `list()` returns a page you can iterate straight through — it fetches the rest for you.
+
+```ts
+for await (const run of await client.runs.list({ user_id: "customer_42" })) {
+  console.log(run.id, run.status);
+}
+```
+
+## Browser UI
+
+This package is **server-only** — it holds your secret key. To render an agent in a browser, use [`@m8tes/react`](https://www.npmjs.com/package/@m8tes/react), which ships a `<MateChat>` component plus a locked-down server proxy so the key never reaches the client. Both packages share this one wire-protocol implementation, exported separately as the browser-safe `@m8tes/sdk/protocol`.
+
+## Docs
+
+- [TypeScript SDK guide](https://www.m8tes.ai/docs/typescript-sdk)
+- [API reference](https://www.m8tes.ai/docs/api-reference)
+- [Multi-tenancy](https://www.m8tes.ai/docs/users)
+- [Streaming & events](https://www.m8tes.ai/docs/streaming)
+
+## License
+
+MIT