ironpost 0.2.0

package/README.md

@@ -0,0 +1,148 @@
+# Ironpost SDK
+
+[![npm version](https://img.shields.io/npm/v/ironpost.svg)](https://www.npmjs.com/package/ironpost)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The official TypeScript SDK for [Ironpost](https://ironpost.ai) — email inboxes for AI agents.
+
+Zero dependencies. Works in Node.js, Deno, Bun, Cloudflare Workers, and anywhere with native `fetch`.
+
+## Why Ironpost?
+
+AI agents need to send and receive email, but existing APIs (SendGrid, Resend, Mailgun) are built for human-configured transactional workflows. Ironpost gives each agent its own email address and persistent inbox with thread history, webhook delivery, and built-in spam/phishing protection — purpose-built for autonomous agents.
+
+| | Ironpost | SendGrid / Resend | Raw SMTP |
+|---|---|---|---|
+| Agent gets own email address | ✅ Auto-generated | ❌ Shared sender | ❌ Manual config |
+| Persistent inbox with history | ✅ Query threads, unreads | ❌ Send-only | ❌ Build it yourself |
+| Agent-to-agent (free) | ✅ Instant, $0 | ❌ Per-message | ❌ Per-message |
+| Spam & phishing protection | ✅ Built-in | ❌ None | ❌ Build it yourself |
+| Real-time webhooks | ✅ HMAC-signed | ⚠️ Varies | ❌ Build it yourself |
+| Zero dependencies | ✅ Native fetch | ❌ Heavy SDKs | ❌ nodemailer, etc. |
+
+## Installation
+
+```bash
+npm install ironpost
+```
+
+## Quick Start
+
+```ts
+import { Ironpost } from "ironpost";
+
+// 1. Create your org (one-time)
+const { organization, apiKey } = await Ironpost.setup({
+  orgName: "Acme Corp",
+  ownerEmail: "founders@acme.com",
+});
+
+// 2. Initialize the client
+const ironpost = new Ironpost(apiKey.key);
+
+// 3. Create an agent (gets auto-generated address like brave-eagle-fly@ironpost.email)
+const agent = await ironpost.agents.create({
+  name: "Customer Service Agent",
+});
+
+// 4. Send a message
+await ironpost.messages.send({
+  from: agent.id,
+  to: "user@example.com",
+  subject: "How can I help you?",
+  body: "Send me your request and I will process it.",
+});
+
+// 5. Listen for replies
+await ironpost.webhooks.register(agent.id, {
+  url: "https://my-app.com/api/webhooks/ironpost",
+  events: ["message.received"],
+});
+```
+
+## Use Cases
+
+**Customer support agent** — Give your support bot an email address. Customers email it directly, the agent processes and replies.
+
+**Multi-agent workflows** — Agents email each other for free. A research agent emails findings to an analysis agent, which emails a summary to a reporting agent.
+
+**Notification handler** — Forward SaaS alerts (Stripe, GitHub, etc.) to an agent that monitors, triages, and escalates.
+
+**Outbound campaigns** — Agent sends personalized emails to leads at $0.001/email with full deliverability (SPF, DKIM, DMARC).
+
+## API Overview
+
+### Agents
+```ts
+const agent = await ironpost.agents.create({ name: "Support" });
+const agents = await ironpost.agents.list();
+const one = await ironpost.agents.get(agentId);
+await ironpost.agents.update(agentId, { name: "New Name" });
+await ironpost.agents.delete(agentId);
+```
+
+### Messages
+```ts
+await ironpost.messages.send({ from: agentId, to: "user@gmail.com", subject: "Hi", body: "Hello" });
+const msg = await ironpost.messages.get(messageId);
+await ironpost.messages.reply(messageId, { from: agentId, body: "Thanks!" });
+```
+
+### Inbox & Threads
+```ts
+const inbox = await ironpost.agents.messages(agentId, { limit: 20 });
+const threads = await ironpost.agents.threads(agentId);
+const thread = await ironpost.agents.thread(agentId, threadId);
+```
+
+### Webhooks
+```ts
+await ironpost.webhooks.register(agentId, { url: "https://...", events: ["message.received"] });
+const hooks = await ironpost.webhooks.list(agentId);
+await ironpost.webhooks.delete(agentId, webhookId);
+
+// Verify incoming webhook signatures
+const isValid = await Ironpost.verifyWebhook(rawBody, signatureHeader, webhookSecret);
+```
+
+### Attachments
+```ts
+const attachment = await ironpost.attachments.upload({
+  agentId,
+  filename: "report.pdf",
+  content: base64String,
+});
+const response = await ironpost.attachments.download(attachmentId);
+```
+
+## Configuration
+
+```ts
+// API key as string
+const client = new Ironpost("ip_key_live_...");
+
+// Or via environment variable (auto-detected)
+// Set IRONPOST_API_KEY in your environment
+const client = new Ironpost();
+
+// Or with options object
+const client = new Ironpost({
+  apiKey: "ip_key_live_...",
+  baseUrl: "https://api.ironpost.ai", // default
+});
+```
+
+## Pricing
+
+- **In-network** (agent ↔ agent): Free, instant
+- **Inbound** (anyone → agent): Free
+- **Outbound** (agent → external): $0.001/email
+- **Free tier**: 5 agents, 100 outbound/month
+
+## Documentation
+
+Full API reference: [ironpost.ai/docs.html](https://ironpost.ai/docs.html)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,254 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Ironpost: () => Ironpost,
+  IronpostError: () => IronpostError
+});
+module.exports = __toCommonJS(index_exports);
+var IronpostError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "IronpostError";
+  }
+};
+var HttpClient = class {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      throw new IronpostError(
+        data.error ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+};
+var AgentsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Create a new agent. */
+  create(params) {
+    return this.http.post("/v1/agents", params);
+  }
+  /** List all agents in your organization. */
+  list() {
+    return this.http.get("/v1/agents");
+  }
+  /** Get a single agent by ID. */
+  get(agentId) {
+    return this.http.get(`/v1/agents/${agentId}`);
+  }
+  /** Update an agent. */
+  update(agentId, params) {
+    return this.http.patch(`/v1/agents/${agentId}`, params);
+  }
+  /** Delete an agent and all associated data. */
+  delete(agentId) {
+    return this.http.delete(`/v1/agents/${agentId}`);
+  }
+  /** List inbox messages for an agent. */
+  messages(agentId, opts) {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.cursor) params.set("cursor", opts.cursor);
+    const qs = params.toString();
+    return this.http.get(`/v1/agents/${agentId}/messages${qs ? `?${qs}` : ""}`);
+  }
+  /** List threads for an agent. */
+  threads(agentId) {
+    return this.http.get(`/v1/agents/${agentId}/threads`);
+  }
+  /** Get a thread and its messages. */
+  thread(agentId, threadId) {
+    return this.http.get(`/v1/agents/${agentId}/threads/${threadId}`);
+  }
+};
+var MessagesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Send a message. If both sides are on Ironpost, delivery is instant and free. */
+  send(params) {
+    return this.http.post("/v1/messages", params);
+  }
+  /** Get a single message by ID. */
+  get(messageId) {
+    return this.http.get(`/v1/messages/${messageId}`);
+  }
+  /** Reply in the same thread as an existing message. */
+  reply(messageId, params) {
+    return this.http.post(`/v1/messages/${messageId}/reply`, params);
+  }
+};
+var WebhooksClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Register a webhook for an agent. */
+  register(agentId, params) {
+    return this.http.post(
+      `/v1/agents/${agentId}/webhooks`,
+      params
+    );
+  }
+  /** List webhooks for an agent. */
+  list(agentId) {
+    return this.http.get(`/v1/agents/${agentId}/webhooks`);
+  }
+  /** Delete a webhook. */
+  delete(agentId, webhookId) {
+    return this.http.delete(
+      `/v1/agents/${agentId}/webhooks/${webhookId}`
+    );
+  }
+};
+var AttachmentsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Upload an attachment. Returns metadata with `id` for referencing. */
+  upload(params) {
+    return this.http.post("/v1/attachments", params);
+  }
+  /** Download an attachment by ID. Returns the raw Response for streaming. */
+  async download(attachmentId) {
+    const url = `${this.http.baseUrl}/v1/attachments/${attachmentId}`;
+    return fetch(url, {
+      headers: {
+        Authorization: `Bearer ${this.http.apiKey}`
+      }
+    });
+  }
+};
+var Ironpost = class {
+  agents;
+  messages;
+  webhooks;
+  attachments;
+  constructor(apiKeyOrOpts, extraOpts) {
+    let apiKey;
+    let baseUrl;
+    if (typeof apiKeyOrOpts === "string") {
+      apiKey = apiKeyOrOpts;
+      baseUrl = extraOpts?.baseUrl;
+    } else if (apiKeyOrOpts) {
+      apiKey = apiKeyOrOpts.apiKey;
+      baseUrl = apiKeyOrOpts.baseUrl;
+    }
+    if (!apiKey && typeof process !== "undefined" && process.env?.IRONPOST_API_KEY) {
+      apiKey = process.env.IRONPOST_API_KEY;
+    }
+    if (!apiKey) {
+      throw new Error(
+        "Ironpost SDK requires an API key. Pass it to the constructor or set IRONPOST_API_KEY."
+      );
+    }
+    baseUrl = baseUrl ?? "https://api.ironpost.ai";
+    const http = new HttpClient(baseUrl, apiKey);
+    this.agents = new AgentsClient(http);
+    this.messages = new MessagesClient(http);
+    this.webhooks = new WebhooksClient(http);
+    this.attachments = new AttachmentsClient(http);
+  }
+  // ── Static Helpers ──────────────────────────────────────────────
+  /**
+   * Provision a new Organization and generate the initial API key.
+   * This endpoint is meant for platform setup or bootstrapping environments.
+   *
+   * @param params  orgName and ownerEmail for the new organization
+   * @param opts    Optional configuration (like replacing baseUrl for local dev)
+   * @returns       The created Organization and the one-time raw API key.
+   */
+  static async setup(params, opts) {
+    const url = `${opts?.baseUrl ?? "https://api.ironpost.ai"}/v1/setup`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params)
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      throw new IronpostError(
+        data.error ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+  /**
+   * Verify an incoming webhook signature.
+   *
+   * @param payload  Raw request body (string)
+   * @param signature  Value of the X-Ironpost-Signature header
+   * @param secret  The webhook secret returned at registration
+   * @returns true if the signature is valid
+   */
+  static async verifyWebhook(payload, signature, secret) {
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      enc.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await crypto.subtle.sign("HMAC", key, enc.encode(payload));
+    const expected = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    return expected === signature;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Ironpost,
+  IronpostError
+});

package/dist/index.d.cts

@@ -0,0 +1,243 @@
+/**
+ * packages/sdk — TypeScript SDK for Ironpost.
+ *
+ * Published to npm as "ironpost".
+ * Zero dependencies — uses native fetch.
+ *
+ * All types are defined inline to avoid coupling with internal packages.
+ */
+interface Organization {
+    id: string;
+    name: string;
+    plan: "free" | "paid";
+    ownerEmail: string;
+    emailVerified: boolean;
+    egressQuota: number;
+    agentQuota: number;
+    createdAt: string;
+}
+interface Agent {
+    id: string;
+    orgId: string;
+    name: string;
+    slug: string;
+    address: string;
+    endpointUrl?: string;
+    reputationScore: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Message {
+    id: string;
+    threadId?: string;
+    sender: string;
+    recipient: string;
+    type: "internal" | "egress" | "ingress";
+    subject?: string;
+    body: string;
+    attachments?: Attachment[];
+    score?: number;
+    scoreAction?: "accept" | "flag" | "quarantine" | "reject";
+    status: "delivered" | "failed" | "quarantined" | "pending";
+    inNetwork: boolean;
+    messageId?: string;
+    inReplyTo?: string;
+    sentAt?: string;
+    receivedAt?: string;
+    deliveryMs?: number;
+    createdAt: string;
+}
+interface Thread {
+    id: string;
+    subject?: string;
+    participants: string[];
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Webhook {
+    id: string;
+    agentId: string;
+    url: string;
+    secret: string;
+    events: string[];
+    enabled: boolean;
+    createdAt: string;
+}
+interface Attachment {
+    id: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    key: string;
+}
+interface IronpostOptions {
+    /** Your API key (ip_key_...) */
+    apiKey: string;
+    /** Override the base URL (default: https://api.ironpost.ai) */
+    baseUrl?: string;
+}
+interface CreateAgentParams {
+    name: string;
+    endpointUrl?: string;
+}
+interface UpdateAgentParams {
+    name?: string;
+    endpointUrl?: string | null;
+}
+interface SendMessageParams {
+    from: string;
+    to: string;
+    subject?: string;
+    body: string;
+    threadId?: string;
+    attachments?: {
+        filename: string;
+        contentType?: string;
+        content: string;
+    }[];
+}
+interface UploadAttachmentParams {
+    agentId: string;
+    filename: string;
+    contentType?: string;
+    content: string;
+}
+interface ReplyParams {
+    from: string;
+    body: string;
+    subject?: string;
+}
+interface RegisterWebhookParams {
+    url: string;
+    events?: string[];
+}
+interface ListOptions {
+    limit?: number;
+    cursor?: string;
+}
+declare class IronpostError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private request;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+declare class AgentsClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Create a new agent. */
+    create(params: CreateAgentParams): Promise<Agent>;
+    /** List all agents in your organization. */
+    list(): Promise<{
+        agents: Agent[];
+        total: number;
+    }>;
+    /** Get a single agent by ID. */
+    get(agentId: string): Promise<Agent>;
+    /** Update an agent. */
+    update(agentId: string, params: UpdateAgentParams): Promise<Agent>;
+    /** Delete an agent and all associated data. */
+    delete(agentId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** List inbox messages for an agent. */
+    messages(agentId: string, opts?: ListOptions): Promise<{
+        messages: Message[];
+        cursor?: string;
+    }>;
+    /** List threads for an agent. */
+    threads(agentId: string): Promise<{
+        threads: Thread[];
+        total: number;
+    }>;
+    /** Get a thread and its messages. */
+    thread(agentId: string, threadId: string): Promise<{
+        thread: Thread;
+        messages: Message[];
+    }>;
+}
+declare class MessagesClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Send a message. If both sides are on Ironpost, delivery is instant and free. */
+    send(params: SendMessageParams): Promise<Message>;
+    /** Get a single message by ID. */
+    get(messageId: string): Promise<Message>;
+    /** Reply in the same thread as an existing message. */
+    reply(messageId: string, params: ReplyParams): Promise<Message>;
+}
+declare class WebhooksClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Register a webhook for an agent. */
+    register(agentId: string, params: RegisterWebhookParams): Promise<Webhook>;
+    /** List webhooks for an agent. */
+    list(agentId: string): Promise<{
+        webhooks: Webhook[];
+        total: number;
+    }>;
+    /** Delete a webhook. */
+    delete(agentId: string, webhookId: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+declare class AttachmentsClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Upload an attachment. Returns metadata with `id` for referencing. */
+    upload(params: UploadAttachmentParams): Promise<Attachment>;
+    /** Download an attachment by ID. Returns the raw Response for streaming. */
+    download(attachmentId: string): Promise<Response>;
+}
+declare class Ironpost {
+    readonly agents: AgentsClient;
+    readonly messages: MessagesClient;
+    readonly webhooks: WebhooksClient;
+    readonly attachments: AttachmentsClient;
+    constructor(apiKey?: string, opts?: {
+        baseUrl?: string;
+    });
+    constructor(opts?: IronpostOptions);
+    /**
+     * Provision a new Organization and generate the initial API key.
+     * This endpoint is meant for platform setup or bootstrapping environments.
+     *
+     * @param params  orgName and ownerEmail for the new organization
+     * @param opts    Optional configuration (like replacing baseUrl for local dev)
+     * @returns       The created Organization and the one-time raw API key.
+     */
+    static setup(params: {
+        orgName: string;
+        ownerEmail: string;
+    }, opts?: {
+        baseUrl?: string;
+    }): Promise<{
+        organization: Organization;
+        apiKey: {
+            id: string;
+            key: string;
+            prefix: string;
+            scopes: string[];
+        };
+    }>;
+    /**
+     * Verify an incoming webhook signature.
+     *
+     * @param payload  Raw request body (string)
+     * @param signature  Value of the X-Ironpost-Signature header
+     * @param secret  The webhook secret returned at registration
+     * @returns true if the signature is valid
+     */
+    static verifyWebhook(payload: string, signature: string, secret: string): Promise<boolean>;
+}
+
+export { type Agent, type Attachment, type CreateAgentParams, Ironpost, IronpostError, type IronpostOptions, type ListOptions, type Message, type Organization, type RegisterWebhookParams, type ReplyParams, type SendMessageParams, type Thread, type UpdateAgentParams, type UploadAttachmentParams, type Webhook };

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+/**
+ * packages/sdk — TypeScript SDK for Ironpost.
+ *
+ * Published to npm as "ironpost".
+ * Zero dependencies — uses native fetch.
+ *
+ * All types are defined inline to avoid coupling with internal packages.
+ */
+interface Organization {
+    id: string;
+    name: string;
+    plan: "free" | "paid";
+    ownerEmail: string;
+    emailVerified: boolean;
+    egressQuota: number;
+    agentQuota: number;
+    createdAt: string;
+}
+interface Agent {
+    id: string;
+    orgId: string;
+    name: string;
+    slug: string;
+    address: string;
+    endpointUrl?: string;
+    reputationScore: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Message {
+    id: string;
+    threadId?: string;
+    sender: string;
+    recipient: string;
+    type: "internal" | "egress" | "ingress";
+    subject?: string;
+    body: string;
+    attachments?: Attachment[];
+    score?: number;
+    scoreAction?: "accept" | "flag" | "quarantine" | "reject";
+    status: "delivered" | "failed" | "quarantined" | "pending";
+    inNetwork: boolean;
+    messageId?: string;
+    inReplyTo?: string;
+    sentAt?: string;
+    receivedAt?: string;
+    deliveryMs?: number;
+    createdAt: string;
+}
+interface Thread {
+    id: string;
+    subject?: string;
+    participants: string[];
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Webhook {
+    id: string;
+    agentId: string;
+    url: string;
+    secret: string;
+    events: string[];
+    enabled: boolean;
+    createdAt: string;
+}
+interface Attachment {
+    id: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    key: string;
+}
+interface IronpostOptions {
+    /** Your API key (ip_key_...) */
+    apiKey: string;
+    /** Override the base URL (default: https://api.ironpost.ai) */
+    baseUrl?: string;
+}
+interface CreateAgentParams {
+    name: string;
+    endpointUrl?: string;
+}
+interface UpdateAgentParams {
+    name?: string;
+    endpointUrl?: string | null;
+}
+interface SendMessageParams {
+    from: string;
+    to: string;
+    subject?: string;
+    body: string;
+    threadId?: string;
+    attachments?: {
+        filename: string;
+        contentType?: string;
+        content: string;
+    }[];
+}
+interface UploadAttachmentParams {
+    agentId: string;
+    filename: string;
+    contentType?: string;
+    content: string;
+}
+interface ReplyParams {
+    from: string;
+    body: string;
+    subject?: string;
+}
+interface RegisterWebhookParams {
+    url: string;
+    events?: string[];
+}
+interface ListOptions {
+    limit?: number;
+    cursor?: string;
+}
+declare class IronpostError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private request;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+declare class AgentsClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Create a new agent. */
+    create(params: CreateAgentParams): Promise<Agent>;
+    /** List all agents in your organization. */
+    list(): Promise<{
+        agents: Agent[];
+        total: number;
+    }>;
+    /** Get a single agent by ID. */
+    get(agentId: string): Promise<Agent>;
+    /** Update an agent. */
+    update(agentId: string, params: UpdateAgentParams): Promise<Agent>;
+    /** Delete an agent and all associated data. */
+    delete(agentId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** List inbox messages for an agent. */
+    messages(agentId: string, opts?: ListOptions): Promise<{
+        messages: Message[];
+        cursor?: string;
+    }>;
+    /** List threads for an agent. */
+    threads(agentId: string): Promise<{
+        threads: Thread[];
+        total: number;
+    }>;
+    /** Get a thread and its messages. */
+    thread(agentId: string, threadId: string): Promise<{
+        thread: Thread;
+        messages: Message[];
+    }>;
+}
+declare class MessagesClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Send a message. If both sides are on Ironpost, delivery is instant and free. */
+    send(params: SendMessageParams): Promise<Message>;
+    /** Get a single message by ID. */
+    get(messageId: string): Promise<Message>;
+    /** Reply in the same thread as an existing message. */
+    reply(messageId: string, params: ReplyParams): Promise<Message>;
+}
+declare class WebhooksClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Register a webhook for an agent. */
+    register(agentId: string, params: RegisterWebhookParams): Promise<Webhook>;
+    /** List webhooks for an agent. */
+    list(agentId: string): Promise<{
+        webhooks: Webhook[];
+        total: number;
+    }>;
+    /** Delete a webhook. */
+    delete(agentId: string, webhookId: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+declare class AttachmentsClient {
+    private http;
+    constructor(http: HttpClient);
+    /** Upload an attachment. Returns metadata with `id` for referencing. */
+    upload(params: UploadAttachmentParams): Promise<Attachment>;
+    /** Download an attachment by ID. Returns the raw Response for streaming. */
+    download(attachmentId: string): Promise<Response>;
+}
+declare class Ironpost {
+    readonly agents: AgentsClient;
+    readonly messages: MessagesClient;
+    readonly webhooks: WebhooksClient;
+    readonly attachments: AttachmentsClient;
+    constructor(apiKey?: string, opts?: {
+        baseUrl?: string;
+    });
+    constructor(opts?: IronpostOptions);
+    /**
+     * Provision a new Organization and generate the initial API key.
+     * This endpoint is meant for platform setup or bootstrapping environments.
+     *
+     * @param params  orgName and ownerEmail for the new organization
+     * @param opts    Optional configuration (like replacing baseUrl for local dev)
+     * @returns       The created Organization and the one-time raw API key.
+     */
+    static setup(params: {
+        orgName: string;
+        ownerEmail: string;
+    }, opts?: {
+        baseUrl?: string;
+    }): Promise<{
+        organization: Organization;
+        apiKey: {
+            id: string;
+            key: string;
+            prefix: string;
+            scopes: string[];
+        };
+    }>;
+    /**
+     * Verify an incoming webhook signature.
+     *
+     * @param payload  Raw request body (string)
+     * @param signature  Value of the X-Ironpost-Signature header
+     * @param secret  The webhook secret returned at registration
+     * @returns true if the signature is valid
+     */
+    static verifyWebhook(payload: string, signature: string, secret: string): Promise<boolean>;
+}
+
+export { type Agent, type Attachment, type CreateAgentParams, Ironpost, IronpostError, type IronpostOptions, type ListOptions, type Message, type Organization, type RegisterWebhookParams, type ReplyParams, type SendMessageParams, type Thread, type UpdateAgentParams, type UploadAttachmentParams, type Webhook };

package/dist/index.js

@@ -0,0 +1,228 @@
+// src/index.ts
+var IronpostError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "IronpostError";
+  }
+};
+var HttpClient = class {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      throw new IronpostError(
+        data.error ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+};
+var AgentsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Create a new agent. */
+  create(params) {
+    return this.http.post("/v1/agents", params);
+  }
+  /** List all agents in your organization. */
+  list() {
+    return this.http.get("/v1/agents");
+  }
+  /** Get a single agent by ID. */
+  get(agentId) {
+    return this.http.get(`/v1/agents/${agentId}`);
+  }
+  /** Update an agent. */
+  update(agentId, params) {
+    return this.http.patch(`/v1/agents/${agentId}`, params);
+  }
+  /** Delete an agent and all associated data. */
+  delete(agentId) {
+    return this.http.delete(`/v1/agents/${agentId}`);
+  }
+  /** List inbox messages for an agent. */
+  messages(agentId, opts) {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.cursor) params.set("cursor", opts.cursor);
+    const qs = params.toString();
+    return this.http.get(`/v1/agents/${agentId}/messages${qs ? `?${qs}` : ""}`);
+  }
+  /** List threads for an agent. */
+  threads(agentId) {
+    return this.http.get(`/v1/agents/${agentId}/threads`);
+  }
+  /** Get a thread and its messages. */
+  thread(agentId, threadId) {
+    return this.http.get(`/v1/agents/${agentId}/threads/${threadId}`);
+  }
+};
+var MessagesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Send a message. If both sides are on Ironpost, delivery is instant and free. */
+  send(params) {
+    return this.http.post("/v1/messages", params);
+  }
+  /** Get a single message by ID. */
+  get(messageId) {
+    return this.http.get(`/v1/messages/${messageId}`);
+  }
+  /** Reply in the same thread as an existing message. */
+  reply(messageId, params) {
+    return this.http.post(`/v1/messages/${messageId}/reply`, params);
+  }
+};
+var WebhooksClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Register a webhook for an agent. */
+  register(agentId, params) {
+    return this.http.post(
+      `/v1/agents/${agentId}/webhooks`,
+      params
+    );
+  }
+  /** List webhooks for an agent. */
+  list(agentId) {
+    return this.http.get(`/v1/agents/${agentId}/webhooks`);
+  }
+  /** Delete a webhook. */
+  delete(agentId, webhookId) {
+    return this.http.delete(
+      `/v1/agents/${agentId}/webhooks/${webhookId}`
+    );
+  }
+};
+var AttachmentsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Upload an attachment. Returns metadata with `id` for referencing. */
+  upload(params) {
+    return this.http.post("/v1/attachments", params);
+  }
+  /** Download an attachment by ID. Returns the raw Response for streaming. */
+  async download(attachmentId) {
+    const url = `${this.http.baseUrl}/v1/attachments/${attachmentId}`;
+    return fetch(url, {
+      headers: {
+        Authorization: `Bearer ${this.http.apiKey}`
+      }
+    });
+  }
+};
+var Ironpost = class {
+  agents;
+  messages;
+  webhooks;
+  attachments;
+  constructor(apiKeyOrOpts, extraOpts) {
+    let apiKey;
+    let baseUrl;
+    if (typeof apiKeyOrOpts === "string") {
+      apiKey = apiKeyOrOpts;
+      baseUrl = extraOpts?.baseUrl;
+    } else if (apiKeyOrOpts) {
+      apiKey = apiKeyOrOpts.apiKey;
+      baseUrl = apiKeyOrOpts.baseUrl;
+    }
+    if (!apiKey && typeof process !== "undefined" && process.env?.IRONPOST_API_KEY) {
+      apiKey = process.env.IRONPOST_API_KEY;
+    }
+    if (!apiKey) {
+      throw new Error(
+        "Ironpost SDK requires an API key. Pass it to the constructor or set IRONPOST_API_KEY."
+      );
+    }
+    baseUrl = baseUrl ?? "https://api.ironpost.ai";
+    const http = new HttpClient(baseUrl, apiKey);
+    this.agents = new AgentsClient(http);
+    this.messages = new MessagesClient(http);
+    this.webhooks = new WebhooksClient(http);
+    this.attachments = new AttachmentsClient(http);
+  }
+  // ── Static Helpers ──────────────────────────────────────────────
+  /**
+   * Provision a new Organization and generate the initial API key.
+   * This endpoint is meant for platform setup or bootstrapping environments.
+   *
+   * @param params  orgName and ownerEmail for the new organization
+   * @param opts    Optional configuration (like replacing baseUrl for local dev)
+   * @returns       The created Organization and the one-time raw API key.
+   */
+  static async setup(params, opts) {
+    const url = `${opts?.baseUrl ?? "https://api.ironpost.ai"}/v1/setup`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params)
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      throw new IronpostError(
+        data.error ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+  /**
+   * Verify an incoming webhook signature.
+   *
+   * @param payload  Raw request body (string)
+   * @param signature  Value of the X-Ironpost-Signature header
+   * @param secret  The webhook secret returned at registration
+   * @returns true if the signature is valid
+   */
+  static async verifyWebhook(payload, signature, secret) {
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      enc.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await crypto.subtle.sign("HMAC", key, enc.encode(payload));
+    const expected = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    return expected === signature;
+  }
+};
+export {
+  Ironpost,
+  IronpostError
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "ironpost",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "bun run build"
+  },
+  "license": "MIT",
+  "description": "TypeScript SDK for Ironpost - email inboxes for AI agents. Zero dependencies.",
+  "homepage": "https://ironpost.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ironposthq/ironpost-js"
+  },
+  "bugs": {
+    "url": "https://github.com/ironposthq/ironpost-js/issues"
+  },
+  "author": "Ironpost <hello@ironpost.ai>",
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "email",
+    "email-api",
+    "email-infrastructure",
+    "messaging",
+    "ai",
+    "ironpost",
+    "agent-email",
+    "agent-messaging",
+    "agent-infrastructure",
+    "llm",
+    "autonomous-agent",
+    "webhook",
+    "smtp",
+    "inbox",
+    "ai-infrastructure",
+    "mcp",
+    "langchain",
+    "crewai",
+    "agent-communication",
+    "agent-to-agent"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}