@mailtarn/node 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Limenzy Technologies Pvt Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @mailtarn/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mailtarn for Node.js (18+). No dependencies.
+
+- **Read captured email in tests:** wait for a message, then use its links and one-time codes.
+- **Send into a Mailtarn inbox over HTTP** instead of SMTP. Mailtarn never delivers anything:
+  messages land in your inbox and stay there.
+
+```bash
+npm install @mailtarn/node
+```
+
+Create an API token in Mailtarn (Developer → API tokens) with the permissions you need and keep
+it in a secret, e.g. `MAILTARN_TOKEN`.
+
+## Wait for an email in a test
+
+```ts
+import { Mailtarn } from '@mailtarn/node';
+
+const mt = new Mailtarn({ token: process.env.MAILTARN_TOKEN! });
+const inboxId = process.env.MAILTARN_INBOX!;
+
+const since = new Date();
+await signUp('priya@example.com'); // your app sends the verification email
+
+const email = await mt.waitFor(inboxId, { to: 'priya@example.com', since });
+expect(email.subject).toBe('Verify your email');
+await page.goto(email.links[0]!.url); // or: await page.fill('#code', email.codes[0]!)
+```
+
+`waitFor` returns the first matching message received after `since` (without `since`, the newest
+match, or the next to arrive). It waits up to `timeoutMs` (default 30 000) and throws a
+`MailtarnError` with code `wait_timeout` if nothing arrives. Filters: `to`, `from`, `subject`,
+`q` (anywhere), `hasAttachments`. Needs `messages:read`.
+
+Each message has `text`, `html` (as sent; untrusted, render it only in a sandbox), `headers`,
+`attachments`, `envelope` (every recipient, including BCC), `links` and `codes`.
+
+## Send into an inbox
+
+```ts
+await mt.send({
+  inbox: inboxId, // not needed with a token for one inbox
+  from: { name: 'Acme', address: 'hello@acme.test' },
+  to: 'priya@example.com',
+  subject: 'Welcome',
+  html: '<p>Hello</p>',
+  attachments: [{ filename: 'invoice.pdf', content: pdfBytes, contentType: 'application/pdf' }],
+});
+```
+
+Addresses take `a@b.test`, `Name <a@b.test>`, `"Last, First" <a@b.test>` or `{ name, address }`.
+Needs `messages:send`. Returns once the message is stored (`202`); it is processed a moment later.
+
+## Everything else
+
+```ts
+await mt.inboxes.list();
+await mt.messages.list(inboxId, { subject: 'Welcome', limit: 20 });
+await mt.messages.get(id);
+await mt.messages.raw(id);            // the .eml bytes
+await mt.messages.attachment(id, 0);
+await mt.messages.delete(id);         // messages:delete
+await mt.inboxes.clear(inboxId);      // messages:delete
+await mt.usage();
+```
+
+Errors are `MailtarnError` with `status` and a stable `code` (`unauthorized`,
+`insufficient_scope`, `not_found`, `rate_limited`, `wait_timeout`, …).
+
+Another Mailtarn server (for example a local one while developing): `new Mailtarn({ token, baseUrl: 'http://localhost:3001' })`.
+
+## Licence
+
+MIT. Copyright (c) 2026 Limenzy Technologies Pvt Ltd.

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Mailtarn for Node.js.
+ *
+ *   import { Mailtarn } from '@mailtarn/node';
+ *   const mt = new Mailtarn({ token: process.env.MAILTARN_TOKEN! });
+ *
+ *   const since = new Date();
+ *   await signUp('priya@example.com');                       // your app sends the email
+ *   const email = await mt.waitFor(inboxId, { to: 'priya@example.com', since });
+ *   expect(email.subject).toBe('Verify your email');
+ *   await page.goto(email.links[0]!.url);                   // or type email.codes[0]
+ *
+ * Mailtarn captures email and never delivers it. `send` puts a message into a Mailtarn inbox
+ * over HTTP (instead of SMTP); it does not send to the real recipients.
+ */
+export interface Address {
+    name: string;
+    address: string;
+}
+export interface Attachment {
+    index: number;
+    filename: string | null;
+    contentType: string;
+    size: number;
+    contentId: string | null;
+    inline: boolean;
+}
+export interface Message {
+    id: string;
+    inboxId: string;
+    status: 'received' | 'parsed' | 'failed';
+    receivedAt: string;
+    subject: string | null;
+    from: string | null;
+    to: Address[];
+    cc: Address[];
+    messageId: string | null;
+    envelope: {
+        from: string | null;
+        to: string[];
+    };
+    text: string | null;
+    /** The HTML exactly as sent. Untrusted: never render it outside a sandbox. */
+    html: string | null;
+    headers: Array<{
+        name: string;
+        value: string;
+    }>;
+    attachments: Attachment[];
+    /** http(s) links, from the HTML (with their text) then the plain text. */
+    links: Array<{
+        url: string;
+        text: string | null;
+    }>;
+    /** One-time codes near words like "code" or "OTP", most likely first. */
+    codes: string[];
+    warnings: string[];
+}
+export interface MessageSummary {
+    id: string;
+    inboxId: string;
+    status: Message['status'];
+    receivedAt: string;
+    subject: string | null;
+    from: string | null;
+    to: Address[];
+    snippet: string | null;
+    hasAttachments: boolean;
+}
+export interface Inbox {
+    id: string;
+    name: string;
+    projectId: string;
+    smtpUsername: string;
+    isCi: boolean;
+    createdAt: string;
+}
+export interface Filters {
+    /** Substring of a To/Cc/envelope recipient. */
+    to?: string;
+    from?: string;
+    /** Substring of the subject. */
+    subject?: string;
+    /** Words anywhere (subject, addresses, body). */
+    q?: string;
+    /** Only messages received after this time. */
+    since?: Date | string;
+    hasAttachments?: boolean;
+}
+/** `a@b.test`, `Name <a@b.test>`, `"Last, First" <a@b.test>`, or the object form. */
+export type AddressInput = string | {
+    name?: string;
+    address: string;
+};
+export interface SendInput {
+    /** Inbox id. Not needed with a token for one inbox. */
+    inbox?: string;
+    from: AddressInput;
+    to?: AddressInput | AddressInput[];
+    cc?: AddressInput | AddressInput[];
+    bcc?: AddressInput | AddressInput[];
+    replyTo?: AddressInput;
+    subject?: string;
+    text?: string;
+    html?: string;
+    /** Custom headers such as X-Env (addressing and MIME headers come from the fields). */
+    headers?: Record<string, string>;
+    attachments?: Array<{
+        filename?: string;
+        content: string | Uint8Array;
+        contentType?: string;
+        contentId?: string;
+        inline?: boolean;
+    }>;
+}
+export interface MailtarnOptions {
+    /** An API token (mtk_…). */
+    token: string;
+    /** Default https://app.mailtarn.com */
+    baseUrl?: string;
+    /** For tests and unusual runtimes. Default: the global fetch. */
+    fetch?: typeof fetch;
+}
+/** An error response from the API, with its stable code (e.g. "insufficient_scope", "wait_timeout"). */
+export declare class MailtarnError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare class Mailtarn {
+    private readonly base;
+    private readonly token;
+    private readonly doFetch;
+    constructor(opts: MailtarnOptions);
+    /** Puts a message into a Mailtarn inbox (stored, never delivered). Needs messages:send. */
+    send(input: SendInput): Promise<{
+        id: string;
+        inboxId: string;
+        status: 'received';
+    }>;
+    /**
+     * Waits for a message matching the filters and returns it in full. With `since`, the first
+     * match received after it; without, the newest match (or the next to arrive). `timeoutMs`
+     * (default 30 s) may exceed the server's 60 s per request: it keeps asking until then.
+     * Throws MailtarnError with code "wait_timeout" if nothing arrives.
+     */
+    waitFor(inboxId: string, filters?: Filters & {
+        timeoutMs?: number;
+    }): Promise<Message>;
+    readonly inboxes: {
+        list: () => Promise<Inbox[]>;
+        /** Needs inboxes:manage. The password is returned once. */
+        create: (input: {
+            name: string;
+            projectId?: string;
+            isCi?: boolean;
+        }) => Promise<{
+            inbox: {
+                id: string;
+                name: string;
+                projectId: string;
+                smtpUsername: string;
+            };
+            credential: {
+                username: string;
+                password: string;
+            };
+        }>;
+        /** Deletes every message in the inbox. Needs messages:delete. */
+        clear: (inboxId: string) => Promise<{
+            deleted: number;
+        }>;
+    };
+    readonly messages: {
+        list: (inboxId: string, filters?: Filters & {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<{
+            messages: MessageSummary[];
+            nextCursor: string | null;
+        }>;
+        get: (id: string) => Promise<Message>;
+        /** The message as received (.eml bytes). */
+        raw: (id: string) => Promise<Uint8Array>;
+        attachment: (id: string, index: number) => Promise<Uint8Array>;
+        delete: (id: string) => Promise<void>;
+    };
+    /** This month's usage for what the token can see: its organization, project or inbox (`scope`). */
+    usage(): Promise<{
+        scope: "org" | "project" | "inbox";
+        periodStart: string;
+        messages: number;
+        bytesIn: number;
+        storageBytes: number;
+    }>;
+    private request;
+    private json;
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+/**
+ * Mailtarn for Node.js.
+ *
+ *   import { Mailtarn } from '@mailtarn/node';
+ *   const mt = new Mailtarn({ token: process.env.MAILTARN_TOKEN! });
+ *
+ *   const since = new Date();
+ *   await signUp('priya@example.com');                       // your app sends the email
+ *   const email = await mt.waitFor(inboxId, { to: 'priya@example.com', since });
+ *   expect(email.subject).toBe('Verify your email');
+ *   await page.goto(email.links[0]!.url);                   // or type email.codes[0]
+ *
+ * Mailtarn captures email and never delivers it. `send` puts a message into a Mailtarn inbox
+ * over HTTP (instead of SMTP); it does not send to the real recipients.
+ */
+/** An error response from the API, with its stable code (e.g. "insufficient_scope", "wait_timeout"). */
+export class MailtarnError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'MailtarnError';
+    }
+}
+const WAIT_MAX_S = 60;
+export class Mailtarn {
+    base;
+    token;
+    doFetch;
+    constructor(opts) {
+        if (!opts?.token)
+            throw new Error('Mailtarn: pass { token } (an API token starting with mtk_).');
+        this.token = opts.token;
+        this.base = (opts.baseUrl ?? 'https://app.mailtarn.com').replace(/\/+$/, '');
+        this.doFetch = opts.fetch ?? fetch;
+    }
+    /** Puts a message into a Mailtarn inbox (stored, never delivered). Needs messages:send. */
+    async send(input) {
+        const body = {
+            ...input,
+            attachments: input.attachments?.map((a) => ({
+                ...a,
+                content: typeof a.content === 'string' ? a.content : base64(a.content),
+            })),
+        };
+        return this.json('POST', '/v1/send', body);
+    }
+    /**
+     * Waits for a message matching the filters and returns it in full. With `since`, the first
+     * match received after it; without, the newest match (or the next to arrive). `timeoutMs`
+     * (default 30 s) may exceed the server's 60 s per request: it keeps asking until then.
+     * Throws MailtarnError with code "wait_timeout" if nothing arrives.
+     */
+    async waitFor(inboxId, filters = {}) {
+        const deadline = Date.now() + (filters.timeoutMs ?? 30_000);
+        for (;;) {
+            const left = Math.max(0, Math.ceil((deadline - Date.now()) / 1000));
+            try {
+                const r = await this.json('GET', `/v1/inboxes/${enc(inboxId)}/messages/wait${qs({ ...filters, timeout: Math.min(left, WAIT_MAX_S) })}`);
+                return r.message;
+            }
+            catch (e) {
+                if (e instanceof MailtarnError && e.code === 'wait_timeout' && Date.now() < deadline)
+                    continue;
+                throw e;
+            }
+        }
+    }
+    inboxes = {
+        list: async () => (await this.json('GET', '/v1/inboxes')).inboxes,
+        /** Needs inboxes:manage. The password is returned once. */
+        create: async (input) => this.json('POST', '/v1/inboxes', input),
+        /** Deletes every message in the inbox. Needs messages:delete. */
+        clear: async (inboxId) => this.json('DELETE', `/v1/inboxes/${enc(inboxId)}/messages`),
+    };
+    messages = {
+        list: async (inboxId, filters = {}) => this.json('GET', `/v1/inboxes/${enc(inboxId)}/messages${qs(filters)}`),
+        get: async (id) => (await this.json('GET', `/v1/messages/${enc(id)}`)).message,
+        /** The message as received (.eml bytes). */
+        raw: async (id) => new Uint8Array(await (await this.request('GET', `/v1/messages/${enc(id)}/raw`)).arrayBuffer()),
+        attachment: async (id, index) => new Uint8Array(await (await this.request('GET', `/v1/messages/${enc(id)}/attachments/${index}`)).arrayBuffer()),
+        delete: async (id) => { await this.request('DELETE', `/v1/messages/${enc(id)}`); },
+    };
+    /** This month's usage for what the token can see: its organization, project or inbox (`scope`). */
+    async usage() {
+        return this.json('GET', '/v1/usage');
+    }
+    async request(method, path, body) {
+        const res = await this.doFetch(`${this.base}${path}`, {
+            method,
+            headers: { authorization: `Bearer ${this.token}`, ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const e = (await res.json().catch(() => null));
+            throw new MailtarnError(res.status, e?.error?.code ?? `http_${res.status}`, e?.error?.message ?? res.statusText);
+        }
+        return res;
+    }
+    async json(method, path, body) {
+        const res = await this.request(method, path, body);
+        return (res.status === 204 ? undefined : await res.json());
+    }
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}
+function qs(f) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(f)) {
+        if (v === undefined || v === null || k === 'timeoutMs')
+            continue;
+        p.set(k, v instanceof Date ? v.toISOString() : String(v));
+    }
+    const s = p.toString();
+    return s ? `?${s}` : '';
+}
+function base64(b) {
+    let s = '';
+    for (let i = 0; i < b.length; i += 0x8000)
+        s += String.fromCharCode(...b.subarray(i, i + 0x8000));
+    return btoa(s);
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@mailtarn/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Mailtarn for Node.js: send into a Mailtarn inbox and read captured email in tests (wait for a message, get its links and codes).",
+  "license": "MIT",
+  "author": "Limenzy Technologies Pvt Ltd",
+  "homepage": "https://mailtarn.com",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "email",
+    "testing",
+    "smtp",
+    "sandbox",
+    "e2e",
+    "otp",
+    "mailtarn"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
 }