@mailhooks/sdk 1.0.4 → 1.1.3

package/README.md

@@ -62,6 +62,7 @@ const emails = await mailhooks.emails.list({
     subject: 'Important',
     startDate: '2024-01-01',
     endDate: '2024-12-31',
+    read: false, // Filter by read status
   },
   sort: {
     field: 'createdAt',
@@ -73,7 +74,11 @@ const emails = await mailhooks.emails.list({
 #### Get Email
 
 ```typescript
+// Get email without marking as read
 const email = await mailhooks.emails.getEmail('email-id');
+
+// Get email and mark it as read in one call
+const readEmail = await mailhooks.emails.getEmail('email-id', true);
 ```
 
 #### Get Email Content
@@ -99,14 +104,29 @@ const attachment = await mailhooks.emails.downloadAttachment('email-id', 'attach
 // attachment.contentType contains the MIME type
 ```
 
+#### Mark Email as Read/Unread
+
+```typescript
+// Mark email as read
+const readEmail = await mailhooks.emails.markAsRead('email-id');
+console.log(readEmail.read); // true
+
+// Mark email as unread
+const unreadEmail = await mailhooks.emails.markAsUnread('email-id');
+console.log(unreadEmail.read); // false
+```
+
 #### Wait for Email
 
 Wait for an email that matches specific filters. Useful for testing and automation.
 
 ```typescript
-// Basic usage - wait for email from specific sender
+// Basic usage - wait for unread email from specific sender
 const email = await mailhooks.emails.waitFor({
-  filter: { from: 'noreply@example.com' },
+  filter: { 
+    from: 'noreply@example.com',
+    read: false // Only wait for unread emails
+  },
   timeout: 30000, // 30 seconds
   pollInterval: 2000, // Check every 2 seconds
 });
@@ -117,6 +137,7 @@ const email = await mailhooks.emails.waitFor({
     from: 'noreply@example.com',
     to: 'test@yourdomain.com',
     subject: 'Order Confirmation',
+    read: false, // Only unread emails
   },
   lookbackWindow: 10000, // Only consider emails from last 10 seconds
   initialDelay: 5000,    // Wait 5 seconds before first check
@@ -127,7 +148,7 @@ const email = await mailhooks.emails.waitFor({
 ```
 
 **Options:**
-- `filter`: Same filters as `list()` method (from, to, subject, startDate, endDate)
+- `filter`: Same filters as `list()` method (from, to, subject, startDate, endDate, read)
 - `lookbackWindow`: How far back to look for emails on first check (default: 10000ms)
 - `initialDelay`: Delay before starting to poll (default: 0ms)
 - `timeout`: Maximum time to wait before throwing error (default: 30000ms)
@@ -150,6 +171,7 @@ interface Email {
   from: string;
   to: string[];
   subject: string;
+  read: boolean;
   createdAt: Date;
   attachments: Attachment[];
 }
@@ -189,6 +211,122 @@ try {
 - **404 Not Found**: Resource not found
 - **429 Too Many Requests**: Rate limit exceeded
 
+## Webhook Signature Verification
+
+When you create a webhook in Mailhooks, you receive a secret that can be used to verify that incoming webhook requests are genuinely from Mailhooks. Each webhook request includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature of the request body.
+
+### Verifying Signatures
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@mailhooks/sdk';
+
+// Express.js example - IMPORTANT: Use raw body parser for signature verification
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-webhook-signature'] as string;
+  const payload = req.body.toString();
+
+  // Verify the signature using your webhook secret
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+    console.error('Invalid webhook signature');
+    return res.status(401).send('Invalid signature');
+  }
+
+  // Parse the verified payload
+  const event = parseWebhookPayload(payload);
+
+  console.log(`Received email from ${event.from}: ${event.subject}`);
+
+  // Process the webhook...
+  res.status(200).send('OK');
+});
+```
+
+### Webhook Payload
+
+The webhook payload contains the following fields:
+
+```typescript
+interface WebhookPayload {
+  id: string;           // Unique email ID
+  from: string;         // Sender email address
+  to: string[];         // Array of recipient addresses
+  subject: string;      // Email subject
+  body: string;         // Plain text body
+  html?: string;        // HTML body (if available)
+  attachments: Array<{  // Attachment metadata
+    filename: string;
+    contentType: string;
+    size: number;
+  }>;
+  receivedAt: string;   // ISO 8601 timestamp
+
+  // Email authentication results
+  spfResult?: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none';
+  dkimResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+  dmarcResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+  authSummary?: 'pass' | 'fail' | 'partial';
+
+  // Spam detection
+  spamScore?: number;   // 0.0 to 1.0
+  isSpam?: boolean;
+}
+```
+
+### Security Best Practices
+
+1. **Always verify signatures** before processing webhook data
+2. **Use the raw request body** for signature verification (not parsed JSON)
+3. **Store secrets securely** in environment variables, not in code
+4. **Use HTTPS** for your webhook endpoint
+5. **Respond quickly** - return 200 OK before doing heavy processing
+
+### Framework Examples
+
+#### Next.js API Route
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@mailhooks/sdk';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  const payload = await request.text();
+  const signature = request.headers.get('x-webhook-signature') || '';
+
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+  }
+
+  const event = parseWebhookPayload(payload);
+  // Process event...
+
+  return NextResponse.json({ received: true });
+}
+```
+
+#### Fastify
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@mailhooks/sdk';
+
+fastify.post('/webhook', {
+  config: {
+    rawBody: true, // Enable raw body
+  },
+}, async (request, reply) => {
+  const signature = request.headers['x-webhook-signature'] as string;
+  const payload = request.rawBody?.toString() || '';
+
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+    return reply.status(401).send({ error: 'Invalid signature' });
+  }
+
+  const event = parseWebhookPayload(payload);
+  // Process event...
+
+  return { received: true };
+});
+```
+
 ## License
 
 MIT

package/dist/client.d.ts

@@ -7,6 +7,7 @@ export declare class MailhooksClient {
     protected get<T>(path: string, params?: Record<string, any>): Promise<T>;
     protected post<T>(path: string, data?: any): Promise<T>;
     protected put<T>(path: string, data?: any): Promise<T>;
+    protected patch<T>(path: string, data?: any): Promise<T>;
     protected delete<T>(path: string): Promise<T>;
     protected downloadFile(path: string): Promise<ArrayBuffer>;
     protected getAxiosInstance(): AxiosInstance;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,aAAa,EAAiB,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAgB;gBAEhB,MAAM,EAAE,eAAe;IAkBnC,OAAO,CAAC,UAAU;cAkBF,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;cAK9D,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;cAK7C,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;cAK5C,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;cAKnC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAOhE,SAAS,CAAC,gBAAgB,IAAI,aAAa;CAG5C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,aAAa,EAAiB,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAgB;gBAEhB,MAAM,EAAE,eAAe;IAkBnC,OAAO,CAAC,UAAU;cAkBF,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;cAK9D,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;cAK7C,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;cAK5C,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;cAK9C,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;cAKnC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAOhE,SAAS,CAAC,gBAAgB,IAAI,aAAa;CAG5C"}

package/dist/client.js

@@ -53,6 +53,10 @@ class MailhooksClient {
         const response = await this.http.put(path, data);
         return response.data;
     }
+    async patch(path, data) {
+        const response = await this.http.patch(path, data);
+        return response.data;
+    }
     async delete(path) {
         const response = await this.http.delete(path);
         return response.data;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { Mailhooks } from './mailhooks';
 export { EmailsResource } from './resources/emails';
 export * from './types';
+export { verifyWebhookSignature, parseWebhookPayload, constructSignature, type WebhookPayload, } from './webhooks';
 import { Mailhooks } from './mailhooks';
 export default Mailhooks;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,eAAe,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -14,12 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailsResource = exports.Mailhooks = void 0;
+exports.constructSignature = exports.parseWebhookPayload = exports.verifyWebhookSignature = exports.EmailsResource = exports.Mailhooks = void 0;
 var mailhooks_1 = require("./mailhooks");
 Object.defineProperty(exports, "Mailhooks", { enumerable: true, get: function () { return mailhooks_1.Mailhooks; } });
 var emails_1 = require("./resources/emails");
 Object.defineProperty(exports, "EmailsResource", { enumerable: true, get: function () { return emails_1.EmailsResource; } });
 __exportStar(require("./types"), exports);
+// Webhook verification utilities
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "parseWebhookPayload", { enumerable: true, get: function () { return webhooks_1.parseWebhookPayload; } });
+Object.defineProperty(exports, "constructSignature", { enumerable: true, get: function () { return webhooks_1.constructSignature; } });
 // Default export for convenience
 const mailhooks_2 = require("./mailhooks");
 exports.default = mailhooks_2.Mailhooks;

package/dist/resources/emails.d.ts

@@ -7,8 +7,10 @@ export declare class EmailsResource extends MailhooksClient {
     list(params?: EmailListParams): Promise<EmailsResponse>;
     /**
      * Get a specific email by ID
+     * @param emailId - The ID of the email to retrieve
+     * @param markAsRead - Optional: Mark the email as read when fetching (default: false)
      */
-    getEmail(emailId: string): Promise<Email>;
+    getEmail(emailId: string, markAsRead?: boolean): Promise<Email>;
     /**
      * Get the HTML and text content of an email
      */
@@ -21,6 +23,14 @@ export declare class EmailsResource extends MailhooksClient {
      * Download a specific attachment from an email
      */
     downloadAttachment(emailId: string, attachmentId: string): Promise<DownloadResponse>;
+    /**
+     * Mark an email as read
+     */
+    markAsRead(emailId: string): Promise<Email>;
+    /**
+     * Mark an email as unread
+     */
+    markAsUnread(emailId: string): Promise<Email>;
     /**
      * Wait for an email that matches the given filters
      *

package/dist/resources/emails.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emails.d.ts","sourceRoot":"","sources":["../../src/resources/emails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,KAAK,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACf,MAAM,UAAU,CAAC;AAElB,qBAAa,cAAe,SAAQ,eAAe;IACjD;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAyB7D;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAI/C;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIxD;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAS7D;;OAEG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC;IAqB5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,KAAK,CAAC;CA8F5D"}
+{"version":3,"file":"emails.d.ts","sourceRoot":"","sources":["../../src/resources/emails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,KAAK,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACf,MAAM,UAAU,CAAC;AAElB,qBAAa,cAAe,SAAQ,eAAe;IACjD;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IA0B7D;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG,OAAO,CAAC,KAAK,CAAC;IAK5E;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIxD;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAS7D;;OAEG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC;IAqB5B;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAIjD;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAInD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,KAAK,CAAC;CA8F5D"}

package/dist/resources/emails.js

@@ -24,6 +24,8 @@ class EmailsResource extends client_1.MailhooksClient {
                 queryParams['filter.createdAfter'] = params.filter.startDate;
             if (params.filter.endDate)
                 queryParams['filter.createdBefore'] = params.filter.endDate;
+            if (params.filter.read !== undefined)
+                queryParams['filter.read'] = String(params.filter.read);
         }
         // Handle sort params
         if (params?.sort) {
@@ -36,9 +38,12 @@ class EmailsResource extends client_1.MailhooksClient {
     }
     /**
      * Get a specific email by ID
+     * @param emailId - The ID of the email to retrieve
+     * @param markAsRead - Optional: Mark the email as read when fetching (default: false)
      */
-    async getEmail(emailId) {
-        return super.get(`/v1/emails/${emailId}`);
+    async getEmail(emailId, markAsRead = false) {
+        const params = markAsRead ? { markAsRead: 'true' } : undefined;
+        return super.get(`/v1/emails/${emailId}`, params);
     }
     /**
      * Get the HTML and text content of an email
@@ -75,6 +80,18 @@ class EmailsResource extends client_1.MailhooksClient {
             contentType: response.headers['content-type'],
         };
     }
+    /**
+     * Mark an email as read
+     */
+    async markAsRead(emailId) {
+        return super.patch(`/v1/emails/${emailId}/read`);
+    }
+    /**
+     * Mark an email as unread
+     */
+    async markAsUnread(emailId) {
+        return super.patch(`/v1/emails/${emailId}/unread`);
+    }
     /**
      * Wait for an email that matches the given filters
      *

package/dist/types.d.ts

@@ -9,6 +9,7 @@ export interface Email {
     from: string;
     to: string[];
     subject: string;
+    read: boolean;
     createdAt: Date;
     attachments: Attachment[];
 }
@@ -33,6 +34,7 @@ export interface EmailFilter {
     subject?: string;
     startDate?: string;
     endDate?: string;
+    read?: boolean;
 }
 export interface EmailSort {
     field?: 'createdAt' | 'from' | 'subject';

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAe,SAAQ,kBAAkB;IACxD,IAAI,EAAE,KAAK,EAAE,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAe,SAAQ,kBAAkB;IACxD,IAAI,EAAE,KAAK,EAAE,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/webhooks.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Webhook payload sent by Mailhooks when an email is received.
+ */
+export interface WebhookPayload {
+    /** Unique email ID */
+    id: string;
+    /** Sender email address */
+    from: string;
+    /** Array of recipient email addresses */
+    to: string[];
+    /** Email subject line */
+    subject: string;
+    /** Plain text body of the email */
+    body: string;
+    /** HTML body of the email (if available) */
+    html?: string;
+    /** Array of attachment metadata */
+    attachments: Array<{
+        filename: string;
+        contentType: string;
+        size: number;
+    }>;
+    /** ISO 8601 timestamp when the email was received */
+    receivedAt: string;
+    /** SPF authentication result */
+    spfResult?: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none';
+    /** DKIM authentication result */
+    dkimResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+    /** DMARC authentication result */
+    dmarcResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+    /** Overall authentication summary */
+    authSummary?: 'pass' | 'fail' | 'partial';
+    /** Email headers as key-value pairs */
+    headers?: Record<string, string>;
+    /** Authentication diagnostic details */
+    authDiagnostics?: {
+        spf: {
+            clientIp: string;
+            domain: string;
+            record?: string;
+            helo?: string;
+        } | null;
+        dkim: Array<{
+            domain: string;
+            selector?: string;
+            algorithm?: string;
+            aligned?: boolean;
+            result: string;
+        }>;
+        dmarc: {
+            domain: string;
+            policy: string;
+            record?: string;
+            alignment: {
+                spf: {
+                    result: string | false;
+                    strict: boolean;
+                };
+                dkim: {
+                    result: string | false;
+                    strict: boolean;
+                };
+            };
+        } | null;
+    };
+}
+/**
+ * Verifies a webhook signature using HMAC-SHA256.
+ *
+ * Each webhook request from Mailhooks includes an `X-Webhook-Signature` header
+ * containing a hex-encoded HMAC-SHA256 signature of the request body.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param signature - The signature from the `X-Webhook-Signature` header
+ * @param secret - Your webhook secret (starts with `whsec_`)
+ * @returns `true` if the signature is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@mailhooks/sdk';
+ *
+ * // Express.js with raw body parser
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const payload = req.body.toString();
+ *
+ *   if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(payload);
+ *   // Process the webhook...
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+/**
+ * Parses a webhook payload from a JSON string.
+ *
+ * @param body - The raw request body as a string
+ * @returns The parsed webhook payload
+ * @throws {SyntaxError} If the body is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookPayload } from '@mailhooks/sdk';
+ *
+ * const payload = parseWebhookPayload(req.body.toString());
+ * console.log(`Received email from ${payload.from}: ${payload.subject}`);
+ * ```
+ */
+export declare function parseWebhookPayload(body: string): WebhookPayload;
+/**
+ * Constructs the expected signature for a webhook payload.
+ * Useful for debugging or manual verification.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param secret - Your webhook secret
+ * @returns The expected HMAC-SHA256 signature as a hex string
+ */
+export declare function constructSignature(payload: string | Buffer, secret: string): string;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,WAAW,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC9D,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IAClE,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IACnE,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,wCAAwC;IACxC,eAAe,CAAC,EAAE;QAChB,GAAG,EAAE;YACH,QAAQ,EAAE,MAAM,CAAC;YACjB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,CAAC;SACf,GAAG,IAAI,CAAC;QACT,IAAI,EAAE,KAAK,CAAC;YACV,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,OAAO,CAAC,EAAE,OAAO,CAAC;YAClB,MAAM,EAAE,MAAM,CAAC;SAChB,CAAC,CAAC;QACH,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,SAAS,EAAE;gBACT,GAAG,EAAE;oBAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;oBAAC,MAAM,EAAE,OAAO,CAAA;iBAAE,CAAC;gBACjD,IAAI,EAAE;oBAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;oBAAC,MAAM,EAAE,OAAO,CAAA;iBAAE,CAAC;aACnD,CAAC;SACH,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAqBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,MAAM,CAER"}

package/dist/webhooks.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.parseWebhookPayload = parseWebhookPayload;
+exports.constructSignature = constructSignature;
+const crypto_1 = require("crypto");
+/**
+ * Verifies a webhook signature using HMAC-SHA256.
+ *
+ * Each webhook request from Mailhooks includes an `X-Webhook-Signature` header
+ * containing a hex-encoded HMAC-SHA256 signature of the request body.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param signature - The signature from the `X-Webhook-Signature` header
+ * @param secret - Your webhook secret (starts with `whsec_`)
+ * @returns `true` if the signature is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@mailhooks/sdk';
+ *
+ * // Express.js with raw body parser
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const payload = req.body.toString();
+ *
+ *   if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(payload);
+ *   // Process the webhook...
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+function verifyWebhookSignature(payload, signature, secret) {
+    if (!payload || !signature || !secret) {
+        return false;
+    }
+    // Normalize and validate signature format (should be 64 hex chars for SHA256)
+    const normalizedSignature = signature.trim().toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(normalizedSignature)) {
+        return false;
+    }
+    const expectedSignature = (0, crypto_1.createHmac)('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    // Use timing-safe comparison to prevent timing attacks
+    // Both buffers are guaranteed to be 32 bytes (64 hex chars)
+    return (0, crypto_1.timingSafeEqual)(Buffer.from(normalizedSignature, 'hex'), Buffer.from(expectedSignature, 'hex'));
+}
+/**
+ * Parses a webhook payload from a JSON string.
+ *
+ * @param body - The raw request body as a string
+ * @returns The parsed webhook payload
+ * @throws {SyntaxError} If the body is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookPayload } from '@mailhooks/sdk';
+ *
+ * const payload = parseWebhookPayload(req.body.toString());
+ * console.log(`Received email from ${payload.from}: ${payload.subject}`);
+ * ```
+ */
+function parseWebhookPayload(body) {
+    return JSON.parse(body);
+}
+/**
+ * Constructs the expected signature for a webhook payload.
+ * Useful for debugging or manual verification.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param secret - Your webhook secret
+ * @returns The expected HMAC-SHA256 signature as a hex string
+ */
+function constructSignature(payload, secret) {
+    return (0, crypto_1.createHmac)('sha256', secret).update(payload).digest('hex');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailhooks/sdk",
-  "version": "1.0.4",
+  "version": "1.1.3",
   "description": "TypeScript SDK for Mailhooks API",
   "publishConfig": {
     "access": "public"