@cedarjs/mailer-handler-ahasend 7.0.0-canary.3261

package/README.md

@@ -0,0 +1,122 @@
+# Mailer - Handler - AhaSend
+
+## Prerequisites
+
+We assume you have the basic boilerplate for Cedar Mailer present. We also
+assume that you have signed up with [AhaSend](https://ahasend.com/), verified a
+sending domain, and have an API key with permission to send messages, along with
+your account ID.
+
+## Setup
+
+We should install this handler package as a production dependency of the API
+side. We can do this with the following command:
+
+```bash
+yarn workspace api add @cedarjs/mailer-handler-ahasend
+```
+
+After this you should be able to import this handler into your
+`api/src/lib/mailer.ts` file and create an instance of this handler with your
+API key and account ID.
+
+```typescript
+import { AhaSendMailHandler } from '@cedarjs/mailer-handler-ahasend'
+
+// ...
+
+export const mailer = new Mailer({
+  handling: {
+    handlers: {
+      // ...
+      ahasend: new AhaSendMailHandler({
+        apiKey: process.env.AHASEND_API_KEY,
+        accountId: process.env.AHASEND_ACCOUNT_ID,
+      }),
+    },
+    // ...
+  },
+  // ...
+})
+```
+
+The handler accepts every option of the `AhaSendClient` from
+[`@ahasend/sdk`](https://github.com/AhaSend/ahasend-ts), such as `timeoutMs` and
+`retry`. By default the client retries failed requests up to three times and
+reuses one idempotency key across those retries. AhaSend stores the outcome of
+every request it accepts or rejects for 24 hours and replays it when a retry
+uses the same key, so such a retry does not queue the email again. Server
+errors are not stored, so a retry after a server error can still deliver the
+email twice.
+
+If you need access to the underlying AhaSend client to perform more specific
+behavior the SDK exposes you can always access this using the `internal`
+function on this AhaSend handler.
+
+```typescript
+const ahasendHandler = mailer.handlers.ahasend
+const ahasendClient = ahasendHandler.internal().client
+```
+
+## Usage
+
+You should be able to use this newly configured handler like any other previous
+handler and it should require no changes to your mailer code.
+
+Each email is sent as a single message that all `to`, `cc` and `bcc` recipients
+share, with `bcc` recipients hidden from the others. AhaSend allows at most 50
+recipients per email.
+
+You can pass AhaSend specific options as the third argument to `mailer.send()`:
+
+```typescript
+await mailer.send(
+  WelcomeEmail({ name: user.name }),
+  { to: user.email, subject: 'Welcome!' },
+  {
+    tags: ['welcome'],
+    idempotencyKey: `welcome-${user.id}`,
+  },
+)
+```
+
+The available options are `tags`, `sandbox`, `sandbox_result`, `tracking`,
+`retention`, `schedule` and `idempotencyKey`. See the
+[AhaSend API reference](https://ahasend.com/docs/api-reference) for what each of
+them does. `sandbox: true` is useful for testing your setup, because AhaSend
+accepts the email without delivering it.
+
+### Attachments
+
+Every attachment needs a filename, either set as `filename` or taken from
+`path`. The attachment's content type is derived from the file extension. String
+`content` is sent as UTF-8 text, and `Buffer` content is sent as binary data. A
+`path` can be a local file or an `http(s)` URL.
+
+## Error Handling
+
+`mailer.send()` rejects when AhaSend does not accept the email, for example
+because of an invalid API key, an unverified sender domain, or a network failure
+that persists through the client's retries. The error from the AhaSend SDK is
+available as the `cause` of the thrown error.
+
+AhaSend reports a result for each recipient. `mailer.send()` also rejects when
+AhaSend accepts none of the recipients, with the per-recipient results as the
+`cause` of the thrown error.
+
+When AhaSend accepts some recipients and rejects others, for example because
+they are on your suppression list, `mailer.send()` resolves. The email has
+already been queued for the accepted recipients, so retrying the send would
+deliver it to them a second time. The result's `messageID` is the ID of the
+first accepted recipient's message, and `handlerInformation` contains the result
+for every recipient:
+
+```typescript
+const result = await mailer.send(/* ... */)
+
+// handlerInformation is typed as unknown by the mailer, so narrow it first
+const recipients = (result.handlerInformation as SendMessageResponse).data
+const rejected = recipients.filter((recipient) => recipient.status === 'error')
+```
+
+`SendMessageResponse` is exported by `@ahasend/sdk`.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { AhaSendClient } from '@ahasend/sdk';
+import type { AhaSendClientOptions, CreateConversationMessageRequest } from '@ahasend/sdk';
+import type { MailSendOptionsComplete, MailRenderedContent, MailResult } from '@cedarjs/mailer-core';
+import { AbstractMailHandler } from '@cedarjs/mailer-core';
+export type AhaSendMailHandlerOptions = Pick<CreateConversationMessageRequest, 'tags' | 'sandbox' | 'sandbox_result' | 'tracking' | 'retention' | 'schedule'> & {
+    /**
+     * Idempotency key for this send. AhaSend replays the stored result for
+     * repeated requests with the same key for 24 hours. When omitted, the SDK
+     * generates a key that is reused across its own retries of this request.
+     */
+    idempotencyKey?: string;
+};
+export declare class AhaSendMailHandler extends AbstractMailHandler {
+    private client;
+    /**
+     * Accepts every `AhaSendClient` option. `apiKey` and `accountId` are
+     * required; the others, such as `retry` and `timeoutMs`, are optional.
+     */
+    constructor(options: AhaSendClientOptions);
+    send(content: MailRenderedContent, sendOptions: MailSendOptionsComplete, handlerOptions?: AhaSendMailHandlerOptions): Promise<MailResult>;
+    internal(): {
+        client: AhaSendClient;
+    };
+}
+//# 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":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAEV,oBAAoB,EAEpB,gCAAgC,EAEjC,MAAM,cAAc,CAAA;AAErB,OAAO,KAAK,EAEV,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACX,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAE1D,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,gCAAgC,EAChC,MAAM,GAAG,SAAS,GAAG,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAC9E,GAAG;IACF;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAmHD,qBAAa,kBAAmB,SAAQ,mBAAmB;IACzD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;OAGG;gBACS,OAAO,EAAE,oBAAoB;IAKnC,IAAI,CACR,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,uBAAuB,EACpC,cAAc,CAAC,EAAE,yBAAyB,GACzC,OAAO,CAAC,UAAU,CAAC;IAqEtB,QAAQ;;;CAKT"}

package/dist/index.js

@@ -0,0 +1,142 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { AhaSendClient } from "@ahasend/sdk";
+import { AbstractMailHandler } from "@cedarjs/mailer-core";
+const contentTypesByExtension = {
+  ".csv": "text/csv",
+  ".gif": "image/gif",
+  ".htm": "text/html",
+  ".html": "text/html",
+  ".ics": "text/calendar",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".json": "application/json",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain",
+  ".webp": "image/webp",
+  ".xml": "application/xml",
+  ".zip": "application/zip"
+};
+function toAhaSendAddress(address) {
+  const trimmed = address.trim();
+  const open = trimmed.lastIndexOf("<");
+  if (open === -1 || !trimmed.endsWith(">")) {
+    return { email: trimmed };
+  }
+  const email = trimmed.slice(open + 1, -1).trim();
+  let name = trimmed.slice(0, open).trim();
+  if (name.length >= 2 && name.startsWith('"') && name.endsWith('"')) {
+    name = name.slice(1, -1);
+  }
+  return name ? { name, email } : { email };
+}
+function toAhaSendAddresses(addresses) {
+  return addresses.length > 0 ? addresses.map(toAhaSendAddress) : void 0;
+}
+async function toAhaSendAttachment(attachment) {
+  const isUrl = /^https?:\/\//.test(attachment.path ?? "");
+  const pathName = attachment.path && isUrl ? new URL(attachment.path).pathname : attachment.path;
+  const fileName = attachment.filename ?? (pathName ? path.basename(pathName) : void 0);
+  if (!fileName) {
+    throw new Error(
+      "AhaSend requires a filename for every attachment. Set `filename` on attachments that are passed as `content`."
+    );
+  }
+  const contentType = contentTypesByExtension[path.extname(fileName).toLowerCase()] ?? "application/octet-stream";
+  if (typeof attachment.content === "string") {
+    return {
+      file_name: fileName,
+      content_type: contentType,
+      data: attachment.content
+    };
+  }
+  let content = attachment.content;
+  if (!content && attachment.path) {
+    content = isUrl ? await fetchAttachment(attachment.path) : await readFile(attachment.path);
+  }
+  if (!content) {
+    throw new Error(
+      `The attachment "${fileName}" has neither \`content\` nor \`path\`.`
+    );
+  }
+  return {
+    file_name: fileName,
+    content_type: contentType,
+    data: content.toString("base64"),
+    base64: true
+  };
+}
+async function fetchAttachment(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch the attachment ${url}: ${response.status} ` + response.statusText
+    );
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+class AhaSendMailHandler extends AbstractMailHandler {
+  client;
+  /**
+   * Accepts every `AhaSendClient` option. `apiKey` and `accountId` are
+   * required; the others, such as `retry` and `timeoutMs`, are optional.
+   */
+  constructor(options) {
+    super();
+    this.client = new AhaSendClient(options);
+  }
+  async send(content, sendOptions, handlerOptions) {
+    const { idempotencyKey, ...messageOptions } = handlerOptions ?? {};
+    const attachments = await Promise.all(
+      sendOptions.attachments.map(toAhaSendAttachment)
+    );
+    let response;
+    try {
+      response = await this.client.messages.sendConversation(
+        {
+          ...messageOptions,
+          // Standard options
+          attachments: attachments.length > 0 ? attachments : void 0,
+          bcc: toAhaSendAddresses(sendOptions.bcc),
+          cc: toAhaSendAddresses(sendOptions.cc),
+          from: toAhaSendAddress(sendOptions.from),
+          headers: sendOptions.headers,
+          reply_to: sendOptions.replyTo ? toAhaSendAddress(sendOptions.replyTo) : void 0,
+          subject: sendOptions.subject,
+          to: sendOptions.to.map(toAhaSendAddress),
+          // Content
+          html_content: content.html,
+          text_content: content.text
+        },
+        { idempotencyKey }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`AhaSend failed to send the email: ${message}`, {
+        cause: error
+      });
+    }
+    const accepted = response.data.filter((result) => result.status !== "error");
+    if (accepted.length === 0) {
+      const reasons = response.data.map((result) => `${result.recipient.email}: ${result.error}`).join("; ");
+      throw new Error(
+        `AhaSend did not accept any recipient of the email: ${reasons}`,
+        { cause: response }
+      );
+    }
+    return {
+      messageID: accepted[0].id ?? void 0,
+      handlerInformation: response
+    };
+  }
+  internal() {
+    return {
+      client: this.client
+    };
+  }
+}
+export {
+  AhaSendMailHandler
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cedarjs/mailer-handler-ahasend",
+  "version": "7.0.0-canary.3261",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cedarjs/cedar.git",
+    "directory": "packages/mailer/handlers/ahasend"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node ./build.mts",
+    "build:pack": "yarn pack -o cedarjs-mailer-handler-ahasend.tgz",
+    "build:types": "tsc --build --verbose ./tsconfig.build.json",
+    "build:watch": "nodemon --watch src --ext \"js,jsx,ts,tsx\" --ignore dist --exec \"yarn build\"",
+    "prepublishOnly": "NODE_ENV=production yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  },
+  "dependencies": {
+    "@ahasend/sdk": "0.2.1",
+    "@cedarjs/mailer-core": "7.0.0-canary.3261"
+  },
+  "devDependencies": {
+    "@cedarjs/framework-tools": "7.0.0-canary.3261",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}