expectbox-agents 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Expectbox
+
+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,101 @@
+# Expectbox Agents SDK
+
+[Website](https://www.expectbox.com/) · [Expectbox Agents](https://www.expectbox.com/agents/) · [API documentation](https://www.expectbox.com/agent-sdk/README.md) · [Releases](https://github.com/simon86pl/expectbox-sdk/releases)
+
+Official JavaScript/TypeScript and Python clients for [Expectbox Agents](https://www.expectbox.com/agents/).
+This repository contains the clients, examples and API contract; the hosted mail service is separate.
+
+## Install
+
+Node.js 22+:
+
+```sh
+npm install expectbox-agents
+```
+
+Python 3.10+:
+
+```sh
+python -m pip install https://github.com/simon86pl/expectbox-sdk/releases/download/v0.1.1/expectbox_agents-0.1.1-py3-none-any.whl
+```
+
+JavaScript and TypeScript use the [npm package](https://www.npmjs.com/package/expectbox-agents). The Python command installs a versioned GitHub release artifact; PyPI publication is not enabled yet. See [release instructions](https://github.com/simon86pl/expectbox-sdk/blob/main/RELEASING.md).
+
+## Before connecting
+
+1. [Create an Agents account](https://www.expectbox.com/mail?product=agents&signup=1&view=agents) using your current external email, or sign in to an existing Expectbox account.
+2. Verify the email code, then activate a separate Agents subscription or obtain admin-granted Agents access. Personal mailbox payment does not unlock Agents.
+3. In Agents → Project API keys, create a key with the permissions you need. **Project keys (`exp_…`) belong on your backend. Individual agents receive scoped inbox keys (`exa_…`).**
+
+Production provisioning also requires the operator to activate agent mail and DNS/DKIM. A disabled service returns HTTP 503; creating an account or installing this SDK does not enable mail delivery.
+
+## Provision an agent (TypeScript / JavaScript)
+
+```js
+import { ExpectboxProject, ExpectboxAgent } from 'expectbox-agents';
+
+const project = new ExpectboxProject({ apiKey: process.env.EXPECTBOX_PROJECT_API_KEY });
+const inbox = await project.createInbox({
+  name: 'Research assistant',
+  username: 'research',
+  mode: 'drafts',
+  senderManagementMode: 'restricted',
+  senderManagementAllow: ['updates.example.com'],
+}, 'research-inbox-v1'); // Persist this key; reuse it only for the same operation.
+
+const credential = await project.createInboxKey(inbox.id, {
+  name: 'Research runtime',
+  scopes: ['messages:read', 'drafts:write', 'events:read', 'senders:write'],
+  days: 90,
+});
+// Store credential.key in your secret manager. It is returned only once.
+const agent = new ExpectboxAgent({ apiKey: credential.key });
+await agent.allowSender(inbox.id, {
+  matchType: 'domain', matchValue: 'updates.example.com', reason: 'Requested research updates',
+});
+const page = await agent.messages(inbox.id, { limit: 20 });
+console.log(page.items.length);
+```
+
+New inboxes default to read-only with no approved senders, no sending and no sender-management delegation. Setting a delegation does not itself allow incoming mail: call `allowSender` or approve it in the panel. Existing owner blocks always take priority.
+
+## Python
+
+```python
+import os
+from expectbox_agents import ExpectboxProject, ExpectboxAgent
+
+project = ExpectboxProject(os.environ['EXPECTBOX_PROJECT_API_KEY'])
+inbox = project.create_inbox({'name': 'Research assistant', 'username': 'research'}, 'research-inbox-v1')
+credential = project.create_inbox_key(inbox['id'], 'Research runtime', ['messages:read', 'events:read'])
+# Store credential['key'] in your secret manager; never print it.
+agent = ExpectboxAgent(credential['key'])
+page = agent.messages(inbox['id'], limit=20)
+print(len(page['items']))
+```
+
+## API and guarantees
+
+- Base URL: `https://www.expectbox.com/api/agents/v1`. Override `baseUrl` / `base_url` with an HTTPS origin for another deployment; HTTP is accepted only on localhost for tests.
+- Project: `project()`, `inboxes()`, `createInbox()`, `createInboxKey()`, `revokeInboxKey()`; Python uses snake_case.
+- Inbox: `inboxes()`, `messages()`, `message()`, `thread()`, `attachment()`, `draft()`, `editDraft()` / `edit_draft()`, `send()`, `reply()`, `events()`, `senders()`, `allowSender()` / `allow_sender()`.
+- Messages use `items` and `next`. Pass `next.before` and `next.beforeId` to get the next page. Events return `items`, `cursor` and `retentionDays`; persist the cursor after processing.
+- Delivery is queued, not guaranteed by a successful send response. Sending needs `messages:send`, inbox mode `send`, an approved recipient and available quota. Unknown incoming senders are rejected before storage.
+- Inbox creation, sending and replies require your persisted idempotency key. Same key and content return the same result; changed content returns 409. Inbox keys are not idempotent: do not retry key creation blindly after a timeout; inspect/revoke unused keys in the panel.
+- No automatic retries. Retry GETs with backoff; retry idempotent writes using the original key. Errors expose `.status` in JavaScript and standard `urllib.error.HTTPError.code` in Python.
+- Timeouts default to 30 seconds. Configure `timeoutMs` (JS) or `timeout` in seconds (Python). Redirects are rejected so credentials cannot follow them to another origin.
+- Keys expire and can be revoked. Project/inbox limits and paid access are checked by the server, not the SDK. Revoking a project key does not revoke inbox keys it issued; revoke those separately.
+- Never include API keys in client-side apps, source control, logs or prompts. These clients do not execute email content or send messages automatically.
+
+See [openapi.json](https://github.com/simon86pl/expectbox-sdk/blob/main/openapi.json) for the project management contract, TypeScript declarations for return types, and [examples](https://github.com/simon86pl/expectbox-sdk/tree/main/examples) for runnable entry points. The full inbox API is documented at [Expectbox](https://www.expectbox.com/agent-sdk/README.md).
+
+## Contributing
+
+No API key or external mail is needed for tests:
+
+```sh
+npm test
+python -m unittest discover -s tests -p '*_test.py'
+```
+
+The two clients share the API contract and local HTTP contract tests. They are maintained explicitly, not generated. Changes to routes or payloads must update the contract, both clients and tests together.

package/js/expectbox.d.mts

@@ -0,0 +1,106 @@
+export interface Attachment {
+  filename: string;
+  contentType?: string;
+  content: string;
+}
+export interface Draft {
+  to?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject?: string;
+  text?: string;
+  attachments?: Attachment[];
+  replyToId?: string;
+  version?: number;
+}
+export interface Queued {
+  id: string;
+  thread_id: string;
+  status: "queued";
+}
+export interface Message {
+  id: string;
+  thread_id: string;
+  subject: string;
+  body_text: string;
+  from_address: string;
+  revision: number;
+  [key: string]: unknown;
+}
+export interface SenderRule {
+  id: string;
+  match_type: "email" | "domain";
+  match_value: string;
+  policy: string;
+  paused: boolean;
+  paused_until: string | null;
+}
+export class ExpectboxAgent {
+  constructor(options: { apiKey: string; baseUrl?: string; timeoutMs?: number });
+  inboxes(): Promise<{
+    items: { id: string; email: string; name: string; mode: string }[];
+  }>;
+  senders(inbox: string): Promise<{ items: SenderRule[] }>;
+  allowSender(
+    inbox: string,
+    body: { matchType: "email" | "domain"; matchValue: string; reason: string },
+  ): Promise<{ created: boolean; rule: SenderRule }>;
+  messages(
+    inbox: string,
+    query?: {
+      before?: string;
+      beforeId?: string;
+      q?: string;
+      limit?: number;
+      folder?: string;
+    },
+  ): Promise<{
+    items: Message[];
+    next: { before: string; beforeId: string } | null;
+  }>;
+  message(inbox: string, id: string): Promise<Message>;
+  thread(inbox: string, id: string): Promise<{ items: Message[] }>;
+  attachment(inbox: string, id: string): Promise<Uint8Array>;
+  draft(inbox: string, body: Draft): Promise<Message>;
+  editDraft(
+    inbox: string,
+    id: string,
+    body: Draft & { version: number },
+  ): Promise<Message>;
+  send(inbox: string, body: Draft, idempotencyKey: string): Promise<Queued>;
+  reply(
+    inbox: string,
+    id: string,
+    body: Pick<Draft, "text" | "attachments">,
+    idempotencyKey: string,
+  ): Promise<Queued>;
+  events(cursor?: string): Promise<{
+    items: {
+      id: string;
+      type: string;
+      inbox_id: string;
+      message_id: string | null;
+      detail: Record<string, unknown>;
+      created_at: string;
+    }[];
+    cursor: string;
+    retentionDays: number;
+  }>;
+}
+
+export type AgentScope = 'messages:read' | 'attachments:read' | 'drafts:write' | 'messages:send' | 'events:read' | 'senders:write';
+export interface Inbox { id: string; email: string; name: string; }
+export interface CreateInbox {
+  name: string; username: string;
+  mode?: 'read' | 'drafts' | 'send'; sendAllow?: string[];
+  senderManagementMode?: 'none' | 'restricted' | 'any'; senderManagementAllow?: string[];
+}
+export interface InboxKeyOptions { name: string; scopes: AgentScope[]; days?: number; }
+export class ExpectboxProject {
+  constructor(options: { apiKey: string; baseUrl?: string; timeoutMs?: number });
+  project(): Promise<{ id: string; limits: { inboxes: number; monthly: number; daily: number; bytes: number }; usage: { incoming: number; outgoing: number } }>;
+  inboxes(): Promise<{ inboxes: (Inbox & { mode: string; paused: boolean; retired_at: string | null; created_at: string })[] }>;
+  createInbox(body: CreateInbox, idempotencyKey: string): Promise<Inbox>;
+  createInboxKey(inbox: string, body: InboxKeyOptions): Promise<{ id: string; key: string }>;
+  revokeInboxKey(inbox: string, key: string): Promise<{ ok: true }>;
+}

package/js/expectbox.mjs

@@ -0,0 +1,160 @@
+class Client {
+  constructor(
+    { apiKey, baseUrl = "https://www.expectbox.com", timeoutMs = 30000 } = {},
+    prefix,
+  ) {
+    const url = new URL(baseUrl);
+    if (
+      (url.protocol !== "https:" &&
+        !(
+          url.protocol === "http:" &&
+          ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)
+        )) ||
+      url.username ||
+      url.password ||
+      url.search ||
+      url.hash ||
+      url.pathname !== "/"
+    )
+      throw new Error("Use an HTTPS origin or local test origin.");
+    if (!new RegExp(`^${prefix}_[a-zA-Z0-9_-]{43}$`).test(apiKey || ""))
+      throw new Error("Agent API key required.");
+    this.baseUrl = url.origin;
+    Object.defineProperty(this, "apiKey", { value: apiKey });
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300000)
+      throw new Error("Invalid timeoutMs.");
+    this.timeoutMs = timeoutMs;
+  }
+  id(value) {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value || ""))
+      throw new Error("Expected resource UUID.");
+    return value;
+  }
+  async request(
+    path,
+    { method = "GET", body, idempotencyKey, binary = false } = {},
+  ) {
+    const res = await fetch(this.baseUrl + "/api/agents/v1" + path, {
+      method,
+      redirect: "error",
+      signal: AbortSignal.timeout(this.timeoutMs),
+      headers: {
+        Authorization: "Bearer " + this.apiKey,
+        "Content-Type": "application/json",
+        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (!res.ok) {
+      const error = new Error("Expectbox API " + res.status);
+      error.status = res.status;
+      try {
+        error.message = (await res.json()).message || error.message;
+      } catch {}
+      throw error;
+    }
+    return binary ? new Uint8Array(await res.arrayBuffer()) : res.json();
+  }
+}
+export class ExpectboxAgent extends Client {
+  constructor(options) {
+    super(options, "exa");
+  }
+  inboxes() {
+    return this.request("/inboxes");
+  }
+  messages(inbox, query = {}) {
+    return this.request(
+      `/inboxes/${this.id(inbox)}/messages?` +
+        new URLSearchParams(
+          Object.entries(query).filter(([, v]) => v !== undefined),
+        ),
+    );
+  }
+  message(inbox, id) {
+    return this.request(`/inboxes/${this.id(inbox)}/messages/${this.id(id)}`);
+  }
+  thread(inbox, id) {
+    return this.request(`/inboxes/${this.id(inbox)}/threads/${this.id(id)}`);
+  }
+  attachment(inbox, id) {
+    return this.request(
+      `/inboxes/${this.id(inbox)}/attachments/${this.id(id)}`,
+      { binary: true },
+    );
+  }
+  draft(inbox, body) {
+    return this.request(`/inboxes/${this.id(inbox)}/drafts`, {
+      method: "POST",
+      body,
+    });
+  }
+  editDraft(inbox, id, body) {
+    return this.request(`/inboxes/${this.id(inbox)}/drafts/${this.id(id)}`, {
+      method: "PUT",
+      body,
+    });
+  }
+  send(inbox, body, idempotencyKey) {
+    if (!idempotencyKey)
+      throw new Error("Persist an idempotency key before sending.");
+    return this.request(`/inboxes/${this.id(inbox)}/send`, {
+      method: "POST",
+      body,
+      idempotencyKey,
+    });
+  }
+  reply(inbox, id, body, idempotencyKey) {
+    if (!idempotencyKey)
+      throw new Error("Persist an idempotency key before replying.");
+    return this.request(
+      `/inboxes/${this.id(inbox)}/messages/${this.id(id)}/reply`,
+      { method: "POST", body, idempotencyKey },
+    );
+  }
+  events(cursor = "0") {
+    return this.request("/events?" + new URLSearchParams({ cursor }));
+  }
+  senders(inbox) {
+    return this.request(`/inboxes/${this.id(inbox)}/senders`);
+  }
+  allowSender(inbox, body) {
+    return this.request(`/inboxes/${this.id(inbox)}/senders`, {
+      method: "POST",
+      body,
+    });
+  }
+}
+
+export class ExpectboxProject extends Client {
+  constructor(options) {
+    super(options, "exp");
+  }
+  project() {
+    return this.request("/project");
+  }
+  inboxes() {
+    return this.request("/project/inboxes");
+  }
+  createInbox(body, idempotencyKey) {
+    if (!idempotencyKey)
+      throw new Error("Persist an idempotency key before creating an inbox.");
+    return this.request("/project/inboxes", {
+      method: "POST",
+      body,
+      idempotencyKey,
+    });
+  }
+  createInboxKey(inbox, body) {
+    return this.request(`/project/inboxes/${this.id(inbox)}/keys`, {
+      method: "POST",
+      body,
+    });
+  }
+  revokeInboxKey(inbox, key) {
+    return this.request(
+      `/project/inboxes/${this.id(inbox)}/keys/${this.id(key)}`,
+      { method: "DELETE" },
+    );
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "expectbox-agents",
+  "version": "0.1.1",
+  "description": "Scoped email inboxes for agents: Expectbox TypeScript and JavaScript SDK",
+  "type": "module",
+  "main": "./js/expectbox.mjs",
+  "types": "./js/expectbox.d.mts",
+  "exports": {
+    ".": {
+      "types": "./js/expectbox.d.mts",
+      "import": "./js/expectbox.mjs",
+      "default": "./js/expectbox.mjs"
+    }
+  },
+  "files": [
+    "js/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simon86pl/expectbox-sdk.git"
+  },
+  "homepage": "https://www.expectbox.com/",
+  "bugs": "https://github.com/simon86pl/expectbox-sdk/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}