@messagebird/n8n-nodes-bird 0.1.1

package/dist/nodes/Bird/transport.js

@@ -0,0 +1,484 @@
+"use strict";
+// The core every operation's route executes through — the analog of the SDK's
+// client.ts. What lives here is the behavior a route table cannot express:
+// region derivation, blank omission, pagination, binary and error handling.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROW_PROPERTY_DEFAULT = exports.ROW_FROM_ITEM = exports.ROW_PROPERTY = exports.ROW_TYPE = void 0;
+exports.baseUrlForKey = baseUrlForKey;
+exports.birdErrorParts = birdErrorParts;
+exports.completeDateTime = completeDateTime;
+exports.compact = compact;
+exports.asNodeError = asNodeError;
+exports.unwrapLocator = unwrapLocator;
+exports.resolveBinary = resolveBinary;
+exports.buildRequest = buildRequest;
+exports.collectPages = collectPages;
+exports.birdRequest = birdRequest;
+const REGION = /^[a-z]{2}[0-9]+$/;
+function baseUrlForKey(key) {
+    const [prefix, region, ...rest] = key.split("_");
+    if (prefix !== "bk" ||
+        !region ||
+        !REGION.test(region) ||
+        rest.join("_") === "") {
+        throw new Error("Bird API key is not in the expected bk_{region}_{token} format. Check the credential.");
+    }
+    return `https://${region}.platform.bird.com`;
+}
+function birdErrorParts(statusCode, body, headers = {}) {
+    const err = (typeof body === "object" && body !== null ? body : {})
+        .error ?? {};
+    const message = err.message ?? `Bird returned an unexpected error (HTTP ${statusCode}).`;
+    const parts = [];
+    if (err.remediation)
+        parts.push(err.remediation);
+    for (const d of err.details ?? []) {
+        if (d.param && d.message)
+            parts.push(`${d.param}: ${d.message}`);
+    }
+    // A rate-limited loop over items is n8n's common failure mode, so the wait
+    // the gateway already announced is worth repeating to the user.
+    if (statusCode === 429) {
+        const reset = headers["retry-after"] ?? headers["ratelimit-reset"];
+        if ((typeof reset === "string" && reset !== "") ||
+            typeof reset === "number") {
+            parts.push(`Retry after ${reset} second(s).`);
+        }
+    }
+    return { message, description: parts.join(" ") };
+}
+// n8n's dateTime picker stores a naive local timestamp, and Bird requires an
+// RFC 3339 offset. The n8n-native reading of a naive value is the workflow's
+// timezone; two zoneOffset passes because the offset itself can shift at a
+// DST boundary near the picked instant.
+const NAIVE_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/;
+function zoneOffset(zone, at) {
+    const name = new Intl.DateTimeFormat("en-US", {
+        timeZone: zone,
+        timeZoneName: "longOffset",
+    })
+        .formatToParts(at)
+        .find((p) => p.type === "timeZoneName")?.value;
+    const m = /^GMT([+-]\d{2}:\d{2})?$/.exec(name ?? "");
+    if (!m)
+        throw new Error(`unresolvable zone ${zone}`);
+    return m[1] ?? "+00:00";
+}
+function completeDateTime(value, zone) {
+    if (!NAIVE_DATETIME.test(value))
+        return value;
+    const base = value.length === 16 ? `${value}:00` : value;
+    try {
+        const guess = zoneOffset(zone, new Date(`${base}Z`));
+        return base + zoneOffset(zone, new Date(base + guess));
+    }
+    catch {
+        return `${base}Z`;
+    }
+}
+// Bird reads an empty filter as one nothing matches, so a blank is omitted
+// rather than sent. 0 and false are real values and stay.
+function compact(values) {
+    const out = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string") {
+            const t = v.trim();
+            if (t === "")
+                continue;
+            out[k] = t;
+            continue;
+        }
+        if (Array.isArray(v)) {
+            const list = v
+                .map((e) => (typeof e === "string" ? e.trim() : e))
+                .filter((e) => e !== undefined && e !== null && e !== "");
+            if (list.length === 0)
+                continue;
+            out[k] = list;
+            continue;
+        }
+        out[k] = v;
+    }
+    return out;
+}
+const n8n_workflow_1 = require("n8n-workflow");
+// A NodeOperationError already names a configuration mistake and the item it
+// happened on; wrapping one would relabel it as something the API said.
+function asNodeError(node, error, itemIndex) {
+    if (error instanceof n8n_workflow_1.NodeApiError || error instanceof n8n_workflow_1.NodeOperationError) {
+        return error;
+    }
+    return new n8n_workflow_1.NodeApiError(node, error, { itemIndex });
+}
+// foldPairs turns the editor's {pairs: [{key, value}]} rows into a map,
+// dropping blank keys; anything else (an expression's own object) passes.
+function foldPairs(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return raw;
+    const pairs = raw.pairs;
+    if (!Array.isArray(pairs))
+        return raw;
+    const out = {};
+    for (const p of pairs) {
+        const { key, value } = (p ?? {});
+        if (typeof key === "string" && key.trim() !== "")
+            out[key.trim()] = value;
+    }
+    return out;
+}
+function foldMembers(members) {
+    const folded = {};
+    for (const [key, value] of Object.entries(members)) {
+        const fv = foldPairs(value);
+        if (typeof fv === "object" &&
+            fv !== null &&
+            Object.keys(fv).length === 0)
+            continue;
+        if (typeof fv === "string" && fv.trim() === "")
+            continue;
+        folded[key] = fv;
+    }
+    return folded;
+}
+// A row of a repeatable fixedCollection folds exactly like a struct, which is
+// what lets a list carry a map member with no descriptor of its own.
+function listRows(raw) {
+    const rows = Array.isArray(raw) ? raw : raw.items;
+    // An untouched fixedCollection stores {}, which is a blank rather than a
+    // mistake; anything else non-array is a value the API would reject.
+    if (rows === undefined)
+        return Object.keys(raw).length === 0 ? [] : undefined;
+    if (!Array.isArray(rows))
+        return undefined;
+    const out = [];
+    for (const row of rows) {
+        if (typeof row !== "object" || row === null) {
+            out.push(row);
+            continue;
+        }
+        const folded = foldMembers(row);
+        if (Object.keys(folded).length > 0)
+            out.push(folded);
+    }
+    return out;
+}
+// unwrapStructured rewrites collection storage into API objects. A string
+// is parsed as JSON and a plain object passes through, so expressions keep
+// working; a field that unwraps to nothing is dropped like any blank.
+function unwrapStructured(node, itemIndex, route, v) {
+    for (const [name, kind] of Object.entries(route.structured)) {
+        let raw = v[name];
+        if (raw === undefined)
+            continue;
+        if (typeof raw === "string") {
+            try {
+                raw = JSON.parse(raw);
+            }
+            catch {
+                throw new n8n_workflow_1.NodeOperationError(node, kind === "list"
+                    ? `${name} is not valid JSON. Provide an array, for example [{"name": "value"}].`
+                    : `${name} is not valid JSON. Provide an object, for example {"key": "value"}.`, { itemIndex });
+            }
+        }
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        if (kind === "list") {
+            const rows = listRows(raw);
+            if (rows === undefined) {
+                throw new n8n_workflow_1.NodeOperationError(node, `${name} must be a list. Provide an array, for example [{"name": "value"}].`, { itemIndex });
+            }
+            if (rows.length === 0)
+                delete v[name];
+            else
+                v[name] = rows;
+            continue;
+        }
+        if (kind === "map") {
+            raw = foldPairs(raw);
+        }
+        else {
+            const group = raw.values;
+            const members = (typeof group === "object" && group !== null ? group : raw);
+            raw = foldMembers(members);
+        }
+        if (typeof raw === "object" &&
+            raw !== null &&
+            Object.keys(raw).length === 0) {
+            delete v[name];
+            continue;
+        }
+        v[name] = raw;
+    }
+}
+// A Resource Locator stores {__rl, mode, value} whichever mode picked it, so
+// the raw id is taken once here rather than at every read site. A bare string
+// passes through: an expression supplying an id resolves to one.
+function unwrapLocator(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        value.__rl === true) {
+        return value.value;
+    }
+    return value;
+}
+// The defaults live here because a row left alone arrives carrying neither —
+// see integrations/AGENTS.md on what n8n stores.
+exports.ROW_TYPE = "attachmentType";
+exports.ROW_PROPERTY = "binaryPropertyName";
+const ROW_CONTENT = "content";
+const ROW_FILENAME = "filename";
+const ROW_CONTENT_TYPE = "content_type";
+// ROW_FROM_ITEM doubles as the selector's default: what a row means when the
+// member is absent has to be what the property declares as its default.
+exports.ROW_FROM_ITEM = "binary";
+exports.ROW_PROPERTY_DEFAULT = "data";
+// The API's `birdContentBudgetBytes`: decimal not binary, over the encoded
+// value, and shared with the html and text bodies counted into the same total.
+const MESSAGE_LIMIT = 20_000_000;
+// Which shape the rows arrived in decides what an absent member means, so it has
+// to survive the read. A JSON string is neither shape; buildRequest parses that.
+function storedRows(raw) {
+    if (Array.isArray(raw))
+        return { rows: raw, fromEditor: false };
+    if (typeof raw === "object" && raw !== null) {
+        const items = raw.items;
+        if (Array.isArray(items))
+            return { rows: items, fromEditor: true };
+    }
+    return { rows: [], fromEditor: false };
+}
+function filled(v) {
+    return typeof v === "string" && v.trim() !== "";
+}
+function megabytes(bytes) {
+    return `${(bytes / 1_000_000).toFixed(1)} MB`;
+}
+// Rows are replaced rather than mutated: getNodeParameter can hand back the same
+// stored object on every item, which would send item one's file with item two.
+async function resolveBinary(ctx, route, values, itemIndex) {
+    let encoded = 0;
+    for (const name of route.binaryFields) {
+        const { rows: stored, fromEditor } = storedRows(values[name]);
+        if (stored.length === 0)
+            continue;
+        const rows = [];
+        for (const source of stored) {
+            if (typeof source !== "object" || source === null) {
+                rows.push(source);
+                continue;
+            }
+            const src = source;
+            const row = { ...src };
+            delete row[exports.ROW_TYPE];
+            delete row[exports.ROW_PROPERTY];
+            // An absent selector means the emitted default only for an editor row — see
+            // integrations/AGENTS.md on what an absent member means per author.
+            const fromItem = filled(src[exports.ROW_TYPE])
+                ? src[exports.ROW_TYPE] === exports.ROW_FROM_ITEM
+                : fromEditor && !filled(src[ROW_CONTENT]);
+            // Blank is the user clearing it, which omits the row; a name the item lacks
+            // is a wrong value instead, and assertBinaryData is left to raise on that.
+            const prop = exports.ROW_PROPERTY in src
+                ? String(src[exports.ROW_PROPERTY] ?? "").trim()
+                : exports.ROW_PROPERTY_DEFAULT;
+            if (fromItem && prop !== "") {
+                const meta = ctx.helpers.assertBinaryData(itemIndex, prop);
+                // Under n8n's filesystem binary mode `data` holds a reference, not the
+                // payload; only the helper resolves both modes.
+                const buffer = await ctx.helpers.getBinaryDataBuffer(itemIndex, prop);
+                row[ROW_CONTENT] = buffer.toString("base64");
+                if (!filled(row[ROW_FILENAME])) {
+                    row[ROW_FILENAME] = filled(meta.fileName)
+                        ? meta.fileName
+                        : meta.fileExtension
+                            ? `${prop}.${meta.fileExtension}`
+                            : prop;
+                }
+                if (!filled(row[ROW_CONTENT_TYPE]) && filled(meta.mimeType)) {
+                    row[ROW_CONTENT_TYPE] = meta.mimeType;
+                }
+            }
+            // Keeps the Input Binary Field promise: without this a cleared row survives
+            // on a stray filename and reaches the API with no bytes, which is a 422.
+            if (fromEditor && fromItem && prop === "")
+                continue;
+            if (typeof row[ROW_CONTENT] === "string")
+                encoded += row[ROW_CONTENT].length;
+            rows.push(row);
+        }
+        values[name] = rows;
+    }
+    // Pointing at a file makes the ceiling easy to cross without noticing, and
+    // the API answers with a 413 about a body the user never assembled.
+    if (encoded > MESSAGE_LIMIT) {
+        throw new n8n_workflow_1.NodeOperationError(ctx.getNode(), `The attachments come to ${megabytes(encoded)} once base64-encoded, over the ${megabytes(MESSAGE_LIMIT)} a message may be. Encoding adds about a third, so the files themselves have to stay under roughly ${megabytes(MESSAGE_LIMIT * 0.75)} — less, since the body counts against the same budget.`, { itemIndex });
+    }
+}
+function buildRequest(node, route, values, zone, itemIndex) {
+    for (const [name, stored] of Object.entries(values)) {
+        values[name] = unwrapLocator(stored);
+    }
+    // Capture explicit nulls on nullable fields before compaction drops them:
+    // on these fields null is the API's clear operation, not a blank.
+    for (const [prop, wire] of Object.entries(route.renames)) {
+        if (prop in values) {
+            values[wire] = values[prop];
+            delete values[prop];
+        }
+    }
+    const cleared = route.nullableFields.filter((n) => values[n] === null);
+    const v = compact(values);
+    unwrapStructured(node, itemIndex, route, v);
+    for (const n of cleared)
+        v[n] = null;
+    // A dotted name (template.components, labels.add) is a member inside an
+    // already-unwrapped struct.
+    const locate = (name) => {
+        const [head, member] = name.split(".");
+        if (member === undefined)
+            return [v, head];
+        return [v[head], member];
+    };
+    for (const name of route.jsonFields) {
+        const [holder, key] = locate(name);
+        const raw = holder?.[key];
+        if (!holder || typeof raw !== "string")
+            continue;
+        try {
+            holder[key] = JSON.parse(raw);
+        }
+        catch {
+            throw new n8n_workflow_1.NodeOperationError(node, `${name} is not valid JSON. Provide an object, for example {"key": "value"}.`, { itemIndex });
+        }
+    }
+    for (const name of route.arrayFields) {
+        const [holder, key] = locate(name);
+        const raw = holder?.[key];
+        if (!holder || typeof raw !== "string")
+            continue;
+        const list = raw
+            .split(",")
+            .map((e) => e.trim())
+            .filter((e) => e !== "");
+        if (list.length === 0)
+            delete holder[key];
+        else
+            holder[key] = list;
+    }
+    if (zone) {
+        for (const name of route.dateTimeFields) {
+            const [holder, key] = locate(name);
+            const raw = holder?.[key];
+            if (holder && typeof raw === "string")
+                holder[key] = completeDateTime(raw, zone);
+        }
+    }
+    if (route.rawBodyField !== "") {
+        const raw = v[route.rawBodyField];
+        let parsed = raw;
+        if (typeof raw === "string") {
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new n8n_workflow_1.NodeOperationError(node, `${route.rawBodyField} is not valid JSON. Provide a JSON array.`, { itemIndex });
+            }
+        }
+        if (!Array.isArray(parsed)) {
+            throw new n8n_workflow_1.NodeOperationError(node, `${route.rawBodyField} must be a JSON array, as the API reference documents.`, { itemIndex });
+        }
+        let path = route.path;
+        for (const p of route.pathParams) {
+            const val = v[p];
+            if (val === undefined) {
+                throw new n8n_workflow_1.NodeOperationError(node, `${p} is required and cannot be blank.`, { itemIndex });
+            }
+            path = path.replace(`{${p}}`, encodeURIComponent(String(val)));
+        }
+        const pick = (keys) => Object.fromEntries(keys.filter((k) => k in v).map((k) => [k, v[k]]));
+        return {
+            path,
+            qs: pick(route.query),
+            body: parsed,
+        };
+    }
+    let path = route.path;
+    for (const p of route.pathParams) {
+        const val = v[p];
+        if (val === undefined) {
+            throw new n8n_workflow_1.NodeOperationError(node, `${p} is required and cannot be blank.`, { itemIndex });
+        }
+        path = path.replace(`{${p}}`, encodeURIComponent(String(val)));
+    }
+    requireTopLevel(node, route, v, itemIndex);
+    const pick = (keys) => Object.fromEntries(keys.filter((k) => k in v).map((k) => [k, v[k]]));
+    return { path, qs: pick(route.query), body: pick(route.body) };
+}
+// n8n's own canvas check misses an empty required multiOptions field, so this
+// names it at execution instead — docs/roadmap/n8n.md carries why.
+function requireTopLevel(node, route, values, itemIndex) {
+    for (const name of route.topLevel) {
+        // topLevel names the property; the value is under its wire name by now.
+        const wire = route.renames[name] ?? name;
+        if (route.pathParams.includes(wire))
+            continue;
+        if (values[wire] === undefined) {
+            throw new n8n_workflow_1.NodeOperationError(node, `${name} is required and cannot be empty.`, { itemIndex });
+        }
+    }
+}
+async function collectPages(fetchPage, returnAll, limit) {
+    const out = [];
+    let cursor;
+    do {
+        const page = await fetchPage(cursor);
+        out.push(...(page.data ?? []));
+        cursor = page.next_cursor;
+    } while (cursor && (returnAll || out.length < limit));
+    return returnAll ? out : out.slice(0, limit);
+}
+async function birdRequest(ctx, opts) {
+    const creds = await ctx.getCredentials("birdApi");
+    let baseUrl;
+    try {
+        baseUrl = baseUrlForKey(String(creds.apiKey ?? ""));
+    }
+    catch (e) {
+        throw new n8n_workflow_1.NodeOperationError(ctx.getNode(), e.message, {
+            itemIndex: opts.itemIndex,
+        });
+    }
+    // ignoreHttpStatusErrors is what lets Bird's error body survive into
+    // birdErrorParts instead of being swallowed by the helper's own throw.
+    const res = await ctx.helpers.httpRequestWithAuthentication.call(ctx, "birdApi", {
+        method: opts.method,
+        url: baseUrl + opts.path,
+        headers: opts.headers && Object.keys(opts.headers).length > 0
+            ? opts.headers
+            : undefined,
+        qs: opts.qs && Object.keys(opts.qs).length > 0
+            ? opts.qs
+            : undefined,
+        body: opts.body && Object.keys(opts.body).length > 0
+            ? opts.body
+            : undefined,
+        json: true,
+        returnFullResponse: true,
+        ignoreHttpStatusErrors: true,
+    });
+    const statusCode = res.statusCode;
+    const body = res.body;
+    if (statusCode >= 400) {
+        const headers = res.headers ?? {};
+        const { message, description } = birdErrorParts(statusCode, body, headers);
+        throw new n8n_workflow_1.NodeApiError(ctx.getNode(), (body ?? {}), {
+            message,
+            description,
+            httpCode: String(statusCode),
+            itemIndex: opts.itemIndex,
+        });
+    }
+    return (body ?? {});
+}

package/dist/nodes/Bird/webhook-verify.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyStandardWebhook = verifyStandardWebhook;
+// Standard Webhooks verification (https://www.standardwebhooks.com): Bird
+// signs {webhook-id}.{webhook-timestamp}.{raw body} with HMAC-SHA256, keyed
+// by the base64 bytes behind the secret's whsec_ prefix. Hand-rolled because
+// verified community nodes cannot carry runtime dependencies.
+const node_crypto_1 = require("node:crypto");
+const TOLERANCE_SECONDS = 300;
+function verifyStandardWebhook(secret, webhookId, webhookTimestamp, rawBody, signatureHeader, nowSeconds = Math.floor(Date.now() / 1000)) {
+    if (!secret || !webhookId || !signatureHeader)
+        return false;
+    const ts = Number(webhookTimestamp);
+    if (!Number.isFinite(ts))
+        return false;
+    if (Math.abs(nowSeconds - ts) > TOLERANCE_SECONDS)
+        return false;
+    let key;
+    try {
+        key = Buffer.from(secret.startsWith("whsec_") ? secret.slice(6) : secret, "base64");
+    }
+    catch {
+        return false;
+    }
+    if (key.length === 0)
+        return false;
+    const expected = (0, node_crypto_1.createHmac)("sha256", key)
+        .update(`${webhookId}.${webhookTimestamp}.${rawBody}`)
+        .digest();
+    for (const part of signatureHeader.split(" ")) {
+        const [version, sig] = part.split(",");
+        if (version !== "v1" || !sig)
+            continue;
+        let candidate;
+        try {
+            candidate = Buffer.from(sig, "base64");
+        }
+        catch {
+            continue;
+        }
+        if (candidate.length === expected.length &&
+            (0, node_crypto_1.timingSafeEqual)(candidate, expected))
+            return true;
+    }
+    return false;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@messagebird/n8n-nodes-bird",
+  "version": "0.1.1",
+  "description": "The official Bird node for n8n: email, SMS, WhatsApp, and verification, plus a webhook trigger for Bird events.",
+  "license": "MIT",
+  "author": {
+    "name": "Bird",
+    "email": "connectors@bird.com"
+  },
+  "keywords": [
+    "n8n-community-node-package",
+    "bird",
+    "messagebird",
+    "email",
+    "transactional email",
+    "sms",
+    "whatsapp",
+    "voice",
+    "verify",
+    "otp",
+    "lookup",
+    "webhooks"
+  ],
+  "homepage": "https://bird.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/messagebird/n8n-nodes-bird.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/BirdApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/Bird/Bird.node.js",
+      "dist/nodes/Bird/BirdTrigger.node.js"
+    ]
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc6 && cp nodes/Bird/bird.svg nodes/Bird/bird-dark.svg nodes/Bird/Bird.node.json nodes/Bird/BirdTrigger.node.json dist/nodes/Bird/ && cp credentials/bird.svg credentials/bird-dark.svg dist/credentials/",
+    "test": "vitest run",
+    "typecheck": "tsc6 --noEmit",
+    "lint": "node scan.mjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "@n8n/scan-community-package": "0.33.0",
+    "@types/node": "22.19.18",
+    "n8n-workflow": "2.16.0",
+    "rimraf": "6.1.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "4.1.10"
+  }
+}