@mailsai/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,674 @@
+// @mailsai/sdk — TypeScript client for the Mails.ai API.
+// 6 lines to give an AI agent a working email primitive:
+//
+//   import { mails } from "@mailsai/sdk";
+//   const sarah = mails.agent("sarah");
+//   await sarah.send({ to: "lead@acme.com", subject: "Demo", body: "Hi…" });
+import crypto from "crypto";
+const DEFAULT_BASE = "https://api.mails.ai";
+// Bounded exponential backoff for transient failures (429 / retry-safe 5xx).
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 500;
+const RETRY_CAP_MS = 8000;
+class MailsError extends Error {
+    type;
+    code;
+    status;
+    requestId;
+    param;
+    constructor(opts) {
+        super(opts.message);
+        this.name = "MailsError";
+        this.type = opts.type;
+        this.code = opts.code;
+        this.status = opts.status;
+        this.requestId = opts.requestId;
+        this.param = opts.param;
+    }
+}
+class MailsClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    messages;
+    received;
+    threads;
+    drafts;
+    events;
+    agents;
+    suppression;
+    api_keys;
+    webhooks;
+    reputation;
+    billing;
+    logs;
+    constructor(opts = {}) {
+        const envKey = typeof process !== "undefined" ? process.env?.MAILS_API_KEY : undefined;
+        const envBase = typeof process !== "undefined" ? process.env?.MAILS_BASE_URL : undefined;
+        this.apiKey = opts.apiKey ?? envKey ?? "";
+        this.baseUrl = (opts.baseUrl ?? envBase ?? DEFAULT_BASE).replace(/\/+$/, "");
+        this.fetchImpl = opts.fetch ?? fetch;
+        if (!this.apiKey) {
+            throw new Error("Mails.ai SDK: apiKey not provided and MAILS_API_KEY env var not set.");
+        }
+        this.messages = new MessagesResource(this);
+        this.received = new ReceivedResource(this);
+        this.threads = new ThreadsResource(this);
+        this.drafts = new DraftsResource(this);
+        this.events = new EventsResource(this);
+        this.agents = new AgentsResource(this);
+        this.suppression = new SuppressionResource(this);
+        this.api_keys = new ApiKeysResource(this);
+        this.webhooks = new WebhooksResource(this);
+        this.reputation = new ReputationResource(this);
+        this.billing = new BillingResource(this);
+        this.logs = new LogsResource(this);
+    }
+    agent(name) {
+        return new Agent(this, name);
+    }
+    async send(agent, input) {
+        return this.messages.send(agent, input);
+    }
+    async createAgent(name, options) {
+        return this.agents.create(name, options);
+    }
+    async listAgents(opts) {
+        return this.agents.list(opts);
+    }
+    async me() {
+        return this.request("GET", "/api/v1/me");
+    }
+    // Raw helpers used by resources
+    request(method, path, body, headersIn) {
+        return this._request(method, path, body, headersIn);
+    }
+    async _request(method, path, body, headersIn) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            ...(headersIn ?? {}),
+        };
+        const payload = body !== undefined ? JSON.stringify(body) : undefined;
+        // A retry is safe when the request can't have applied a side effect twice:
+        // a 429 was REJECTED (rate-limited, never processed), and 5xx is only retried
+        // for read methods or when an Idempotency-Key makes a resend a no-op server-side.
+        const idempotentMethod = method === "GET" || method === "HEAD";
+        const hasIdemKey = Object.keys(headers).some((k) => k.toLowerCase() === "idempotency-key");
+        for (let attempt = 0;; attempt++) {
+            const res = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers, body: payload });
+            const requestId = res.headers.get("x-request-id") ?? undefined;
+            if (res.ok) {
+                if (res.status === 204)
+                    return undefined;
+                return (await res.json());
+            }
+            const retryable = attempt < MAX_RETRIES && (res.status === 429 || (res.status >= 500 && (idempotentMethod || hasIdemKey)));
+            if (retryable) {
+                const retryAfter = Number(res.headers.get("retry-after"));
+                const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
+                    ? retryAfter * 1000
+                    : Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** attempt);
+                await new Promise((r) => setTimeout(r, waitMs));
+                continue;
+            }
+            let err = {};
+            try {
+                err = await res.json();
+            }
+            catch {
+                /* ignore */
+            }
+            throw new MailsError({
+                type: err.error?.type ?? "api_error",
+                code: err.error?.code ?? "unknown",
+                message: err.error?.message ?? `${method} ${path} failed with ${res.status}`,
+                status: res.status,
+                requestId,
+                param: err.error?.param,
+            });
+        }
+    }
+    async requestText(method, path, body, headersIn) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            ...(headersIn ?? {}),
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            let err = {};
+            try {
+                err = await res.json();
+            }
+            catch {
+                /* ignore */
+            }
+            throw new MailsError({
+                type: err.error?.type ?? "api_error",
+                code: err.error?.code ?? "unknown",
+                message: err.error?.message ?? `${method} ${path} failed with ${res.status}`,
+                status: res.status,
+            });
+        }
+        return await res.text();
+    }
+    // SSE stream helper. Returns AbortController; caller closes via abort().
+    stream(opts) {
+        const ctrl = new AbortController();
+        if (opts.signal)
+            opts.signal.addEventListener("abort", () => ctrl.abort());
+        const qs = new URLSearchParams();
+        if (opts.since)
+            qs.set("since", opts.since);
+        if (opts.event_types)
+            qs.set("event_types", opts.event_types.join(","));
+        const url = `${this.baseUrl}/api/v1/events/stream${qs.toString() ? "?" + qs.toString() : ""}`;
+        void (async () => {
+            try {
+                const res = await this.fetchImpl(url, {
+                    headers: { Authorization: `Bearer ${this.apiKey}`, Accept: "text/event-stream" },
+                    signal: ctrl.signal,
+                });
+                if (!res.ok || !res.body) {
+                    opts.onError?.(new Error(`stream HTTP ${res.status}`));
+                    return;
+                }
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                // eslint-disable-next-line no-constant-condition
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    let idx;
+                    while ((idx = buffer.indexOf("\n\n")) !== -1) {
+                        const chunk = buffer.slice(0, idx);
+                        buffer = buffer.slice(idx + 2);
+                        const dataLine = chunk.split("\n").find((l) => l.startsWith("data: "));
+                        if (dataLine) {
+                            try {
+                                const evt = JSON.parse(dataLine.slice(6));
+                                opts.onEvent(evt);
+                            }
+                            catch {
+                                /* ignore parse errors */
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (!ctrl.signal.aborted)
+                    opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+            }
+        })();
+        return ctrl;
+    }
+}
+class MessagesResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    send(agent, input) {
+        const body = {
+            agent,
+            to: input.to,
+            cc: input.cc,
+            bcc: input.bcc,
+            subject: input.subject,
+            body_text: input.body_text ?? input.body,
+            body_html: input.body_html,
+            reply_to: input.reply_to,
+            in_reply_to_message_id: input.in_reply_to_message_id,
+            references: input.references,
+            attachments: input.attachments,
+            metadata: input.metadata,
+            pool_hint: input.pool_hint,
+            scheduled_at: input.scheduled_at,
+            tags: input.tags,
+        };
+        const headers = {};
+        if (input.idempotency_key)
+            headers["Idempotency-Key"] = input.idempotency_key;
+        return this.c.request("POST", "/api/v1/messages", body, headers);
+    }
+    batch(messages, opts) {
+        const headers = {};
+        if (opts?.idempotency_key)
+            headers["Idempotency-Key"] = opts.idempotency_key;
+        return this.c.request("POST", "/api/v1/messages/batch", messages, headers);
+    }
+    reply(id, input) {
+        return this.c.request("POST", `/api/v1/messages/${encodeURIComponent(id)}/reply`, { ...input, body_text: input.body_text ?? input.body });
+    }
+    forward(id, input) {
+        return this.c.request("POST", `/api/v1/messages/${encodeURIComponent(id)}/forward`, input);
+    }
+    cancel(id) {
+        return this.c.request("POST", `/api/v1/messages/${encodeURIComponent(id)}/cancel`);
+    }
+    reschedule(id, scheduled_at) {
+        return this.c.request("PATCH", `/api/v1/messages/${encodeURIComponent(id)}`, { scheduled_at });
+    }
+    raw(id) {
+        return this.c.requestText("GET", `/api/v1/messages/${encodeURIComponent(id)}/raw`);
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        if (opts?.agent_id)
+            qs.set("agent_id", opts.agent_id);
+        if (opts?.thread_id)
+            qs.set("thread_id", opts.thread_id);
+        return this.c.request("GET", `/api/v1/messages${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    get(id) {
+        return this.c.request("GET", `/api/v1/messages/${encodeURIComponent(id)}`);
+    }
+}
+class ReceivedResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        if (opts?.agent_id)
+            qs.set("agent_id", opts.agent_id);
+        if (opts?.thread_id)
+            qs.set("thread_id", opts.thread_id);
+        return this.c.request("GET", `/api/v1/messages/received${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    get(id) {
+        return this.c.request("GET", `/api/v1/messages/received/${encodeURIComponent(id)}`);
+    }
+}
+class ThreadsResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        if (opts?.agent_id)
+            qs.set("agent_id", opts.agent_id);
+        if (opts?.status)
+            qs.set("status", opts.status);
+        return this.c.request("GET", `/api/v1/threads${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    get(id) {
+        return this.c.request("GET", `/api/v1/threads/${encodeURIComponent(id)}`);
+    }
+    update(id, patch) {
+        return this.c.request("PATCH", `/api/v1/threads/${encodeURIComponent(id)}`, patch);
+    }
+}
+class DraftsResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    create(input) {
+        return this.c.request("POST", "/api/v1/drafts", input);
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        if (opts?.status)
+            qs.set("status", opts.status);
+        return this.c.request("GET", `/api/v1/drafts${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    get(id) {
+        return this.c.request("GET", `/api/v1/drafts/${encodeURIComponent(id)}`);
+    }
+    update(id, patch) {
+        return this.c.request("PATCH", `/api/v1/drafts/${encodeURIComponent(id)}`, patch);
+    }
+    remove(id) {
+        return this.c.request("DELETE", `/api/v1/drafts/${encodeURIComponent(id)}`);
+    }
+    send(id, opts) {
+        return this.c.request("POST", `/api/v1/drafts/${encodeURIComponent(id)}/send`, opts ?? {});
+    }
+}
+class EventsResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        if (opts?.event_type)
+            qs.set("event_type", opts.event_type);
+        if (opts?.agent_id)
+            qs.set("agent_id", opts.agent_id);
+        if (opts?.since)
+            qs.set("since", opts.since);
+        return this.c.request("GET", `/api/v1/events${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    get(id) {
+        return this.c.request("GET", `/api/v1/events/${encodeURIComponent(id)}`);
+    }
+    redeliver(id) {
+        return this.c.request("POST", `/api/v1/events/${encodeURIComponent(id)}/redeliver`, {});
+    }
+    // Convenience — wraps client.stream
+    stream(opts) {
+        return this.c.stream(opts);
+    }
+}
+class AgentsResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    create(name, opts) {
+        return this.c.request("POST", "/api/v1/agents", { name, ...opts });
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        return this.c.request("GET", `/api/v1/agents${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    get(id) {
+        return this.c.request("GET", `/api/v1/agents/${encodeURIComponent(id)}`);
+    }
+    update(id, patch) {
+        return this.c.request("PATCH", `/api/v1/agents/${encodeURIComponent(id)}`, patch);
+    }
+    archive(id) {
+        return this.c.request("DELETE", `/api/v1/agents/${encodeURIComponent(id)}`);
+    }
+}
+class SuppressionResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    check(address) {
+        return this.c.request("GET", `/api/v1/suppression?address=${encodeURIComponent(address)}`);
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        return this.c.request("GET", `/api/v1/suppression${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    allow(address, attestation) {
+        return this.c.request("POST", "/api/v1/suppression/allow", { address, attestation });
+    }
+    revoke(id) {
+        return this.c.request("DELETE", `/api/v1/suppression/allow/${encodeURIComponent(id)}`);
+    }
+}
+class ApiKeysResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    create(input) {
+        return this.c.request("POST", "/api/v1/api-keys", input);
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        return this.c.request("GET", `/api/v1/api-keys${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    revoke(id) {
+        return this.c.request("DELETE", `/api/v1/api-keys/${encodeURIComponent(id)}`);
+    }
+}
+class WebhooksResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    create(input) {
+        return this.c.request("POST", "/api/v1/webhooks", input);
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        return this.c.request("GET", `/api/v1/webhooks${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    update(id, patch) {
+        return this.c.request("PATCH", `/api/v1/webhooks/${encodeURIComponent(id)}`, patch);
+    }
+    /** Send a signed test event to the endpoint to verify reachability + signature handling. */
+    test(id) {
+        return this.c.request("POST", `/api/v1/webhooks/${encodeURIComponent(id)}/test`);
+    }
+    remove(id) {
+        return this.c.request("DELETE", `/api/v1/webhooks/${encodeURIComponent(id)}`);
+    }
+    deliveries(webhookId, opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        return this.c.request("GET", `/api/v1/webhooks/${encodeURIComponent(webhookId)}/deliveries${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+    replayDelivery(deliveryId) {
+        return this.c.request("POST", `/api/v1/webhook-deliveries/${encodeURIComponent(deliveryId)}/replay`, {});
+    }
+    verify(body, signature, secret, toleranceSec = 300) {
+        try {
+            const parts = Object.fromEntries(signature.split(",").map((p) => p.split("=")));
+            const ts = parseInt(parts.t ?? "0", 10);
+            if (!Number.isFinite(ts))
+                return null;
+            if (Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSec)
+                return null;
+            const expected = crypto.createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
+            const ok = crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1 ?? "", "hex"));
+            if (!ok)
+                return null;
+            return JSON.parse(body);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+class ReputationResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    get(agentId) {
+        const qs = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : "";
+        return this.c.request("GET", `/api/v1/reputation${qs}`);
+    }
+}
+class BillingResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    portal(returnUrl) {
+        return this.c.request("POST", "/api/v1/billing/portal", { return_url: returnUrl });
+    }
+    usage() {
+        return this.c.request("GET", "/api/v1/billing/usage");
+    }
+}
+class LogsResource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    list(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit)
+            qs.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            qs.set("cursor", opts.cursor);
+        if (opts?.category)
+            qs.set("category", opts.category);
+        if (opts?.action)
+            qs.set("action", opts.action);
+        return this.c.request("GET", `/api/v1/logs${qs.toString() ? "?" + qs.toString() : ""}`);
+    }
+}
+class Agent {
+    client;
+    name;
+    _id;
+    constructor(client, name) {
+        this.client = client;
+        this.name = name;
+    }
+    async send(input) {
+        return this.client.send(this.name, input);
+    }
+    async listReplies(opts) {
+        return this.client.events.list({ event_type: "reply.received", agent_id: this.name, ...opts });
+    }
+    /**
+     * List cold/first-contact inbound (`message.received`) for this agent — messages
+     * from senders that are NOT replies to one of your sends (new leads, support
+     * requests, strangers). Authenticated only; SPF+DKIM failures surface separately
+     * as `message.received.unauthenticated`. Mirrors {@link listReplies}.
+     */
+    async listMessages(opts) {
+        return this.client.events.list({ event_type: "message.received", agent_id: this.name, ...opts });
+    }
+    async reputation() {
+        return this.client.reputation.get(this.name);
+    }
+    /**
+     * Subscribe to reply.received events for this agent. Opens an SSE stream
+     * filtered server-side to reply.received and dispatches to `callback` for
+     * events matching this agent. Resolves the agent name → id once on first
+     * matching event so subsequent events skip the lookup.
+     *
+     * @returns AbortController — call `.abort()` to stop listening. Caller can
+     *   also pass `opts.signal` to chain into an existing abort flow.
+     *
+     * @example
+     *   const ctrl = agent.onReply((event) => {
+     *     console.log(event.intent, event.entities);
+     *   });
+     *   // …later
+     *   ctrl.abort();
+     */
+    onReply(callback, opts) {
+        return this.subscribe(["reply.received"], callback, opts);
+    }
+    /**
+     * Subscribe to cold/first-contact inbound (`message.received`) for this agent —
+     * new senders that are NOT replying to one of your sends. Same shape and
+     * agent-scoping as {@link onReply}; returns an AbortController.
+     *
+     * @example
+     *   const ctrl = agent.onMessage((event) => {
+     *     if (event.intent === "sales_inquiry") routeToCrm(event);
+     *   });
+     */
+    onMessage(callback, opts) {
+        return this.subscribe(["message.received"], callback, opts);
+    }
+    /** Shared agent-scoped SSE subscription used by onReply/onMessage. */
+    subscribe(eventTypes, callback, opts) {
+        return this.client.stream({
+            event_types: eventTypes,
+            since: opts?.since,
+            signal: opts?.signal,
+            onError: opts?.onError,
+            onEvent: async (event) => {
+                try {
+                    if (!this._id)
+                        this._id = await this.resolveId();
+                    if (event.agent_id && event.agent_id !== this._id)
+                        return;
+                    await callback(event);
+                }
+                catch (err) {
+                    opts?.onError?.(err instanceof Error ? err : new Error(String(err)));
+                }
+            },
+        });
+    }
+    async resolveId() {
+        // Look up the agent's UUID by friendly name. Cached on the instance so
+        // subsequent matches in the stream skip the round-trip.
+        const list = await this.client.agents.list({ limit: 100 });
+        const found = list.data.find((a) => a.name === this.name);
+        if (!found) {
+            throw new Error(`Agent "${this.name}" not found in this workspace. Create it with mails.agents.create("${this.name}") or verify the name.`);
+        }
+        return found.id;
+    }
+}
+export function createClient(opts = {}) {
+    return new MailsClient(opts);
+}
+// Default singleton — uses env vars. Safe to import even without keys; throws on first use.
+export const mails = {
+    agent(name, opts) {
+        return new MailsClient(opts ?? {}).agent(name);
+    },
+    send(agent, input, opts) {
+        return new MailsClient(opts ?? {}).send(agent, input);
+    },
+    webhooks: {
+        verify(body, signature, secret, toleranceSec = 300) {
+            try {
+                const parts = Object.fromEntries(signature.split(",").map((p) => p.split("=")));
+                const ts = parseInt(parts.t ?? "0", 10);
+                if (!Number.isFinite(ts))
+                    return null;
+                if (Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSec)
+                    return null;
+                const expected = crypto.createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
+                const ok = crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1 ?? "", "hex"));
+                if (!ok)
+                    return null;
+                return JSON.parse(body);
+            }
+            catch {
+                return null;
+            }
+        },
+    },
+};
+export { MailsClient, Agent, MailsError };