@molecule/api-emails-inbound-agentmail 1.0.0

package/dist/api.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Minimal AgentMail REST client — only the three calls the inbound bond
+ * needs: fetch a message (to hydrate bodies the 1 MB webhook cap omitted),
+ * download an attachment (metadata → presigned URL → bytes), and reply.
+ * Built on the global `fetch`; no SDK.
+ *
+ * @see https://docs.agentmail.to/api-reference
+ * @see https://docs.agentmail.to/errors
+ * @see https://docs.agentmail.to/knowledge-base/rate-limits
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+import './secrets.js';
+import type { AgentMailAttachmentDownload, AgentMailMessage, AgentMailReplyRequest, AgentMailReplyResponse } from './types.js';
+/**
+ * Timeout (ms) for a JSON API call. Bounds a hanging AgentMail endpoint so
+ * the webhook handler fails (and AgentMail retries) instead of stalling.
+ */
+export declare const API_REQUEST_TIMEOUT_MS = 15000;
+/**
+ * Timeout (ms) for downloading one attachment's bytes from its presigned
+ * URL. Larger than {@link API_REQUEST_TIMEOUT_MS} because it moves the
+ * attachment payload, not a small JSON document.
+ */
+export declare const ATTACHMENT_DOWNLOAD_TIMEOUT_MS = 60000;
+/**
+ * A non-2xx response from the AgentMail API, carrying the documented error
+ * envelope's `code` / `name` / `fix` and — for `429` — the `Retry-After`
+ * delay. The message never includes the API key.
+ */
+export declare class AgentMailApiError extends Error {
+    /** HTTP status AgentMail returned. */
+    readonly statusCode: number;
+    /** Machine-readable error code (`unknown_api_key`, `rate_limit_exceeded`, …). */
+    readonly code: string | undefined;
+    /** Legacy error type name from the envelope (`NotFoundError`, …). */
+    readonly errorName: string | undefined;
+    /** Remediation steps from the envelope, when AgentMail supplied any. */
+    readonly fix: string | undefined;
+    /** Seconds to wait before retrying, from `Retry-After` (rate limits). */
+    readonly retryAfterSeconds: number | undefined;
+    /**
+     * Builds the error from the HTTP status and the parsed envelope.
+     *
+     * @param message - Human-readable description.
+     * @param details - Status and envelope fields.
+     */
+    constructor(message: string, details: {
+        statusCode: number;
+        code?: string;
+        errorName?: string;
+        fix?: string;
+        retryAfterSeconds?: number;
+    });
+}
+/**
+ * Reads the AgentMail API key from the environment, throwing the tagged
+ * `config.notConfigured` error (never revealing any value) when unset.
+ *
+ * @returns The API key.
+ */
+export declare const getApiKey: () => string;
+/**
+ * Resolves the API base URL: `AGENTMAIL_BASE_URL` when set (trailing
+ * slashes stripped), else {@link DEFAULT_BASE_URL}.
+ *
+ * @returns The base URL without a trailing slash.
+ */
+export declare const getBaseUrl: () => string;
+/**
+ * Path of a message resource. Both ids are URL-encoded — AgentMail's
+ * `message_id` is the RFC 5322 Message-ID INCLUDING angle brackets and `@`.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @returns `/v0/inboxes/{inbox_id}/messages/{message_id}`.
+ */
+export declare const messagePath: (inboxId: string, messageId: string) => string;
+/**
+ * Performs one authenticated JSON call against the AgentMail API.
+ *
+ * @param method - HTTP method.
+ * @param path - Path under the base URL (must start with `/`).
+ * @param body - Optional JSON request body.
+ * @returns The parsed JSON response.
+ * @throws {AgentMailApiError} On any non-2xx response.
+ * @throws {Error} The tagged `config.notConfigured` error when
+ *   `AGENTMAIL_API_KEY` is unset.
+ */
+export declare const agentMailRequest: <T>(method: "GET" | "POST", path: string, body?: unknown) => Promise<T>;
+/**
+ * Fetches a full message — used to hydrate `text` / `html` when the webhook
+ * payload omitted them (AgentMail drops both once the payload would exceed
+ * 1 MB).
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @returns The message.
+ * @see https://docs.agentmail.to/api-reference/inboxes/messages/get
+ */
+export declare const getMessage: (inboxId: string, messageId: string) => Promise<AgentMailMessage>;
+/**
+ * Fetches an attachment's metadata + presigned `download_url`.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @param attachmentId - The attachment id from the message's metadata.
+ * @returns The attachment metadata and download URL.
+ * @see https://docs.agentmail.to/api-reference/inboxes/messages/get-attachment
+ */
+export declare const getAttachmentDownload: (inboxId: string, messageId: string, attachmentId: string) => Promise<AgentMailAttachmentDownload>;
+/**
+ * Downloads an attachment's bytes: resolves the presigned `download_url`
+ * via {@link getAttachmentDownload}, then GETs it. The presigned request
+ * deliberately carries NO `Authorization` header — the URL is self-
+ * authenticating, and object stores reject a request that presents two
+ * auth mechanisms at once.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @param attachmentId - The attachment id from the message's metadata.
+ * @returns The metadata and the raw bytes.
+ * @throws {AgentMailApiError} When either request fails.
+ */
+export declare const downloadAttachment: (inboxId: string, messageId: string, attachmentId: string) => Promise<{
+    meta: AgentMailAttachmentDownload;
+    content: Buffer;
+}>;
+/**
+ * Sends a reply to a message from the inbox that received it. AgentMail
+ * threads the reply (`In-Reply-To` / `References` / subject) itself.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @param body - The reply.
+ * @returns The created message's ids.
+ * @see https://docs.agentmail.to/api-reference/inboxes/messages/reply
+ */
+export declare const replyToMessage: (inboxId: string, messageId: string, body: AgentMailReplyRequest) => Promise<AgentMailReplyResponse>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAKpC,OAAO,cAAc,CAAA;AAIrB,OAAO,KAAK,EACV,2BAA2B,EAE3B,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAGnB;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAA;AAEpD;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAE9C;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAA;QAClB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAC3B;CAUJ;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAAO,MAQ5B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,QAAO,MAI7B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,MAEhE,CAAA;AAuDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAU,CAAC,EACtC,QAAQ,KAAK,GAAG,MAAM,EACtB,MAAM,MAAM,EACZ,OAAO,OAAO,KACb,OAAO,CAAC,CAAC,CAmBX,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAU,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAE7F,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,cAAc,MAAM,KACnB,OAAO,CAAC,2BAA2B,CAKrC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,cAAc,MAAM,KACnB,OAAO,CAAC;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAsBhE,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,MAAM,qBAAqB,KAC1B,OAAO,CAAC,sBAAsB,CAMhC,CAAA"}

package/dist/api.js

@@ -0,0 +1,244 @@
+/**
+ * Minimal AgentMail REST client — only the three calls the inbound bond
+ * needs: fetch a message (to hydrate bodies the 1 MB webhook cap omitted),
+ * download an attachment (metadata → presigned URL → bytes), and reply.
+ * Built on the global `fetch`; no SDK.
+ *
+ * @see https://docs.agentmail.to/api-reference
+ * @see https://docs.agentmail.to/errors
+ * @see https://docs.agentmail.to/knowledge-base/rate-limits
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+// Side-effect import: registers this bond's secret definitions so the
+// runtime registry is populated even when api.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+import { configNotConfiguredError } from '@molecule/api-secrets';
+import { DEFAULT_BASE_URL, isRecord, parseRetryAfterSeconds } from './utilities.js';
+/**
+ * Timeout (ms) for a JSON API call. Bounds a hanging AgentMail endpoint so
+ * the webhook handler fails (and AgentMail retries) instead of stalling.
+ */
+export const API_REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Timeout (ms) for downloading one attachment's bytes from its presigned
+ * URL. Larger than {@link API_REQUEST_TIMEOUT_MS} because it moves the
+ * attachment payload, not a small JSON document.
+ */
+export const ATTACHMENT_DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * A non-2xx response from the AgentMail API, carrying the documented error
+ * envelope's `code` / `name` / `fix` and — for `429` — the `Retry-After`
+ * delay. The message never includes the API key.
+ */
+export class AgentMailApiError extends Error {
+    /** HTTP status AgentMail returned. */
+    statusCode;
+    /** Machine-readable error code (`unknown_api_key`, `rate_limit_exceeded`, …). */
+    code;
+    /** Legacy error type name from the envelope (`NotFoundError`, …). */
+    errorName;
+    /** Remediation steps from the envelope, when AgentMail supplied any. */
+    fix;
+    /** Seconds to wait before retrying, from `Retry-After` (rate limits). */
+    retryAfterSeconds;
+    /**
+     * Builds the error from the HTTP status and the parsed envelope.
+     *
+     * @param message - Human-readable description.
+     * @param details - Status and envelope fields.
+     */
+    constructor(message, details) {
+        super(message);
+        this.name = 'AgentMailApiError';
+        this.statusCode = details.statusCode;
+        this.code = details.code;
+        this.errorName = details.errorName;
+        this.fix = details.fix;
+        this.retryAfterSeconds = details.retryAfterSeconds;
+    }
+}
+/**
+ * Reads the AgentMail API key from the environment, throwing the tagged
+ * `config.notConfigured` error (never revealing any value) when unset.
+ *
+ * @returns The API key.
+ */
+export const getApiKey = () => {
+    const apiKey = process.env.AGENTMAIL_API_KEY;
+    if (!apiKey) {
+        // Tagged config-missing error → clean 503 + 'config.notConfigured', with the
+        // registered definition's description + setup URL (see classifyTaggedError).
+        throw configNotConfiguredError('AGENTMAIL_API_KEY', 'inbound email');
+    }
+    return apiKey;
+};
+/**
+ * Resolves the API base URL: `AGENTMAIL_BASE_URL` when set (trailing
+ * slashes stripped), else {@link DEFAULT_BASE_URL}.
+ *
+ * @returns The base URL without a trailing slash.
+ */
+export const getBaseUrl = () => {
+    const raw = process.env.AGENTMAIL_BASE_URL?.trim();
+    const base = raw && raw.length > 0 ? raw : DEFAULT_BASE_URL;
+    return base.replace(/\/+$/u, '');
+};
+/**
+ * Path of a message resource. Both ids are URL-encoded — AgentMail's
+ * `message_id` is the RFC 5322 Message-ID INCLUDING angle brackets and `@`.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @returns `/v0/inboxes/{inbox_id}/messages/{message_id}`.
+ */
+export const messagePath = (inboxId, messageId) => {
+    return `/v0/inboxes/${encodeURIComponent(inboxId)}/messages/${encodeURIComponent(messageId)}`;
+};
+/**
+ * Converts a non-2xx response into an {@link AgentMailApiError}, reading
+ * the documented error envelope when the body carries one and falling back
+ * to a snippet of the raw body (e.g. the plain-text `413`).
+ *
+ * @param response - The failed response.
+ * @param method - HTTP method, for the message.
+ * @param path - Request path, for the message.
+ * @returns The mapped error.
+ */
+const toApiError = async (response, method, path) => {
+    let text = '';
+    try {
+        text = await response.text();
+    }
+    catch (_error) {
+        // An unreadable error body is still an error response — report the
+        // status without a detail rather than masking the failure.
+    }
+    let envelope = {};
+    try {
+        const parsed = JSON.parse(text);
+        if (isRecord(parsed))
+            envelope = parsed;
+    }
+    catch (_error) {
+        // Not JSON (AgentMail's 413 is a bare message) — fall through to the
+        // raw-text snippet below.
+    }
+    const code = typeof envelope.code === 'string' ? envelope.code : undefined;
+    const errorName = typeof envelope.name === 'string' ? envelope.name : undefined;
+    const fix = typeof envelope.fix === 'string' ? envelope.fix : undefined;
+    const detail = typeof envelope.message === 'string' && envelope.message.length > 0
+        ? envelope.message
+        : text.trim().slice(0, 200) || response.statusText || 'no response body';
+    const message = `AgentMail ${method} ${path} failed with HTTP ${String(response.status)}` +
+        `${code ? ` (${code})` : ''}: ${detail}${fix ? ` ${fix}` : ''}`;
+    return new AgentMailApiError(message, {
+        statusCode: response.status,
+        code,
+        errorName,
+        fix,
+        retryAfterSeconds: parseRetryAfterSeconds(response.headers.get('retry-after')),
+    });
+};
+/**
+ * Performs one authenticated JSON call against the AgentMail API.
+ *
+ * @param method - HTTP method.
+ * @param path - Path under the base URL (must start with `/`).
+ * @param body - Optional JSON request body.
+ * @returns The parsed JSON response.
+ * @throws {AgentMailApiError} On any non-2xx response.
+ * @throws {Error} The tagged `config.notConfigured` error when
+ *   `AGENTMAIL_API_KEY` is unset.
+ */
+export const agentMailRequest = async (method, path, body) => {
+    const apiKey = getApiKey();
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json',
+    };
+    const init = {
+        method,
+        headers,
+        signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS),
+    };
+    if (body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        init.body = JSON.stringify(body);
+    }
+    const response = await fetch(`${getBaseUrl()}${path}`, init);
+    if (!response.ok)
+        throw await toApiError(response, method, path);
+    return (await response.json());
+};
+/**
+ * Fetches a full message — used to hydrate `text` / `html` when the webhook
+ * payload omitted them (AgentMail drops both once the payload would exceed
+ * 1 MB).
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @returns The message.
+ * @see https://docs.agentmail.to/api-reference/inboxes/messages/get
+ */
+export const getMessage = async (inboxId, messageId) => {
+    return agentMailRequest('GET', messagePath(inboxId, messageId));
+};
+/**
+ * Fetches an attachment's metadata + presigned `download_url`.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @param attachmentId - The attachment id from the message's metadata.
+ * @returns The attachment metadata and download URL.
+ * @see https://docs.agentmail.to/api-reference/inboxes/messages/get-attachment
+ */
+export const getAttachmentDownload = async (inboxId, messageId, attachmentId) => {
+    return agentMailRequest('GET', `${messagePath(inboxId, messageId)}/attachments/${encodeURIComponent(attachmentId)}`);
+};
+/**
+ * Downloads an attachment's bytes: resolves the presigned `download_url`
+ * via {@link getAttachmentDownload}, then GETs it. The presigned request
+ * deliberately carries NO `Authorization` header — the URL is self-
+ * authenticating, and object stores reject a request that presents two
+ * auth mechanisms at once.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @param attachmentId - The attachment id from the message's metadata.
+ * @returns The metadata and the raw bytes.
+ * @throws {AgentMailApiError} When either request fails.
+ */
+export const downloadAttachment = async (inboxId, messageId, attachmentId) => {
+    const meta = await getAttachmentDownload(inboxId, messageId, attachmentId);
+    if (typeof meta.download_url !== 'string' || meta.download_url.length === 0) {
+        throw new Error(`AgentMail returned no download_url for attachment ${attachmentId} of message ${messageId}.`);
+    }
+    const response = await fetch(meta.download_url, {
+        method: 'GET',
+        signal: AbortSignal.timeout(ATTACHMENT_DOWNLOAD_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new AgentMailApiError(`AgentMail attachment download for ${attachmentId} failed with HTTP ${String(response.status)}.`, {
+            statusCode: response.status,
+            retryAfterSeconds: parseRetryAfterSeconds(response.headers.get('retry-after')),
+        });
+    }
+    return { meta, content: Buffer.from(await response.arrayBuffer()) };
+};
+/**
+ * Sends a reply to a message from the inbox that received it. AgentMail
+ * threads the reply (`In-Reply-To` / `References` / subject) itself.
+ *
+ * @param inboxId - The inbox id.
+ * @param messageId - The message id, exactly as AgentMail supplied it.
+ * @param body - The reply.
+ * @returns The created message's ids.
+ * @see https://docs.agentmail.to/api-reference/inboxes/messages/reply
+ */
+export const replyToMessage = async (inboxId, messageId, body) => {
+    return agentMailRequest('POST', `${messagePath(inboxId, messageId)}/reply`, body);
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-emails-inbound-agentmail` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-emails-inbound-agentmail is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,iHAAiH;QAC/G,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AgentMail inbound-email provider for molecule.dev.
+ *
+ * Implements `@molecule/api-emails-inbound`'s `InboundEmailProvider`
+ * interface against AgentMail's `message.received` webhook. Verifies the
+ * Svix signature headers (`svix-id` / `svix-timestamp` / `svix-signature`,
+ * HMAC-SHA256 over `id.timestamp.body` keyed by the `whsec_` secret) with
+ * replay protection, normalizes the JSON payload, hydrates through the
+ * AgentMail API what the webhook leaves out (attachment bytes; bodies over
+ * the 1 MB cap), and replies through AgentMail's own reply endpoint. Built
+ * on the global `fetch` — no SDK.
+ *
+ * @remarks
+ * - **The webhook route is PUBLIC and needs the RAW body.** Mount it outside
+ *   any auth middleware and hand `verifySignature()` the exact bytes
+ *   received — `express.raw({ type: 'application/json' })` on that route, or
+ *   the body-parser bond's `req.rawBody`. A body that went through
+ *   `express.json()` and was re-stringified will NOT verify.
+ * - **Nothing arrives until BOTH exist at AgentMail: the inbox
+ *   (`POST /v0/inboxes`) and a webhook registered for it
+ *   (`POST /v0/webhooks` with `url` + `event_types: ['message.received']`,
+ *   optionally scoped by `inbox_ids`).** The create-webhook response's
+ *   `secret` IS `AGENTMAIL_WEBHOOK_SECRET`. Subscribe this URL to
+ *   `message.received*` only — any other event type (`message.sent`,
+ *   `message.bounced`, …) makes `parseWebhookPayload()` throw.
+ * - `verifySignature()` THROWS the tagged `config.notConfigured` error
+ *   (→ 503 via the API error middleware) when `AGENTMAIL_WEBHOOK_SECRET` is
+ *   unset, and resolves `false` for a missing/stale/forged signature. Let the
+ *   throw propagate — mapping it to the same 401 as a forged webhook hides a
+ *   misconfigured server behind "invalid signature".
+ * - **`parseWebhookPayload()` may call the AgentMail API.** Attachments
+ *   arrive as metadata only and are downloaded (metadata → presigned
+ *   `download_url` → bytes); when both `text` and `html` are missing (the
+ *   1 MB payload cap) the message is fetched. Both need
+ *   `AGENTMAIL_API_KEY` (tagged config error if unset) and count against
+ *   AgentMail's per-key rate limit. A `429` surfaces as an
+ *   `AgentMailApiError` with `retryAfterSeconds` — let it propagate as a
+ *   5xx so AgentMail redelivers later; never swallow it into a 200, which
+ *   loses the mail. A message with bodies and no attachments makes no
+ *   network call.
+ * - **Replies use AgentMail's reply endpoint, not `@molecule/api-emails`.**
+ *   The reply is sent from the inbox that received the message and AgentMail
+ *   threads it itself, so `reply.subject` and `reply.from` are ignored. The
+ *   inbox is resolved from `AGENTMAIL_INBOX_ID`, else from the in-process
+ *   record `parseWebhookPayload()` kept — set `AGENTMAIL_INBOX_ID` whenever
+ *   a reply is sent from a later request or after a restart. When set it
+ *   also makes `parseWebhookPayload()` reject events for any other inbox.
+ * - `InboundEmail.id` is AgentMail's `message_id` verbatim — the Message-ID
+ *   INCLUDING angle brackets, which is also the path parameter of every
+ *   per-message endpoint; `messageId` is the same value without brackets.
+ *   Dedupe on `id`.
+ * - The sender field is documented under two spellings (`from` in the API
+ *   reference, `from_` in the webhooks guide); both are read.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-emails-inbound'
+ * import { provider as agentMailInbound } from '@molecule/api-emails-inbound-agentmail'
+ *
+ * setProvider(agentMailInbound)
+ * ```
+ *
+ * @module
+ */
+export * from './api.js';
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,71 @@
+/**
+ * AgentMail inbound-email provider for molecule.dev.
+ *
+ * Implements `@molecule/api-emails-inbound`'s `InboundEmailProvider`
+ * interface against AgentMail's `message.received` webhook. Verifies the
+ * Svix signature headers (`svix-id` / `svix-timestamp` / `svix-signature`,
+ * HMAC-SHA256 over `id.timestamp.body` keyed by the `whsec_` secret) with
+ * replay protection, normalizes the JSON payload, hydrates through the
+ * AgentMail API what the webhook leaves out (attachment bytes; bodies over
+ * the 1 MB cap), and replies through AgentMail's own reply endpoint. Built
+ * on the global `fetch` — no SDK.
+ *
+ * @remarks
+ * - **The webhook route is PUBLIC and needs the RAW body.** Mount it outside
+ *   any auth middleware and hand `verifySignature()` the exact bytes
+ *   received — `express.raw({ type: 'application/json' })` on that route, or
+ *   the body-parser bond's `req.rawBody`. A body that went through
+ *   `express.json()` and was re-stringified will NOT verify.
+ * - **Nothing arrives until BOTH exist at AgentMail: the inbox
+ *   (`POST /v0/inboxes`) and a webhook registered for it
+ *   (`POST /v0/webhooks` with `url` + `event_types: ['message.received']`,
+ *   optionally scoped by `inbox_ids`).** The create-webhook response's
+ *   `secret` IS `AGENTMAIL_WEBHOOK_SECRET`. Subscribe this URL to
+ *   `message.received*` only — any other event type (`message.sent`,
+ *   `message.bounced`, …) makes `parseWebhookPayload()` throw.
+ * - `verifySignature()` THROWS the tagged `config.notConfigured` error
+ *   (→ 503 via the API error middleware) when `AGENTMAIL_WEBHOOK_SECRET` is
+ *   unset, and resolves `false` for a missing/stale/forged signature. Let the
+ *   throw propagate — mapping it to the same 401 as a forged webhook hides a
+ *   misconfigured server behind "invalid signature".
+ * - **`parseWebhookPayload()` may call the AgentMail API.** Attachments
+ *   arrive as metadata only and are downloaded (metadata → presigned
+ *   `download_url` → bytes); when both `text` and `html` are missing (the
+ *   1 MB payload cap) the message is fetched. Both need
+ *   `AGENTMAIL_API_KEY` (tagged config error if unset) and count against
+ *   AgentMail's per-key rate limit. A `429` surfaces as an
+ *   `AgentMailApiError` with `retryAfterSeconds` — let it propagate as a
+ *   5xx so AgentMail redelivers later; never swallow it into a 200, which
+ *   loses the mail. A message with bodies and no attachments makes no
+ *   network call.
+ * - **Replies use AgentMail's reply endpoint, not `@molecule/api-emails`.**
+ *   The reply is sent from the inbox that received the message and AgentMail
+ *   threads it itself, so `reply.subject` and `reply.from` are ignored. The
+ *   inbox is resolved from `AGENTMAIL_INBOX_ID`, else from the in-process
+ *   record `parseWebhookPayload()` kept — set `AGENTMAIL_INBOX_ID` whenever
+ *   a reply is sent from a later request or after a restart. When set it
+ *   also makes `parseWebhookPayload()` reject events for any other inbox.
+ * - `InboundEmail.id` is AgentMail's `message_id` verbatim — the Message-ID
+ *   INCLUDING angle brackets, which is also the path parameter of every
+ *   per-message endpoint; `messageId` is the same value without brackets.
+ *   Dedupe on `id`.
+ * - The sender field is documented under two spellings (`from` in the API
+ *   reference, `from_` in the webhooks guide); both are read.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-emails-inbound'
+ * import { provider as agentMailInbound } from '@molecule/api-emails-inbound-agentmail'
+ *
+ * setProvider(agentMailInbound)
+ * ```
+ *
+ * @module
+ */
+export * from './api.js';
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}