@martenhq/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marten
+
+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

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @martenhq/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Talk to your Martens from your own programs. [Marten](https://marten.sh) is a messenger where your AI agents are
+members: each Marten has a 1:1 chat with you, its own memory, connected apps, tasks and sketches. This SDK acts as you,
+with an API key: ask your Martens, read and post in your chats, manage tasks, and install Martens from the registry.
+
+ESM only (`import`, not `require`): Node 20+, Bun, Deno and edge runtimes (it needs only `fetch`). Types included. No
+dependencies.
+
+```sh
+npm install @martenhq/sdk
+```
+
+## A key
+
+Run `npx @martenhq/cli login`: it signs you in with your Marten email (the link, or the 6-digit code) and keeps a key for
+this machine in `~/.config/marten/credentials` (JSON, its `apiKey`). Pass it as `apiKey`, or set `MARTEN_API_KEY`.
+Each has scopes:
+
+| Scope | Lets it |
+|---|---|
+| `martens` (default) | list your Martens, read and post in their 1:1s with you, `ask` them |
+| `tasks` (default) | list, add and change tasks in your chats |
+| `registry` (default) | browse the registry and install Martens for you |
+| `chats:read` | read your groups |
+| `chats:write` | post as you in your groups, add Martens to them |
+
+`marten login` asks for the defaults; for the others, name them all: `npx @martenhq/cli login --scope martens --scope
+tasks --scope registry --scope chats:read --scope chats:write`.
+
+A message sent with a key shows "via <key name>" under it, so everyone in the chat can tell.
+
+## Examples
+
+```ts
+import { Marten } from "@martenhq/sdk";
+
+const marten = new Marten({ apiKey: process.env.MARTEN_API_KEY });
+
+// Ask a Marten and wait for its reply (60 s by default, at most 120 s).
+const poker = await marten.martens.get("Poker");
+const { reply, status } = await poker.ask("Who's up this month?");
+if (status === "replied") console.log(reply!.text);
+// "quiet": it chose not to answer; "timeout": still working, its answer will land in the chat.
+
+// Or post without waiting, and read the chat later.
+await poker.send("Book the table for Friday");
+const { messages } = await poker.messages({ limit: 20 });
+
+// Any chat you're in (groups need chats:read / chats:write).
+for (const chat of await marten.chats.list()) console.log(chat.kind, chat.title, chat.id);
+await marten.chats.send(chatId, "On my way");
+
+// Tasks: when and how often in words, as you'd say them.
+const task = await marten.tasks.create({ chatId: poker.chatId, title: "Buy chips", due: "friday 6pm", timezone: "Europe/Berlin" });
+await marten.tasks.update(task.id, { status: "done" });
+const open = await marten.tasks.list({ status: "open" });
+
+// The registry.
+const listings = await marten.registry.list();
+await marten.registry.install("trip-planner"); // a Marten of your own
+await marten.registry.install("trip-planner", { chatId: groupId }); // added to a group (chats:write)
+```
+
+## Errors
+
+Every refused or failed call throws a `MartenError` with the HTTP `status` (0 when Marten couldn't be reached) and the
+API's `code`:
+
+```ts
+import { MartenError } from "@martenhq/sdk";
+
+try {
+  await marten.chats.send(groupId, "hi");
+} catch (err) {
+  if (err instanceof MartenError && err.code === "missing_scope") console.error("This key can't post in groups");
+  else throw err;
+}
+```
+
+Codes include `unauthorized` (no key sent), `invalid_key` (a revoked or mistyped one: sign in again), `missing_scope`,
+`not_found`, `invalid`, `rate_limited` (60 requests a minute per key, 20 of them `ask`s; `err.retryAfter` is the
+seconds to wait) and `network`.
+
+## Options
+
+```ts
+new Marten({
+  apiKey: "mk_live_…", // default: MARTEN_API_KEY
+  baseUrl: "https://api.marten.sh", // default: MARTEN_API_URL, else this
+  fetch, // bring your own
+});
+```
+
+The API it calls is `/v1`, described at https://api.marten.sh/v1/openapi.json.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_BASE_URL, Marten, MartenError, MartenHandle, type MartenOptions } from "./marten/marten.js";
+export type * from "./types/types.js";

package/dist/index.js

@@ -0,0 +1,150 @@
+// src/marten/marten.ts
+var DEFAULT_BASE_URL = "https://api.marten.sh";
+
+class MartenError extends Error {
+  status;
+  code;
+  retryAfter;
+  constructor(status, code, message, opts = {}) {
+    super(message);
+    this.name = "MartenError";
+    this.status = status;
+    this.code = code;
+    this.retryAfter = opts.retryAfter ?? null;
+  }
+}
+function retryAfterOf(header) {
+  if (!header)
+    return null;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds))
+    return Math.max(0, seconds);
+  const at = Date.parse(header);
+  return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}
+function env(name) {
+  try {
+    return globalThis.process?.env?.[name];
+  } catch {
+    return;
+  }
+}
+var query = (params) => {
+  const entries = Object.entries(params).filter((e) => e[1] !== undefined);
+  return entries.length ? `?${new URLSearchParams(entries.map(([k, v]) => [k, String(v)]))}` : "";
+};
+
+class MartenHandle {
+  id;
+  name;
+  chatId;
+  info;
+  #client;
+  constructor(client, info) {
+    this.#client = client;
+    this.info = info;
+    this.id = info.id;
+    this.name = info.name;
+    this.chatId = info.chatId;
+  }
+  ask(text, opts = {}) {
+    return this.#client.request("POST", `/v1/martens/${this.id}/ask`, { text, ...opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {} });
+  }
+  send(text, opts = {}) {
+    return this.#client.chats.send(this.chatId, text, opts);
+  }
+  messages(opts = {}) {
+    return this.#client.chats.messages(this.chatId, opts);
+  }
+}
+
+class Marten {
+  baseUrl;
+  #apiKey;
+  #fetch;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? env("MARTEN_API_KEY");
+    if (!apiKey)
+      throw new MartenError(0, "no_api_key", "Pass an API key (new Marten({ apiKey })) or set MARTEN_API_KEY; make one with `npx @martenhq/cli login`");
+    this.#apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? env("MARTEN_API_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+  }
+  async request(method, path, body) {
+    let res;
+    try {
+      res = await this.#fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: { authorization: `Bearer ${this.#apiKey}`, accept: "application/json", ...body === undefined ? {} : { "content-type": "application/json" } },
+        body: body === undefined ? undefined : JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new MartenError(0, "network", `Can't reach Marten at ${this.baseUrl}: ${err.message}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (res.ok)
+      return data;
+    const error = typeof data?.error === "object" ? data.error : { code: data?.error, message: data?.message };
+    throw new MartenError(res.status, error?.code ?? "http_error", error?.message ?? `Marten answered ${res.status}`, { retryAfter: retryAfterOf(res.headers.get("retry-after")) });
+  }
+  me() {
+    return this.request("GET", "/v1/me");
+  }
+  async revokeKey() {
+    await this.request("DELETE", "/v1/key");
+  }
+  martens = {
+    list: async () => (await this.request("GET", "/v1/martens")).martens,
+    get: async (nameOrId) => {
+      const list = await this.martens.list();
+      const found = pick(list, nameOrId, (m) => m.name, "Marten");
+      if (!found.chatId)
+        throw new MartenError(404, "not_found", `${found.name} has no 1:1 with you`);
+      return new MartenHandle(this, found);
+    }
+  };
+  chats = {
+    list: async () => (await this.request("GET", "/v1/chats")).chats,
+    messages: (chatId, opts = {}) => this.request("GET", `/v1/chats/${encodeURIComponent(chatId)}/messages${query({ limit: opts.limit, before: opts.before })}`),
+    send: async (chatId, text, opts = {}) => (await this.request("POST", `/v1/chats/${encodeURIComponent(chatId)}/messages`, { text, ...opts })).message
+  };
+  tasks = {
+    list: async (opts = {}) => (await this.request("GET", `/v1/tasks${query({ chat: opts.chatId, status: opts.status })}`)).tasks,
+    create: async (task) => (await this.request("POST", "/v1/tasks", task)).task,
+    update: async (taskId, changes) => (await this.request("PATCH", `/v1/tasks/${encodeURIComponent(taskId)}`, changes)).task
+  };
+  registry = {
+    list: async () => (await this.request("GET", "/v1/registry")).listings,
+    get: async (slug) => (await this.request("GET", `/v1/registry/${encodeURIComponent(slug)}`)).listing,
+    install: (slug, target = "you", opts = {}) => this.request("POST", `/v1/registry/${encodeURIComponent(slug)}/install`, {
+      ...target === "you" ? {} : { chatId: target.chatId },
+      timezone: opts.timezone ?? localZone()
+    })
+  };
+}
+function localZone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+function pick(list, wanted, name, what) {
+  const w = wanted.trim().toLowerCase();
+  const byId = list.find((x) => x.id.toLowerCase() === w);
+  if (byId)
+    return byId;
+  const exact = list.filter((x) => name(x).toLowerCase() === w);
+  const matches = exact.length ? exact : list.filter((x) => name(x).toLowerCase().startsWith(w));
+  if (matches.length === 1)
+    return matches[0];
+  if (matches.length > 1)
+    throw new MartenError(409, "ambiguous", `Several match "${wanted}": ${matches.map(name).join(", ")}; use an id`);
+  throw new MartenError(404, "not_found", `No ${what} called "${wanted}"${list.length ? ` (yours: ${list.map(name).join(", ")})` : ""}`);
+}
+export {
+  MartenHandle,
+  MartenError,
+  Marten,
+  DEFAULT_BASE_URL
+};

package/dist/marten/marten.d.ts

@@ -0,0 +1,112 @@
+import type { AskResult, Chat, Installed, Listing, ListingDetail, MartenInfo, Me, Message, MessagePage, NewTask, Task, TaskChanges, TaskStatus } from "../types/types.js";
+export declare const DEFAULT_BASE_URL = "https://api.marten.sh";
+export interface MartenOptions {
+    /** An API key (`mk_live_…`). Defaults to `MARTEN_API_KEY` where there's an environment. */
+    apiKey?: string;
+    /** Defaults to `MARTEN_API_URL`, else https://api.marten.sh. */
+    baseUrl?: string;
+    /** For runtimes or tests that bring their own. */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/**
+ * A refused or failed call. `status` is the HTTP status (0 when Marten couldn't be reached); `code` the API's reason
+ * (`unauthorized`, `invalid_key`, `missing_scope`, `not_found`, `rate_limited`, `invalid`…), so a program can tell them
+ * apart. `retryAfter`: when it's `rate_limited`, the seconds to wait before trying again.
+ */
+export declare class MartenError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfter: number | null;
+    constructor(status: number, code: string, message: string, opts?: {
+        retryAfter?: number | null;
+    });
+}
+type Method = "GET" | "POST" | "PATCH" | "DELETE";
+/** One of your Martens, to talk to: `ask` waits for its answer, `send` doesn't. */
+export declare class MartenHandle {
+    #private;
+    readonly id: string;
+    readonly name: string;
+    /** Its 1:1 with you. */
+    readonly chatId: string;
+    readonly info: MartenInfo;
+    constructor(client: Marten, info: MartenInfo & {
+        chatId: string;
+    });
+    /** Posts in its 1:1 and waits for its reply (`timeoutMs`: 60 s by default, at most 120 s). */
+    ask(text: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<AskResult>;
+    send(text: string, opts?: {
+        replyToId?: string;
+        clientId?: string;
+    }): Promise<Message>;
+    messages(opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<MessagePage>;
+}
+/**
+ * Marten's public API, as you: your Martens, your chats, their tasks and the registry. Every call carries your API key;
+ * what it may do is the key's scopes.
+ *
+ * ```ts
+ * const marten = new Marten({ apiKey: process.env.MARTEN_API_KEY });
+ * const poker = await marten.martens.get("Poker");
+ * const { reply } = await poker.ask("Who's up this month?");
+ * ```
+ */
+export declare class Marten {
+    #private;
+    readonly baseUrl: string;
+    constructor(options?: MartenOptions);
+    /** A call to the API: JSON in and out, a `MartenError` for anything but a 2xx. */
+    request<T>(method: Method, path: string, body?: unknown): Promise<T>;
+    /** Who the key acts as, and what it may do. */
+    me(): Promise<Me>;
+    /** Revokes this client's own key: it opens nothing from then on (signing out). */
+    revokeKey(): Promise<void>;
+    readonly martens: {
+        /** Your own Martens: your personal one and the ones you made or installed. */
+        list: () => Promise<MartenInfo[]>;
+        /** One of your Martens by id, or by name: exact (any case) first, else the one whose name starts so. */
+        get: (nameOrId: string) => Promise<MartenHandle>;
+    };
+    readonly chats: {
+        /** Your Martens' 1:1s, and your groups when the key may read them (`chats:read`). */
+        list: () => Promise<Chat[]>;
+        /** A chat's messages, oldest first; `before` (a page's `next`) goes further back. */
+        messages: (chatId: string, opts?: {
+            limit?: number;
+            before?: string;
+        }) => Promise<MessagePage>;
+        /** Posts as you ("via <key name>" under it); it wakes the Martens a message from you would. */
+        send: (chatId: string, text: string, opts?: {
+            replyToId?: string;
+            clientId?: string;
+        }) => Promise<Message>;
+    };
+    readonly tasks: {
+        /** Your chats' tasks (or one chat's): open ones and those done in the last 30 days. */
+        list: (opts?: {
+            chatId?: string;
+            status?: TaskStatus | "open";
+        }) => Promise<Task[]>;
+        create: (task: NewTask) => Promise<Task>;
+        update: (taskId: string, changes: TaskChanges) => Promise<Task>;
+    };
+    readonly registry: {
+        list: () => Promise<Listing[]>;
+        get: (slug: string) => Promise<ListingDetail>;
+        /**
+         * Installs a listing: a Marten of your own (`"you"`, the default) or one added to a group (`{ chatId }`, which
+         * takes the `chats:write` scope). Its starter tasks' times are in `timezone` (this runtime's by default).
+         */
+        install: (slug: string, target?: "you" | {
+            chatId: string;
+        }, opts?: {
+            timezone?: string;
+        }) => Promise<Installed>;
+    };
+}
+export {};

package/dist/types/types.d.ts

@@ -0,0 +1,191 @@
+/** What a key may do; see `Scope` in the API's OpenAPI document (`/v1/openapi.json`). */
+export type Scope = "martens" | "chats:read" | "chats:write" | "tasks" | "registry";
+export interface Me {
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        displayName: string;
+    };
+    key: {
+        id: string;
+        name: string;
+        scopes: Scope[];
+    };
+}
+/** One of your own Martens. `chatId` is its 1:1 with you. */
+export interface MartenInfo {
+    id: string;
+    kind: "personal" | "custom";
+    name: string;
+    color: string;
+    description: string;
+    look: string | null;
+    voice: string | null;
+    listing: {
+        slug: string;
+        version: string;
+    } | null;
+    createdAt: string;
+    chatId: string | null;
+}
+export interface Chat {
+    id: string;
+    /** `direct`: a 1:1 with one of your Martens. */
+    kind: "direct" | "group";
+    title: string;
+    members: {
+        id: string;
+        name: string;
+    }[];
+    martens: {
+        id: string;
+        name: string;
+        kind: string;
+    }[];
+}
+export interface Message {
+    id: string;
+    chatId: string;
+    author: {
+        kind: "person";
+        id: string;
+        name: string;
+    } | {
+        kind: "marten";
+        id: string;
+        name: string;
+    } | {
+        kind: "system";
+        id: null;
+        name: null;
+    };
+    /** Markdown; mentions read `@Name`. */
+    text: string;
+    at: string;
+    replyToId: string | null;
+    taskId: string | null;
+    appId: string | null;
+    fileId: string | null;
+    /** The name of the API key it was sent with, when it was. */
+    viaKey: string | null;
+    editedAt: string | null;
+    clientId: string | null;
+}
+export interface MessagePage {
+    /** Oldest first. */
+    messages: Message[];
+    /** Pass as `before` for the page before this one; null at the start of the chat. */
+    next: string | null;
+}
+/** `replied`; `quiet`: it chose not to answer; `timeout`: still working, its answer will land in the chat. */
+export interface AskResult {
+    message: Message;
+    reply: Message | null;
+    status: "replied" | "quiet" | "timeout";
+}
+export type TaskStatus = "todo" | "in_progress" | "needs_review" | "done";
+export interface Task {
+    id: string;
+    chatId: string;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    assigneeId: string | null;
+    assigneeMartenId: string | null;
+    /** A calendar date (`YYYY-MM-DD`) with no time. */
+    due: string | null;
+    scheduledAt: string | null;
+    remind: boolean;
+    labels: string[];
+    repeat: {
+        seriesId: string;
+        rrule: string;
+        timezone: string;
+        text: string;
+        nextAt: string | null;
+    } | null;
+    createdBy: string | null;
+    createdByMartenId: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+}
+/** When and how often, in words: the server reads them as `marten task add --due/--repeat/--tz` does. */
+interface TaskWhen {
+    /** "friday", "tomorrow 9am", "2026-10-31", "2026-10-31 09:00" (in `timezone`) or an ISO time; null or "none" clears it. */
+    due?: string | null;
+    /** "every weekday at 9", "every 2 weeks on friday", "daily", an RRULE, or "none" to stop. */
+    repeat?: string;
+    /** An IANA zone for `due` and `repeat`; UTC when left out. */
+    timezone?: string;
+    description?: string;
+    remind?: boolean;
+    labels?: string[];
+}
+export interface NewTask extends TaskWhen {
+    /** The chat it goes in (its card is posted there). */
+    chatId: string;
+    title: string;
+    /** `me`, or a person or Marten in the chat by name or id. In a 1:1 the Marten's unless you say otherwise. */
+    assignee?: string;
+}
+export interface TaskChanges extends TaskWhen {
+    title?: string;
+    status?: TaskStatus;
+    /** null: nobody. */
+    assignee?: string | null;
+}
+export interface Listing {
+    slug: string;
+    name: string;
+    version: string;
+    summary: string;
+    category: string;
+    for: ("you" | "group")[];
+    look: string | null;
+    voice: string | null;
+    color: string;
+    needs: {
+        apps: string[];
+        optional: string[];
+    };
+}
+export interface ListingDetail extends Omit<Listing, "needs"> {
+    needs: {
+        apps: {
+            app: string;
+            why: string;
+        }[];
+        optional: {
+            app: string;
+            why: string;
+        }[];
+        mcp: unknown[];
+    };
+    examples: string[];
+    sketches: {
+        name: string;
+    }[];
+    tasks: {
+        title: string;
+        repeat: string | null;
+        time: string | null;
+        assignee: string;
+    }[];
+    skills: string[];
+    readme: string;
+    instructions: string;
+    changelog: string;
+}
+export interface Installed {
+    marten: {
+        id: string;
+        kind: string;
+        name: string;
+        [field: string]: unknown;
+    };
+    /** Its 1:1 with you, or the group it was added to. */
+    chatId: string;
+}
+export {};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@martenhq/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Talk to your Martens from your own programs: ask them, read and post in your chats, manage tasks, install Martens.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://marten.sh",
+  "repository": {
+  "type": "git",
+  "url": "git+https://github.com/RedPlanetHQ/marten-app.git",
+  "directory": "packages/sdk"
+},
+"keywords": ["marten", "agents", "ai", "sdk"],
+"engines": {
+"node": ">=20"
+},
+"sideEffects": false,
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "default": "./dist/index.js"
+  },
+  "./package.json": "./package.json"
+},
+"main": "./dist/index.js",
+"types": "./dist/index.d.ts",
+"files": ["dist", "README.md", "LICENSE"],
+"publishConfig": {
+"access": "public"
+},
+"scripts": {
+  "build": "bun build.ts",
+  "test": "bun test",
+  "typecheck": "tsc -p tsconfig.json"
+},
+"devDependencies": {
+  "@types/bun": "^1.4.2"
+}
+}