@mailhooks/sdk 2.1.0 → 2.2.0

package/README.md

@@ -257,6 +257,7 @@ interface WebhookPayload {
     filename: string;
     contentType: string;
     size: number;
+    storagePath?: string; // Storage path (only for custom storage)
   }>;
   receivedAt: string;   // ISO 8601 timestamp
 
@@ -266,9 +267,9 @@ interface WebhookPayload {
   dmarcResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
   authSummary?: 'pass' | 'fail' | 'partial';
 
-  // Spam detection
-  spamScore?: number;   // 0.0 to 1.0
-  isSpam?: boolean;
+  // Custom storage (BYOB)
+  usesCustomStorage: boolean; // true if using your own S3 bucket
+  storagePath?: string;       // EML file path (only for custom storage)
 }
 ```
 
@@ -327,6 +328,98 @@ fastify.post('/webhook', {
 });
 ```
 
+## Parsing EML Files (BYOB)
+
+If you use custom storage (Bring Your Own Bucket), you can fetch and parse EML files directly using the `parseEml` function. This is useful when you want to process emails from your own S3-compatible storage.
+
+### Basic Usage
+
+```typescript
+import { parseEml } from '@mailhooks/sdk';
+import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+
+// Fetch EML from your S3 bucket
+const s3 = new S3Client({ region: 'us-east-1' });
+const response = await s3.send(new GetObjectCommand({
+  Bucket: 'my-email-bucket',
+  Key: storagePath, // from webhook payload
+}));
+
+const emlBuffer = Buffer.from(await response.Body!.transformToByteArray());
+
+// Parse the EML
+const email = await parseEml(emlBuffer);
+
+console.log(email.from);        // "sender@example.com"
+console.log(email.to);          // ["recipient@yourdomain.com"]
+console.log(email.subject);     // "Hello World"
+console.log(email.body);        // Plain text content
+console.log(email.html);        // HTML content (if available)
+console.log(email.headers);     // All headers as key-value pairs
+console.log(email.attachments); // [{ filename, contentType, size }]
+console.log(email.date);        // Date object from Date header
+```
+
+### Webhook Integration
+
+When using custom storage, your webhook payload includes `storagePath` for both the email and attachments:
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload, parseEml } from '@mailhooks/sdk';
+
+app.post('/webhook', express.raw({ type: 'application/json' }), async (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 = parseWebhookPayload(payload);
+
+  // For custom storage users
+  if (event.usesCustomStorage && event.storagePath) {
+    // Fetch and parse the full email from your storage
+    const emlBuffer = await fetchFromS3(event.storagePath);
+    const fullEmail = await parseEml(emlBuffer);
+
+    // Access full email content
+    console.log(fullEmail.html);
+    console.log(fullEmail.headers);
+  }
+
+  // Attachment paths are also available for custom storage
+  for (const attachment of event.attachments) {
+    if (attachment.storagePath) {
+      // Fetch attachment from your storage
+      const attachmentBuffer = await fetchFromS3(attachment.storagePath);
+      // Process attachment...
+    }
+  }
+
+  res.status(200).send('OK');
+});
+```
+
+### ParsedEmail Type
+
+```typescript
+interface ParsedEmail {
+  from: string;           // Sender email address
+  to: string[];           // 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;
+  }>;
+  headers: Record<string, string>; // All email headers
+  date?: Date;            // Date from headers
+}
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -168,6 +168,8 @@ interface WebhookPayload {
         filename: string;
         contentType: string;
         size: number;
+        /** Storage path for the attachment (only present when usesCustomStorage is true) */
+        storagePath?: string;
     }>;
     /** ISO 8601 timestamp when the email was received */
     receivedAt: string;
@@ -274,4 +276,61 @@ declare function parseWebhookPayload(body: string): WebhookPayload;
  */
 declare function constructSignature(payload: string | Buffer, secret: string): string;
 
-export { type Attachment, type DownloadResponse, type Email, type EmailContent, type EmailFilter, type EmailListParams, type EmailSort, EmailsResource, type EmailsResponse, Mailhooks, type MailhooksConfig, type PaginationResponse, type WaitForOptions, type WebhookPayload, constructSignature, Mailhooks as default, parseWebhookPayload, verifyWebhookSignature };
+/**
+ * Parsed email structure returned by parseEml.
+ * Matches the webhook payload structure for consistency.
+ */
+interface ParsedEmail {
+    /** 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;
+    }>;
+    /** Email headers as key-value pairs */
+    headers: Record<string, string>;
+    /** Date the email was sent (from Date header) */
+    date?: Date;
+}
+/**
+ * Parses a raw EML file and returns a structured email object.
+ *
+ * This is useful for BYOB (Bring Your Own Bucket) users who store emails
+ * in their own S3-compatible storage and need to parse them.
+ *
+ * @param eml - The raw EML content as a Buffer or string
+ * @returns A Promise that resolves to the parsed email
+ *
+ * @example
+ * ```typescript
+ * import { parseEml } from '@mailhooks/sdk';
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ *
+ * // Fetch EML from your S3 bucket
+ * const s3 = new S3Client({ region: 'us-east-1' });
+ * const response = await s3.send(new GetObjectCommand({
+ *   Bucket: 'my-email-bucket',
+ *   Key: storagePath, // from webhook payload
+ * }));
+ * const emlBuffer = Buffer.from(await response.Body.transformToByteArray());
+ *
+ * // Parse the EML
+ * const email = await parseEml(emlBuffer);
+ * console.log(email.from);        // "sender@example.com"
+ * console.log(email.subject);     // "Hello World"
+ * console.log(email.attachments); // [{ filename: "doc.pdf", ... }]
+ * ```
+ */
+declare function parseEml(eml: Buffer | string): Promise<ParsedEmail>;
+
+export { type Attachment, type DownloadResponse, type Email, type EmailContent, type EmailFilter, type EmailListParams, type EmailSort, EmailsResource, type EmailsResponse, Mailhooks, type MailhooksConfig, type PaginationResponse, type ParsedEmail, type WaitForOptions, type WebhookPayload, constructSignature, Mailhooks as default, parseEml, parseWebhookPayload, verifyWebhookSignature };

package/dist/index.js

@@ -1,5 +1,6 @@
 import axios from 'axios';
 import { createHmac, timingSafeEqual } from 'crypto';
+import { simpleParser } from 'mailparser';
 
 // src/client.ts
 var MailhooksClient = class {
@@ -273,8 +274,42 @@ function parseWebhookPayload(body) {
 function constructSignature(payload, secret) {
   return createHmac("sha256", secret).update(payload).digest("hex");
 }
+async function parseEml(eml) {
+  const parsed = await simpleParser(eml);
+  const from = parsed.from?.value?.[0]?.address || "";
+  const toAddresses = parsed.to;
+  let to = [];
+  if (toAddresses) {
+    if (Array.isArray(toAddresses)) {
+      to = toAddresses.flatMap(
+        (addr) => addr.value?.map((v) => v.address || "") || []
+      );
+    } else {
+      to = toAddresses.value?.map((v) => v.address || "") || [];
+    }
+  }
+  const headers = {};
+  for (const [key, value] of parsed.headers) {
+    headers[key] = typeof value === "object" ? JSON.stringify(value) : String(value);
+  }
+  const attachments = (parsed.attachments || []).map((att) => ({
+    filename: att.filename || "unknown",
+    contentType: att.contentType || "application/octet-stream",
+    size: att.size || 0
+  }));
+  return {
+    from,
+    to,
+    subject: parsed.subject || "",
+    body: parsed.text || "",
+    html: parsed.html || void 0,
+    attachments,
+    headers,
+    date: parsed.date
+  };
+}
 
 // src/index.ts
 var index_default = Mailhooks;
 
-export { EmailsResource, Mailhooks, constructSignature, index_default as default, parseWebhookPayload, verifyWebhookSignature };
+export { EmailsResource, Mailhooks, constructSignature, index_default as default, parseEml, parseWebhookPayload, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailhooks/sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "TypeScript SDK for Mailhooks API",
   "publishConfig": {
     "access": "public"
@@ -22,9 +22,11 @@
     "api"
   ],
   "dependencies": {
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "mailparser": "^3.7.2"
   },
   "devDependencies": {
+    "@types/mailparser": "^3.4.6",
     "@types/node": "^20.19.0",
     "dotenv": "^17.2.1",
     "tsup": "^8.5.1",