@messagebird/bird-plugin-medusa 0.0.0-stage → 0.1.1

package/dist/message.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invalid = invalid;
+exports.regionalOrigin = regionalOrigin;
+exports.validateOptions = validateOptions;
+exports.prepareMessage = prepareMessage;
+const utils_1 = require("@medusajs/framework/utils");
+const operations_gen_1 = require("./generated/operations.gen");
+function invalid(message) {
+    throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, message);
+}
+function nonBlank(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function regionalOrigin(key) {
+    if (typeof key !== "string")
+        invalid("Set api_key to a current Bird API key.");
+    const match = /^bk_([a-z]{2}\d+)_[A-Za-z0-9_-]+$/.exec(key);
+    if (!match)
+        invalid("Set api_key to a current Bird API key beginning with bk_<region>_.");
+    return `https://${match[1]}.platform.bird.com`;
+}
+function validateOptions(options) {
+    regionalOrigin(options.api_key);
+    if (!Array.isArray(options.channels) ||
+        !options.channels.length ||
+        options.channels.some((c) => c !== "email" && c !== "sms" && c !== "whatsapp")) {
+        invalid("Set channels to email, sms, whatsapp, or a combination of them.");
+    }
+    for (const field of ["email_from", "sms_from", "whatsapp_from"]) {
+        if (options[field] !== undefined && !nonBlank(options[field])) {
+            invalid(`Set ${field} to a non-empty sender, or omit it and supply notification.from.`);
+        }
+    }
+}
+function prepareMessage(notification, options) {
+    const channel = notification.channel;
+    if ((channel !== "email" && channel !== "sms" && channel !== "whatsapp") ||
+        !options.channels.includes(channel)) {
+        invalid("This Bird provider is not configured for the notification channel. Enable email, sms, or whatsapp in channels.");
+    }
+    if (!nonBlank(notification.to))
+        invalid("Set notification.to to a recipient.");
+    const extra = notification.provider_data ?? {};
+    const allowed = new Set([
+        "language",
+        "idempotency_key",
+        ...(channel === "whatsapp" ? ["preview_url"] : ["category"]),
+        ...(channel === "email" ? ["cc", "bcc", "reply_to"] : []),
+    ]);
+    if (Object.keys(extra).some((key) => !allowed.has(key))) {
+        invalid("Unsupported provider_data field. See the Bird provider's documented options.");
+    }
+    const idempotencyKey = extra.idempotency_key;
+    if (idempotencyKey !== undefined &&
+        (!nonBlank(idempotencyKey) ||
+            idempotencyKey.length > 255 ||
+            /[\r\n]/.test(idempotencyKey))) {
+        invalid("Set provider_data.idempotency_key to a non-empty string of at most 255 characters without line breaks.");
+    }
+    const language = extra.language;
+    if (language !== undefined && !nonBlank(language))
+        invalid("Set provider_data.language to a language tag, or omit it.");
+    if (notification.data != null &&
+        (typeof notification.data !== "object" || Array.isArray(notification.data))) {
+        invalid("Set notification.data to an object containing template parameters.");
+    }
+    const connection = { idempotencyKey: idempotencyKey };
+    switch (channel) {
+        case "email":
+            return {
+                ...operations_gen_1.birdOperations.email,
+                ...connection,
+                body: prepareEmailMessage(notification, options, language),
+            };
+        case "sms":
+            return {
+                ...operations_gen_1.birdOperations.sms,
+                ...connection,
+                body: prepareSmsMessage(notification, options, language),
+            };
+        case "whatsapp":
+            return {
+                ...operations_gen_1.birdOperations.whatsapp,
+                ...connection,
+                body: prepareWhatsAppMessage(notification, options, language),
+            };
+    }
+}
+function category(value, categories, channel) {
+    for (const candidate of categories) {
+        if (value === candidate)
+            return candidate;
+    }
+    return invalid(`Unsupported ${channel} category.`);
+}
+function templateSelector(template, prefix) {
+    if (!nonBlank(template)) {
+        invalid("Set notification.template to a Bird template ID or slug, or supply inline content.");
+    }
+    const value = template.trim();
+    return value.startsWith(prefix) ? { id: value } : { slug: value };
+}
+function prepareEmailMessage(notification, options, language) {
+    const from = notification.from?.trim() || options.email_from;
+    if (!from) {
+        invalid("Set email_from or notification.from to an address on your verified Bird domain.");
+    }
+    const extra = notification.provider_data ?? {};
+    const body = { from, to: [notification.to] };
+    const content = notification.content;
+    if (content != null) {
+        if (extra.language !== undefined) {
+            invalid("provider_data.language applies to stored templates. Omit it for inline content.");
+        }
+        if (!nonBlank(content.subject) ||
+            (!nonBlank(content.html) && !nonBlank(content.text))) {
+            invalid("Inline email requires content.subject and content.html or content.text.");
+        }
+        body.subject = content.subject;
+        if (content.html !== undefined)
+            body.html = content.html;
+        if (content.text !== undefined)
+            body.text = content.text;
+        if (notification.data != null)
+            body.parameters = notification.data;
+        body.category = category(extra.category ?? "transactional", operations_gen_1.birdOperations.email.categories, "email");
+    }
+    else {
+        body.template = {
+            ...templateSelector(notification.template, "emt_"),
+            ...(language === undefined ? {} : { language }),
+            ...(notification.data == null ? {} : { parameters: notification.data }),
+        };
+        if (extra.category !== undefined) {
+            body.category = category(extra.category, operations_gen_1.birdOperations.email.categories, "email");
+        }
+    }
+    for (const field of ["cc", "bcc", "reply_to"]) {
+        const addresses = extra[field];
+        if (addresses !== undefined) {
+            if (!Array.isArray(addresses) ||
+                !addresses.length ||
+                addresses.some((address) => !nonBlank(address))) {
+                invalid(`Set provider_data.${field} to a non-empty array of email addresses.`);
+            }
+            body[field] = addresses;
+        }
+    }
+    if (notification.attachments?.length) {
+        body.attachments = notification.attachments.map((attachment) => {
+            if (attachment.disposition &&
+                !["attachment", "inline"].includes(attachment.disposition)) {
+                invalid("Email attachment disposition must be attachment or inline.");
+            }
+            if (attachment.disposition === "inline" && !nonBlank(attachment.id)) {
+                invalid("An inline attachment requires an id referenced by cid: in the HTML.");
+            }
+            if (attachment.id && attachment.disposition === "attachment") {
+                invalid("Omit attachment.id for a downloadable attachment, or set disposition to inline.");
+            }
+            return {
+                filename: attachment.filename,
+                content: attachment.content,
+                ...(attachment.content_type
+                    ? { content_type: attachment.content_type }
+                    : {}),
+                ...(attachment.id ? { content_id: attachment.id } : {}),
+            };
+        });
+    }
+    return body;
+}
+function messagingSender(notification, defaultSender) {
+    if (notification.content == null &&
+        notification.template?.trim().startsWith("bird_")) {
+        if (nonBlank(notification.from)) {
+            invalid("Omit notification.from for built-in SMS and WhatsApp templates; Bird selects their sender.");
+        }
+        return undefined;
+    }
+    return notification.from?.trim() || defaultSender;
+}
+function prepareSmsMessage(notification, options, language) {
+    if (notification.attachments?.length)
+        invalid("SMS notifications do not support attachments.");
+    const from = messagingSender(notification, options.sms_from);
+    const extra = notification.provider_data ?? {};
+    const content = notification.content;
+    if (content != null) {
+        if (extra.language !== undefined) {
+            invalid("provider_data.language applies to stored templates. Omit it for inline content.");
+        }
+        if (!from)
+            invalid("Set sms_from or notification.from before sending inline sms content.");
+        if (!nonBlank(content.text) ||
+            content.html !== undefined ||
+            content.subject !== undefined) {
+            invalid("Inline SMS requires content.text and does not support content.html or content.subject.");
+        }
+        if (notification.data && Object.keys(notification.data).length) {
+            invalid("Inline SMS does not interpolate notification.data. Render content.text before sending, or use a stored template.");
+        }
+        return {
+            from,
+            to: notification.to,
+            text: content.text,
+            category: category(extra.category ?? "transactional", operations_gen_1.birdOperations.sms.categories, "sms"),
+        };
+    }
+    if (extra.category !== undefined) {
+        invalid("Omit provider_data.category for SMS templates; the template supplies it.");
+    }
+    return {
+        to: notification.to,
+        ...(from ? { from } : {}),
+        template: {
+            ...templateSelector(notification.template, "smt_"),
+            ...(language === undefined ? {} : { language }),
+            ...(notification.data == null ? {} : { parameters: notification.data }),
+        },
+    };
+}
+function prepareWhatsAppMessage(notification, options, language) {
+    const from = messagingSender(notification, options.whatsapp_from);
+    const body = {
+        to: notification.to,
+        ...(from ? { from } : {}),
+    };
+    const extra = notification.provider_data ?? {};
+    if (notification.attachments?.length) {
+        invalid("WhatsApp notifications do not support attachments. Use media in an approved template's components.");
+    }
+    if (notification.content != null) {
+        if (extra.language !== undefined) {
+            invalid("provider_data.language applies to stored templates. Omit it for inline content.");
+        }
+        if (!from) {
+            invalid("Set whatsapp_from or notification.from before sending inline WhatsApp content.");
+        }
+        const content = notification.content;
+        if (!nonBlank(content.text) ||
+            content.html !== undefined ||
+            content.subject !== undefined) {
+            invalid("Inline WhatsApp requires content.text and does not support content.html or content.subject.");
+        }
+        if ([...content.text].length > 4096) {
+            invalid("Inline WhatsApp content.text must be at most 4096 characters.");
+        }
+        if (notification.data && Object.keys(notification.data).length) {
+            invalid("Inline WhatsApp does not interpolate notification.data. Render content.text before sending, or use a stored template.");
+        }
+        if (extra.preview_url !== undefined &&
+            typeof extra.preview_url !== "boolean") {
+            invalid("Set provider_data.preview_url to a boolean, or omit it.");
+        }
+        body.text = {
+            body: content.text,
+            ...(extra.preview_url === undefined
+                ? {}
+                : { preview_url: extra.preview_url }),
+        };
+    }
+    else {
+        if (!nonBlank(notification.template)) {
+            invalid("Set notification.template to a Bird WhatsApp template ID or slug, or supply inline content.");
+        }
+        if (extra.preview_url !== undefined) {
+            invalid("provider_data.preview_url applies to inline WhatsApp text. Omit it for stored templates.");
+        }
+        const data = notification.data ?? {};
+        if (Object.keys(data).some((key) => key !== "components") ||
+            (data.components !== undefined &&
+                (!Array.isArray(data.components) ||
+                    data.components.some((component) => !component ||
+                        typeof component !== "object" ||
+                        Array.isArray(component) ||
+                        !nonBlank(component.type))))) {
+            invalid("Set WhatsApp notification.data.components to an array of template component objects with a type, or omit data for a template without parameters.");
+        }
+        const template = notification.template.trim();
+        body.template = {
+            ...templateSelector(template, "wat_"),
+            ...(language === undefined ? {} : { language }),
+            ...(data.components === undefined ? {} : { components: data.components }),
+        };
+    }
+    return body;
+}

package/dist/providers/bird/index.d.ts

@@ -0,0 +1,4 @@
+import { BirdNotificationProviderService } from "./service";
+export { BirdNotificationProviderService };
+declare const _default: import("@medusajs/types").ModuleProviderExports;
+export default _default;

package/dist/providers/bird/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BirdNotificationProviderService = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const service_1 = require("./service");
+Object.defineProperty(exports, "BirdNotificationProviderService", { enumerable: true, get: function () { return service_1.BirdNotificationProviderService; } });
+exports.default = (0, utils_1.ModuleProvider)(utils_1.Modules.NOTIFICATION, {
+    services: [service_1.BirdNotificationProviderService],
+});

package/dist/providers/bird/service.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderSendNotificationDTO, ProviderSendNotificationResultsDTO } from "@medusajs/framework/types";
+import { AbstractNotificationProviderService } from "@medusajs/framework/utils";
+import type { BirdNotificationProviderOptions } from "../../types";
+export declare class BirdNotificationProviderService extends AbstractNotificationProviderService {
+    static identifier: string;
+    protected readonly options: BirdNotificationProviderOptions;
+    protected readonly origin: string;
+    static validateOptions(options: BirdNotificationProviderOptions): void;
+    constructor(_container: Record<string, unknown>, options: BirdNotificationProviderOptions);
+    send(notification: ProviderSendNotificationDTO): Promise<ProviderSendNotificationResultsDTO>;
+}

package/dist/providers/bird/service.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BirdNotificationProviderService = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const message_1 = require("../../message");
+class BirdNotificationProviderService extends utils_1.AbstractNotificationProviderService {
+    static identifier = "bird";
+    options;
+    origin;
+    static validateOptions(options) {
+        (0, message_1.validateOptions)(options);
+    }
+    constructor(_container, options) {
+        super();
+        (0, message_1.validateOptions)(options);
+        this.options = { ...options, channels: [...options.channels] };
+        this.origin = (0, message_1.regionalOrigin)(options.api_key);
+    }
+    async send(notification) {
+        const { method, path, body, idempotencyKey } = (0, message_1.prepareMessage)(notification, this.options);
+        const headers = {
+            Authorization: `Bearer ${this.options.api_key}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        if (idempotencyKey)
+            headers["Idempotency-Key"] = idempotencyKey;
+        let serialized;
+        try {
+            serialized = JSON.stringify(body);
+        }
+        catch {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Notification content and parameters must be JSON-serializable.");
+        }
+        let response;
+        let result;
+        try {
+            response = await fetch(`${this.origin}${path}`, {
+                method,
+                headers,
+                body: serialized,
+                redirect: "error",
+                signal: AbortSignal.timeout(30_000),
+            });
+            result = await response.json().catch(() => undefined);
+        }
+        catch {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "Bird could not confirm acceptance of the notification. Check connectivity and Bird message history before retrying; reuse provider_data.idempotency_key when supplied.");
+        }
+        const data = result && typeof result === "object"
+            ? result
+            : {};
+        if (!response.ok) {
+            const error = data.error && typeof data.error === "object"
+                ? data.error
+                : {};
+            const details = [formatErrorDetail(error), error.remediation].filter((value) => typeof value === "string" && value.length > 0);
+            if (Array.isArray(error.details)) {
+                for (const detail of error.details) {
+                    if (detail && typeof detail === "object") {
+                        const description = formatErrorDetail(detail);
+                        if (description)
+                            details.push(description);
+                    }
+                }
+            }
+            const message = details.length
+                ? details.join(" ")
+                : "Check the API key, its channel permissions, and your Bird sender configuration.";
+            const safe = message
+                .replaceAll(this.options.api_key, "[redacted]")
+                .replace(/\b(?:bk|bt)_[a-z]{2}\d+_[A-Za-z0-9_-]+/g, "[redacted]")
+                .slice(0, 2000);
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, `Bird rejected the notification (HTTP ${response.status}): ${safe}`);
+        }
+        if (typeof data.id !== "string" || !data.id.length) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "Bird returned no message ID. Check Bird message history before retrying; acceptance could not be confirmed.");
+        }
+        return { id: data.id };
+    }
+}
+exports.BirdNotificationProviderService = BirdNotificationProviderService;
+function formatErrorDetail(error) {
+    const message = typeof error.message === "string" ? error.message : "";
+    const param = typeof error.param === "string" ? error.param : "";
+    return [param, message].filter(Boolean).join(": ") || undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+import type { birdOperations, EmailMessageRequest, SmsMessageRequest } from "./generated/operations.gen";
+export type BirdNotificationProviderOptions = {
+    api_key: string;
+    channels: (keyof typeof birdOperations)[];
+    email_from?: string;
+    sms_from?: string;
+    whatsapp_from?: string;
+};
+export type BirdNotificationProviderData = {
+    language?: string;
+    category?: EmailMessageRequest["category"] | SmsMessageRequest["category"];
+    idempotency_key?: string;
+    preview_url?: boolean;
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string[];
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@messagebird/bird-plugin-medusa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Bird email, SMS, and WhatsApp notifications for Medusa v2.",
+  "license": "MIT",
+  "author": {
+    "name": "Bird",
+    "email": "connectors@bird.com"
+  },
+  "homepage": "https://bird.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/messagebird/bird-plugin-medusa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/messagebird/bird-plugin-medusa/issues"
+  },
+  "keywords": [
+    "medusa-v2",
+    "medusa-plugin-integration",
+    "medusa-plugin-notification",
+    "medusa-provider",
+    "bird",
+    "messagebird",
+    "email",
+    "sms",
+    "whatsapp",
+    "notifications"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./providers/bird": {
+      "types": "./dist/providers/bird/index.d.ts",
+      "default": "./dist/providers/bird/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "whatsapp.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc6",
+    "typecheck": "tsc6 -p tsconfig.typecheck.json",
+    "test": "npm run typecheck && vitest run src",
+    "lint": "eslint src && npm run typecheck",
+    "prepack": "npm run build",
+    "test:integration": "npm run build && node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config jest.integration.config.cjs --runInBand"
+  },
+  "peerDependencies": {
+    "@medusajs/framework": "^2.21.2"
+  },
+  "devDependencies": {
+    "@medusajs/eslint-plugin": "2.21.2",
+    "@medusajs/framework": "2.21.2",
+    "@medusajs/notification": "2.21.2",
+    "@medusajs/notification-local": "2.21.2",
+    "@medusajs/test-utils": "2.21.2",
+    "@testcontainers/postgresql": "11.12.0",
+    "@types/node": "22.20.5",
+    "eslint": "9.39.5",
+    "jest": "29.7.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "5.0.5"
+  }
+}

package/whatsapp.md

@@ -0,0 +1,54 @@
+# WhatsApp notifications
+
+Enable `whatsapp` in the Bird provider's `channels` and give your API key `whatsapp:write`. The provider uses the same regional API host, error handling, and idempotency behavior as email and SMS.
+
+## Send an approved template
+
+Set `template` to a WhatsApp template ID (`wat_…`) or slug. Pass the approved language's components in `data.components`, using Bird's [template component format](https://bird.com/docs/api/reference/create-whatsapp-message). Email and SMS parameter maps do not apply to WhatsApp.
+
+This built-in delivery template selects its own sender. The provider skips `whatsapp_from` for `bird_…` slugs; omit `from` in the notification:
+
+```ts
+await notificationModuleService.createNotifications({
+  to: customer.phone,
+  channel: "whatsapp",
+  template: "bird_delivery_update",
+  data: {
+    components: [
+      {
+        type: "body",
+        parameters: [
+          { type: "text", name: "ref", text: String(order.display_id) },
+          { type: "text", name: "date", text: deliveryDate },
+        ],
+      },
+    ],
+  },
+  idempotency_key: `delivery-update/${order.id}`,
+  provider_data: {
+    language: "en",
+    idempotency_key: `delivery-update/${order.id}`,
+  },
+});
+```
+
+For your workspace's approved templates, set `whatsapp_from` to a connected number belonging to the template's WhatsApp Business Account, or supply `notification.from`. Use the parameter names or positions required by the approved language. Header media, buttons, and carousel parameters stay inside their template components; Bird validates their shape against the template. Omit `data` for a template without parameters. Template categories come from the template; `provider_data.category` is unsupported.
+
+## Send text in an open conversation
+
+Freeform text requires an open 24-hour customer service window for the recipient and sender. Use a connected sender and render the final text in your application:
+
+```ts
+await notificationModuleService.createNotifications({
+  to: customer.phone,
+  from: process.env.BIRD_WHATSAPP_FROM,
+  channel: "whatsapp",
+  template: "delivery-reply",
+  content: { text: `Your tracking link: ${trackingUrl}` },
+  provider_data: { preview_url: true },
+});
+```
+
+Medusa requires a `template` label even when `content` supplies the text. Inline WhatsApp accepts 1–4096 characters in `content.text`; it rejects HTML, subjects, attachments, template `data`, and `provider_data.language`. Link previews are disabled unless `provider_data.preview_url` is `true`.
+
+Bird enforces the service window. A closed window returns an error with instructions to use an approved template. A message accepted just before the window closes can still fail asynchronously. Inspect the Bird message or its webhooks for delivery; Medusa's success status records API acceptance.