mailtruss 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -28,6 +28,11 @@ export type SendEmailParams = {
         id: string;
         variables?: Record<string, unknown>;
     };
+    /** `false` (or `{ clicks: false, opens: false }`) switches click and open tracking off for this message. It cannot switch on what the domain has off. */
+    tracking?: boolean | {
+        clicks?: boolean;
+        opens?: boolean;
+    };
 };
 export type Email = {
     object: "email";
@@ -77,6 +82,30 @@ export type ClientOptions = {
     maxRetries?: number;
     fetch?: typeof fetch;
 };
+export type EmailEvents = {
+    object: "email_events";
+    email_id: string;
+    status: string;
+    diagnosis: {
+        title: string;
+        explanation: string;
+        retry_safe: boolean;
+        next_step: string;
+    } | null;
+    recipients: {
+        address: string;
+        kind: "to" | "cc" | "bcc";
+        status: string;
+    }[];
+    data: {
+        type: string;
+        occurred_at: string;
+        source: string;
+        recipient: string | null;
+        meaning: string | null;
+        detail: Record<string, unknown>;
+    }[];
+};
 export type RequestOptions = {
     idempotencyKey?: string;
     signal?: AbortSignal;
@@ -117,6 +146,8 @@ export declare class MailClient {
         cancel: (id: string, o?: RequestOptions) => Promise<{
             id: string;
         }>;
+        /** The delivery timeline with what each event proves, and a plain-language diagnosis when something went wrong. */
+        events: (id: string, o?: RequestOptions) => Promise<EmailEvents>;
     };
     readonly domains: {
         create: (p: {
@@ -160,10 +191,12 @@ export declare class MailClient {
         setTracking: (id: string, p: {
             click_tracking?: boolean;
             open_tracking?: boolean;
+            tracking_scope?: "all" | "broadcasts";
         }, o?: RequestOptions) => Promise<{
             id: string;
             click_tracking: boolean;
             open_tracking: boolean;
+            tracking_scope: "all" | "broadcasts";
         }>;
         remove: (id: string, o?: RequestOptions) => Promise<{
             id: string;
@@ -425,3 +458,11 @@ export declare class MailClient {
         }>>;
     };
 }
+/**
+ * Verifies a Mailtruss webhook (Standard Webhooks format). Pass the raw request body exactly as received, the request headers,
+ * and the endpoint's signing secret. Returns the parsed event, or throws if the signature or timestamp is wrong.
+ * Works in Node 18+, edge runtimes and Workers (Web Crypto). Standard libraries (`standardwebhooks`, `svix`) also work.
+ *
+ *   const event = await verifyWebhook(await req.text(), req.headers, process.env.MAILTRUSS_WEBHOOK_SECRET!);
+ */
+export declare function verifyWebhook<T = unknown>(body: string, headers: Headers | Record<string, string | string[] | undefined>, secret: string, toleranceSeconds?: number): Promise<T>;

package/dist/index.js

@@ -35,7 +35,7 @@ export class MailClient {
             try {
                 const res = await f(`${base}${path}`, {
                     method, signal: ctl.signal,
-                    headers: { Authorization: `Bearer ${this.o.apiKey}`, "Content-Type": "application/json", "User-Agent": "mailtruss-node/0.1.0", ...(opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {}) },
+                    headers: { Authorization: `Bearer ${this.o.apiKey}`, "Content-Type": "application/json", "User-Agent": "mailtruss-node/0.1.1", ...(opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {}) },
                     body: body === undefined ? undefined : JSON.stringify(body),
                 });
                 const json = (await res.json().catch(() => null));
@@ -74,6 +74,8 @@ export class MailClient {
         list: (q = {}, o) => this.request("GET", `/api/v1/emails${this.q(q)}`, undefined, o),
         reschedule: (id, scheduled_at, o) => this.request("PATCH", `/api/v1/emails/${encodeURIComponent(id)}`, { scheduled_at }, o),
         cancel: (id, o) => this.request("POST", `/api/v1/emails/${encodeURIComponent(id)}/cancel`, undefined, o),
+        /** The delivery timeline with what each event proves, and a plain-language diagnosis when something went wrong. */
+        events: (id, o) => this.request("GET", `/api/v1/emails/${encodeURIComponent(id)}/events`, undefined, o),
     };
     domains = {
         create: (p, o) => this.request("POST", "/api/v1/domains", p, o),
@@ -149,3 +151,40 @@ export class MailClient {
         list: (q = {}, o) => this.request("GET", `/api/v1/logs${this.q(q)}`, undefined, o),
     };
 }
+/**
+ * Verifies a Mailtruss webhook (Standard Webhooks format). Pass the raw request body exactly as received, the request headers,
+ * and the endpoint's signing secret. Returns the parsed event, or throws if the signature or timestamp is wrong.
+ * Works in Node 18+, edge runtimes and Workers (Web Crypto). Standard libraries (`standardwebhooks`, `svix`) also work.
+ *
+ *   const event = await verifyWebhook(await req.text(), req.headers, process.env.MAILTRUSS_WEBHOOK_SECRET!);
+ */
+export async function verifyWebhook(body, headers, secret, toleranceSeconds = 300) {
+    const h = (k) => {
+        const v = headers instanceof Headers ? headers.get(k) : headers[k] ?? headers[k.toLowerCase()];
+        return Array.isArray(v) ? v[0] : v ?? undefined;
+    };
+    const id = h("webhook-id") ?? h("svix-id"), ts = h("webhook-timestamp") ?? h("svix-timestamp"), sigs = h("webhook-signature") ?? h("svix-signature");
+    if (!id || !ts || !sigs)
+        throw new Error("Missing webhook-id, webhook-timestamp or webhook-signature header");
+    if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds)
+        throw new Error("Webhook timestamp is outside the allowed window");
+    // Secrets issued before 2026-11-14 (whsec_ + 32 url-safe characters) were used as text; newer ones are base64 key bytes.
+    const raw = secret.replace(/^whsec_/, "");
+    const legacy = /^whsec_[A-Za-z0-9_-]{32}$/.test(secret);
+    const keyBytes = legacy ? new TextEncoder().encode(secret) : Uint8Array.from(atob(raw), (c) => c.charCodeAt(0));
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${id}.${ts}.${body}`)));
+    const expected = btoa(String.fromCharCode(...mac));
+    const ok = sigs.split(" ").some((part) => {
+        const [v, sig] = part.split(",");
+        if (v !== "v1" || !sig || sig.length !== expected.length)
+            return false;
+        let diff = 0;
+        for (let i = 0; i < sig.length; i++)
+            diff |= sig.charCodeAt(i) ^ expected.charCodeAt(i);
+        return diff === 0;
+    });
+    if (!ok)
+        throw new Error("Webhook signature does not match");
+    return JSON.parse(body);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailtruss",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official TypeScript and JavaScript client for the Mailtruss email API",
   "license": "MIT",
   "author": "Mailtruss <hello@mailtruss.com>",