Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,27 @@
{
"name": "@toolctrl/marketing-outbound",
"version": "0.0.0",
"private": true,
"type": "module",
"sideEffects": false,
"exports": {
".": "./src/index.ts",
"./adapters/slack": "./src/adapters/slack.ts",
"./adapters/discord": "./src/adapters/discord.ts",
"./adapters/mailchimp": "./src/adapters/mailchimp.ts",
"./adapters/hubspot": "./src/adapters/hubspot.ts",
"./adapters/brevo": "./src/adapters/brevo.ts",
"./adapters/custom-webhook": "./src/adapters/custom-webhook.ts"
},
"scripts": {
"build": "pnpm run typecheck",
"test": "vitest run src",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {},
"devDependencies": {
"@types/node": "^25.0.0",
"typescript": "^5.3.2",
"vitest": "^3.2.4"
}
}
@@ -0,0 +1,253 @@
import { describe, expect, it, vi } from "vitest";
import { slackAdapter, buildSlackBlocks } from "./slack.js";
import { discordAdapter, buildDiscordEmbed } from "./discord.js";
import { mailchimpAdapter, buildMailchimpPayload } from "./mailchimp.js";
import { hubspotAdapter, buildHubSpotPayload } from "./hubspot.js";
import { brevoAdapter, buildBrevoPayload } from "./brevo.js";
import { customWebhookAdapter, buildCustomPayload } from "./custom-webhook.js";
import { adapterRegistry, isOutboundUrlAllowed, maskEmailIfRequested } from "../index.js";
import type { MarketingLeadPayload } from "../types.js";
const PAYLOAD: MarketingLeadPayload = {
leadId: "lead_1",
email: "patrick@example.com",
firstName: "Patrick",
lastName: "Doe",
company: "Acme",
source: "landing-pro",
utm: { source: "google", medium: "cpc", campaign: "q2-launch" },
referrer: "https://google.com",
landingPage: "/pricing",
tenantId: "tenant_1",
targetStatus: "trial",
conversionPath: "self-service",
planId: "plan_pro",
occurredAt: "2026-05-17T00:00:00Z",
};
function mockFetch(status = 200): typeof fetch {
return vi.fn().mockResolvedValue(new Response("ok", { status })) as unknown as typeof fetch;
}
describe("registry + URL guard", () => {
it("exposes 6 adapters", () => {
expect(Object.keys(adapterRegistry).sort()).toEqual([
"brevo",
"discord",
"hubspot",
"mailchimp",
"slack",
"webhook",
]);
});
it("isOutboundUrlAllowed rejects HTTP, localhost, RFC1918, metadata", () => {
expect(isOutboundUrlAllowed("https://hooks.slack.com/x")).toBe(true);
expect(isOutboundUrlAllowed("http://hooks.slack.com/x")).toBe(false);
expect(isOutboundUrlAllowed("https://localhost/x")).toBe(false);
expect(isOutboundUrlAllowed("https://127.0.0.1/x")).toBe(false);
expect(isOutboundUrlAllowed("https://10.0.0.1/x")).toBe(false);
expect(isOutboundUrlAllowed("https://192.168.1.1/x")).toBe(false);
expect(isOutboundUrlAllowed("https://172.16.0.1/x")).toBe(false);
expect(isOutboundUrlAllowed("https://metadata.google.internal/x")).toBe(false);
expect(isOutboundUrlAllowed("https://service.internal/x")).toBe(false);
expect(isOutboundUrlAllowed("not-a-url")).toBe(false);
});
it("maskEmailIfRequested masks local part when enabled", () => {
expect(maskEmailIfRequested("foo@bar.com", { maskPii: { email: true } })).toBe("***@bar.com");
expect(maskEmailIfRequested("foo@bar.com", {})).toBe("foo@bar.com");
expect(maskEmailIfRequested(null, { maskPii: { email: true } })).toBeNull();
});
});
describe("slack adapter", () => {
it("builds Block-Kit payload with name + email + UTM fields", () => {
const body = buildSlackBlocks("marketing.lead.captured", PAYLOAD, {}) as Record<string, unknown>;
expect(typeof body.text).toBe("string");
expect((body.text as string)).toMatch(/Patrick Doe/);
expect((body.text as string)).toMatch(/patrick@example.com/);
});
it("sends POST and returns ok on 2xx", async () => {
const fetchImpl = mockFetch(200);
const res = await slackAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: slackAdapter.parseConfig({ webhookUrl: "https://hooks.slack.com/services/X/Y/Z" }),
ctx: { fetch: fetchImpl },
});
expect(res.ok).toBe(true);
expect(fetchImpl).toHaveBeenCalledOnce();
});
it("returns ssrf rejection for http URL", async () => {
const fetchImpl = mockFetch();
const res = await slackAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: slackAdapter.parseConfig({ webhookUrl: "http://hooks.slack.com/x" }),
ctx: { fetch: fetchImpl },
});
expect(res.ok).toBe(false);
expect(res.errorTag).toBe("url_rejected_ssrf");
expect(fetchImpl).not.toHaveBeenCalled();
});
it("config error on missing webhookUrl", () => {
expect(() => slackAdapter.parseConfig({})).toThrow();
});
it("maps 5xx to upstream_5xx, 4xx to upstream_4xx", async () => {
const fetch5 = mockFetch(500);
const r5 = await slackAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: { webhookUrl: "https://hooks.slack.com/x" },
ctx: { fetch: fetch5 },
});
expect(r5.errorTag).toBe("upstream_5xx");
const fetch4 = mockFetch(404);
const r4 = await slackAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: { webhookUrl: "https://hooks.slack.com/x" },
ctx: { fetch: fetch4 },
});
expect(r4.errorTag).toBe("upstream_4xx");
});
});
describe("discord adapter", () => {
it("builds embed with color + fields", () => {
const body = buildDiscordEmbed("marketing.lead.convertedtotrial", PAYLOAD, {}) as { embeds: any[] };
expect(body.embeds[0].color).toBe(0xf59e0b);
expect(body.embeds[0].fields.length).toBeGreaterThan(2);
});
it("sends to webhook URL", async () => {
const fetchImpl = mockFetch(200);
const res = await discordAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: discordAdapter.parseConfig({ webhookUrl: "https://discord.com/api/webhooks/x/y" }),
ctx: { fetch: fetchImpl },
});
expect(res.ok).toBe(true);
});
});
describe("mailchimp adapter", () => {
it("builds list-member upsert URL with md5 email hash", () => {
const built = buildMailchimpPayload(PAYLOAD, { apiKey: "abc-us12", listId: "abc123" });
expect(built.url).toMatch(/us12\.api\.mailchimp\.com/);
expect(built.url).toMatch(/lists\/abc123\/members\/[a-f0-9]{32}/);
expect(built.body.email_address).toBe("patrick@example.com");
expect((built.body.merge_fields as any).FNAME).toBe("Patrick");
});
it("rejects API key without DC suffix", () => {
expect(() => buildMailchimpPayload(PAYLOAD, { apiKey: "no-dc", listId: "x" })).not.toThrow();
expect(() => buildMailchimpPayload(PAYLOAD, { apiKey: "nodc", listId: "x" })).toThrow();
});
it("sends PUT with basic auth", async () => {
const fetchImpl = mockFetch(200);
const res = await mailchimpAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: mailchimpAdapter.parseConfig({ apiKey: "abc-us12", listId: "abc123" }),
ctx: { fetch: fetchImpl },
});
expect(res.ok).toBe(true);
const [, init] = (fetchImpl as any).mock.calls[0];
expect(init.method).toBe("PUT");
expect(init.headers.authorization).toMatch(/^Basic /);
});
});
describe("hubspot adapter", () => {
it("builds CRM v3 contacts URL + properties", () => {
const built = buildHubSpotPayload(PAYLOAD);
expect(built.url).toBe("https://api.hubapi.com/crm/v3/objects/contacts");
expect((built.body.properties as any).email).toBe("patrick@example.com");
expect((built.body.properties as any).utm_campaign).toBe("q2-launch");
});
it("treats 409 conflict as success", async () => {
const fetchImpl = mockFetch(409);
const res = await hubspotAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: { accessToken: "tok" },
ctx: { fetch: fetchImpl },
});
expect(res.ok).toBe(true);
expect(res.status).toBe(409);
});
});
describe("brevo adapter", () => {
it("builds contact POST with attributes + optional listIds", () => {
const built = buildBrevoPayload(PAYLOAD, { apiKey: "x", listIds: [1, 2] });
expect(built.url).toBe("https://api.brevo.com/v3/contacts");
expect(built.body.listIds).toEqual([1, 2]);
expect((built.body.attributes as any).FIRSTNAME).toBe("Patrick");
});
it("sends with api-key header", async () => {
const fetchImpl = mockFetch(201);
const res = await brevoAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: { apiKey: "tok" },
ctx: { fetch: fetchImpl },
});
expect(res.ok).toBe(true);
const [, init] = (fetchImpl as any).mock.calls[0];
expect(init.headers["api-key"]).toBe("tok");
});
});
describe("custom-webhook adapter", () => {
it("builds canonical envelope with conversion when tenantId present", () => {
const env = buildCustomPayload("marketing.lead.convertedtotrial", PAYLOAD, {});
expect((env as any).eventType).toBe("marketing.lead.convertedtotrial");
expect((env as any).conversion.tenantId).toBe("tenant_1");
});
it("omits conversion when no tenantId", () => {
const env = buildCustomPayload("marketing.lead.captured", { ...PAYLOAD, tenantId: null }, {});
expect((env as any).conversion).toBeNull();
});
it("adds X-Marketing-Signature header when signingSecret configured", async () => {
const fetchImpl = mockFetch(200);
await customWebhookAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: { url: "https://example.com/hook", signingSecret: "topsecret", headers: {} },
ctx: { fetch: fetchImpl },
});
const [, init] = (fetchImpl as any).mock.calls[0];
expect(init.headers["x-marketing-signature"]).toMatch(/^sha256=[a-f0-9]+$/);
});
it("forwards configured extra headers", async () => {
const fetchImpl = mockFetch(200);
await customWebhookAdapter.send({
eventType: "marketing.lead.captured",
payload: PAYLOAD,
config: { url: "https://example.com/hook", headers: { "x-tenant": "t1" } },
ctx: { fetch: fetchImpl },
});
const [, init] = (fetchImpl as any).mock.calls[0];
expect(init.headers["x-tenant"]).toBe("t1");
});
it("masks email when ctx.maskPii.email is set", () => {
const env = buildCustomPayload("marketing.lead.captured", PAYLOAD, { maskPii: { email: true } });
expect((env as any).lead.email).toBe("***@example.com");
});
});
@@ -0,0 +1,68 @@
/**
* Brevo (formerly Sendinblue) contact-add adapter (Phase 05 #79).
* Adds the lead as a contact, optionally to one or more lists. Auth
* header is `api-key: <apiKey>`.
*/
import {
adapterFetch,
MarketingAdapterConfigError,
type AdapterResult,
type MarketingLeadPayload,
type MarketingOutboundAdapter,
} from "../types.js";
export interface BrevoConfig {
apiKey: string;
/** Optional Brevo list-IDs (numeric). */
listIds?: number[];
}
export function buildBrevoPayload(payload: MarketingLeadPayload, config: BrevoConfig): { url: string; body: Record<string, unknown> } {
const body: Record<string, unknown> = {
email: payload.email.trim().toLowerCase(),
updateEnabled: true,
attributes: {} as Record<string, string>,
};
const attrs = body.attributes as Record<string, string>;
if (payload.firstName) attrs.FIRSTNAME = payload.firstName;
if (payload.lastName) attrs.LASTNAME = payload.lastName;
if (payload.company) attrs.COMPANY = payload.company;
if (payload.utm?.source) attrs.UTM_SOURCE = payload.utm.source;
if (payload.utm?.campaign) attrs.UTM_CAMPAIGN = payload.utm.campaign;
if (config.listIds && config.listIds.length > 0) {
body.listIds = config.listIds;
}
return { url: "https://api.brevo.com/v3/contacts", body };
}
export const brevoAdapter: MarketingOutboundAdapter<BrevoConfig> = {
type: "brevo",
parseConfig(config: unknown): BrevoConfig {
if (!config || typeof config !== "object") {
throw new MarketingAdapterConfigError("brevo config must be an object");
}
const c = config as Record<string, unknown>;
if (typeof c.apiKey !== "string" || c.apiKey.length === 0) {
throw new MarketingAdapterConfigError("brevo config requires apiKey");
}
const listIdsRaw = Array.isArray(c.listIds) ? (c.listIds as unknown[]) : [];
const listIds = listIdsRaw.filter((v): v is number => typeof v === "number" && Number.isFinite(v));
return { apiKey: c.apiKey, listIds: listIds.length > 0 ? listIds : undefined };
},
async send({ payload, config, ctx }): Promise<AdapterResult> {
const built = buildBrevoPayload(payload, config);
return adapterFetch(
built.url,
{
method: "POST",
headers: {
"content-type": "application/json",
"api-key": config.apiKey,
},
body: JSON.stringify(built.body),
},
ctx
);
},
};
@@ -0,0 +1,95 @@
/**
* Custom webhook adapter — POSTs the canonical {@link MarketingLeadPayload}
* envelope as JSON to an operator-controlled HTTPS URL. Optional shared
* secret is sent as `X-Marketing-Signature: sha256=<hex(hmac(body))>` so
* the receiver can verify authenticity.
*/
import { createHmac } from "node:crypto";
import {
adapterFetch,
maskEmailIfRequested,
MarketingAdapterConfigError,
type AdapterContext,
type AdapterResult,
type MarketingLeadEventType,
type MarketingLeadPayload,
type MarketingOutboundAdapter,
} from "../types.js";
export interface CustomWebhookConfig {
url: string;
/** Optional HMAC-SHA256 shared secret. */
signingSecret?: string;
/** Extra headers (e.g. tenant-id, X-Source). */
headers?: Record<string, string>;
}
export function buildCustomPayload(
eventType: MarketingLeadEventType,
payload: MarketingLeadPayload,
ctx: AdapterContext
): Record<string, unknown> {
return {
schema: "marketing.lead.v1",
eventType,
occurredAt: payload.occurredAt ?? new Date().toISOString(),
lead: {
id: payload.leadId,
email: maskEmailIfRequested(payload.email, ctx),
firstName: payload.firstName ?? null,
lastName: payload.lastName ?? null,
company: payload.company ?? null,
source: payload.source ?? null,
utm: payload.utm ?? {},
referrer: payload.referrer ?? null,
landingPage: payload.landingPage ?? null,
},
conversion:
payload.tenantId
? {
tenantId: payload.tenantId,
targetStatus: payload.targetStatus ?? null,
conversionPath: payload.conversionPath ?? null,
planId: payload.planId ?? null,
}
: null,
};
}
export const customWebhookAdapter: MarketingOutboundAdapter<CustomWebhookConfig> = {
type: "webhook",
parseConfig(config: unknown): CustomWebhookConfig {
if (!config || typeof config !== "object") {
throw new MarketingAdapterConfigError("webhook config must be an object");
}
const c = config as Record<string, unknown>;
if (typeof c.url !== "string" || c.url.length === 0) {
throw new MarketingAdapterConfigError("webhook config requires url");
}
const headers: Record<string, string> = {};
if (c.headers && typeof c.headers === "object" && !Array.isArray(c.headers)) {
for (const [k, v] of Object.entries(c.headers as Record<string, unknown>)) {
if (typeof v === "string") headers[k] = v;
}
}
return {
url: c.url,
signingSecret: typeof c.signingSecret === "string" ? c.signingSecret : undefined,
headers,
};
},
async send({ eventType, payload, config, ctx }): Promise<AdapterResult> {
const envelope = buildCustomPayload(eventType, payload, ctx);
const bodyText = JSON.stringify(envelope);
const headers: Record<string, string> = {
"content-type": "application/json",
...(config.headers ?? {}),
};
if (config.signingSecret) {
const sig = createHmac("sha256", config.signingSecret).update(bodyText).digest("hex");
headers["x-marketing-signature"] = `sha256=${sig}`;
}
return adapterFetch(config.url, { method: "POST", headers, body: bodyText }, ctx);
},
};
@@ -0,0 +1,113 @@
/**
* Discord incoming-webhook adapter (Phase 05 #79). Posts an embed
* describing the lead event to a Discord channel.
*/
import {
adapterFetch,
formatLeadName,
maskEmailIfRequested,
MarketingAdapterConfigError,
type AdapterContext,
type AdapterResult,
type MarketingLeadEventType,
type MarketingLeadPayload,
type MarketingOutboundAdapter,
} from "../types.js";
export interface DiscordConfig {
webhookUrl: string;
username?: string;
}
function embedColor(eventType: MarketingLeadEventType): number {
switch (eventType) {
case "marketing.lead.captured":
return 0x3b82f6;
case "marketing.lead.qualified":
return 0x8b5cf6;
case "marketing.lead.convertedtotrial":
return 0xf59e0b;
case "marketing.lead.convertedtocustomer":
return 0x10b981;
default:
return 0x6b7280;
}
}
function eventTitle(eventType: MarketingLeadEventType): string {
switch (eventType) {
case "marketing.lead.captured":
return "New Lead";
case "marketing.lead.qualified":
return "Lead Qualified";
case "marketing.lead.convertedtotrial":
return "Converted to Trial";
case "marketing.lead.convertedtocustomer":
return "Converted to Customer";
default:
return "Lead event";
}
}
export function buildDiscordEmbed(
eventType: MarketingLeadEventType,
payload: MarketingLeadPayload,
ctx: AdapterContext
): unknown {
const name = formatLeadName(payload);
const email = maskEmailIfRequested(payload.email, ctx) ?? "(unknown)";
const fields: Array<{ name: string; value: string; inline?: boolean }> = [
{ name: "Email", value: email, inline: true },
];
if (payload.company) fields.push({ name: "Company", value: payload.company, inline: true });
if (payload.source) fields.push({ name: "Source", value: payload.source, inline: true });
if (payload.utm?.campaign) fields.push({ name: "Campaign", value: payload.utm.campaign, inline: true });
if (payload.utm?.source) fields.push({ name: "UTM Source", value: payload.utm.source, inline: true });
if (payload.conversionPath) fields.push({ name: "Path", value: payload.conversionPath, inline: true });
if (payload.planId) fields.push({ name: "Plan", value: payload.planId, inline: true });
return {
embeds: [
{
title: eventTitle(eventType),
description: name,
color: embedColor(eventType),
timestamp: payload.occurredAt ?? new Date().toISOString(),
fields,
},
],
};
}
export const discordAdapter: MarketingOutboundAdapter<DiscordConfig> = {
type: "discord",
parseConfig(config: unknown): DiscordConfig {
if (!config || typeof config !== "object") {
throw new MarketingAdapterConfigError("discord config must be an object");
}
const c = config as Record<string, unknown>;
if (typeof c.webhookUrl !== "string" || c.webhookUrl.length === 0) {
throw new MarketingAdapterConfigError("discord config requires webhookUrl");
}
return {
webhookUrl: c.webhookUrl,
username: typeof c.username === "string" ? c.username : undefined,
};
},
async send({ eventType, payload, config, ctx }): Promise<AdapterResult> {
const body = buildDiscordEmbed(eventType, payload, ctx);
const final = {
...(body as object),
...(config.username ? { username: config.username } : {}),
};
return adapterFetch(
config.webhookUrl,
{
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(final),
},
ctx
);
},
};
@@ -0,0 +1,70 @@
/**
* HubSpot contact-create / update adapter (Phase 05 #79).
* Uses Hubspot CRM v3 contacts API + private-app token auth.
*/
import {
adapterFetch,
MarketingAdapterConfigError,
type AdapterResult,
type MarketingLeadPayload,
type MarketingOutboundAdapter,
} from "../types.js";
export interface HubSpotConfig {
/** HubSpot private-app token (Bearer). */
accessToken: string;
}
export function buildHubSpotPayload(payload: MarketingLeadPayload): { url: string; body: Record<string, unknown> } {
const properties: Record<string, string> = {
email: payload.email.trim().toLowerCase(),
};
if (payload.firstName) properties.firstname = payload.firstName;
if (payload.lastName) properties.lastname = payload.lastName;
if (payload.company) properties.company = payload.company;
if (payload.utm?.source) properties.utm_source = payload.utm.source;
if (payload.utm?.medium) properties.utm_medium = payload.utm.medium;
if (payload.utm?.campaign) properties.utm_campaign = payload.utm.campaign;
// Use the v3 contacts create endpoint; HubSpot returns 409 on conflict
// which is a recoverable "already exists" — the worker handler treats
// 409 as a successful no-op.
return {
url: "https://api.hubapi.com/crm/v3/objects/contacts",
body: { properties },
};
}
export const hubspotAdapter: MarketingOutboundAdapter<HubSpotConfig> = {
type: "hubspot",
parseConfig(config: unknown): HubSpotConfig {
if (!config || typeof config !== "object") {
throw new MarketingAdapterConfigError("hubspot config must be an object");
}
const c = config as Record<string, unknown>;
if (typeof c.accessToken !== "string" || c.accessToken.length === 0) {
throw new MarketingAdapterConfigError("hubspot config requires accessToken");
}
return { accessToken: c.accessToken };
},
async send({ payload, config, ctx }): Promise<AdapterResult> {
const built = buildHubSpotPayload(payload);
const res = await adapterFetch(
built.url,
{
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${config.accessToken}`,
},
body: JSON.stringify(built.body),
},
ctx
);
if (!res.ok && res.status === 409) {
// Idempotent — contact already exists.
return { ok: true, status: 409 };
}
return res;
},
};
@@ -0,0 +1,101 @@
/**
* Mailchimp list-subscribe adapter (Phase 05 #79).
*
* Adds the lead as a `subscribed` (or `pending` if you flip the toggle)
* contact to the configured audience. Auth is `Authorization: Basic
* <base64(any:apiKey)>` per Mailchimp's documented scheme. The DC suffix
* is parsed from the API key (`us12-…` → `us12.api.mailchimp.com`).
*
* Idempotent by Mailchimp's email-hash semantics — we PUT to
* `/lists/{listId}/members/{md5(lowercase-email)}` which upserts.
*/
import { createHash } from "node:crypto";
import {
adapterFetch,
MarketingAdapterConfigError,
type AdapterResult,
type MarketingLeadPayload,
type MarketingOutboundAdapter,
} from "../types.js";
export interface MailchimpConfig {
apiKey: string;
listId: string;
/** `subscribed` (default) | `pending` */
status?: "subscribed" | "pending";
/** Optional tags applied to the contact. */
tags?: string[];
}
function dcFromApiKey(apiKey: string): string {
const idx = apiKey.lastIndexOf("-");
if (idx <= 0) throw new MarketingAdapterConfigError("Mailchimp API key missing DC suffix");
return apiKey.slice(idx + 1);
}
export function buildMailchimpPayload(
payload: MarketingLeadPayload,
config: MailchimpConfig
): { url: string; body: Record<string, unknown>; emailHash: string } {
const lower = payload.email.trim().toLowerCase();
const emailHash = createHash("md5").update(lower).digest("hex");
const dc = dcFromApiKey(config.apiKey);
const url = `https://${dc}.api.mailchimp.com/3.0/lists/${encodeURIComponent(config.listId)}/members/${emailHash}`;
const merge_fields: Record<string, string> = {};
if (payload.firstName) merge_fields.FNAME = payload.firstName;
if (payload.lastName) merge_fields.LNAME = payload.lastName;
if (payload.company) merge_fields.COMPANY = payload.company;
const body: Record<string, unknown> = {
email_address: lower,
status_if_new: config.status ?? "subscribed",
merge_fields,
};
if (config.tags && config.tags.length > 0) {
body.tags = config.tags;
}
return { url, body, emailHash };
}
export const mailchimpAdapter: MarketingOutboundAdapter<MailchimpConfig> = {
type: "mailchimp",
parseConfig(config: unknown): MailchimpConfig {
if (!config || typeof config !== "object") {
throw new MarketingAdapterConfigError("mailchimp config must be an object");
}
const c = config as Record<string, unknown>;
if (typeof c.apiKey !== "string" || c.apiKey.length === 0) {
throw new MarketingAdapterConfigError("mailchimp config requires apiKey");
}
if (typeof c.listId !== "string" || c.listId.length === 0) {
throw new MarketingAdapterConfigError("mailchimp config requires listId");
}
return {
apiKey: c.apiKey,
listId: c.listId,
status: c.status === "pending" ? "pending" : "subscribed",
tags: Array.isArray(c.tags) ? (c.tags as unknown[]).filter((t) => typeof t === "string") as string[] : undefined,
};
},
async send({ payload, config, ctx }): Promise<AdapterResult> {
let built: ReturnType<typeof buildMailchimpPayload>;
try {
built = buildMailchimpPayload(payload, config);
} catch (err) {
return { ok: false, errorTag: err instanceof MarketingAdapterConfigError ? "config_error" : "build_error" };
}
const authHeader = `Basic ${Buffer.from(`any:${config.apiKey}`, "utf8").toString("base64")}`;
return adapterFetch(
built.url,
{
method: "PUT",
headers: {
"content-type": "application/json",
authorization: authHeader,
},
body: JSON.stringify(built.body),
},
ctx
);
},
};
@@ -0,0 +1,105 @@
/**
* Slack incoming-webhook adapter for Marketing-funnel Phase 2
* (Phase 05 #79). Posts a Block-Kit-formatted message describing the
* lead event to a Slack channel. Config carries only the
* incoming-webhook URL (encrypted at rest in MarketingIntegration).
*/
import {
adapterFetch,
formatLeadName,
maskEmailIfRequested,
MarketingAdapterConfigError,
type AdapterContext,
type AdapterResult,
type MarketingLeadEventType,
type MarketingLeadPayload,
type MarketingOutboundAdapter,
} from "../types.js";
export interface SlackConfig {
webhookUrl: string;
/** Optional channel override (Slack ignores when webhook is channel-bound). */
channel?: string;
}
function eventHeadline(eventType: MarketingLeadEventType): string {
switch (eventType) {
case "marketing.lead.captured":
return "New Lead Captured";
case "marketing.lead.qualified":
return "Lead Qualified";
case "marketing.lead.convertedtotrial":
return "Lead converted to Trial";
case "marketing.lead.convertedtocustomer":
return "Lead converted to Customer";
default:
return "Lead event";
}
}
export function buildSlackBlocks(
eventType: MarketingLeadEventType,
payload: MarketingLeadPayload,
ctx: AdapterContext
): unknown {
const name = formatLeadName(payload);
const email = maskEmailIfRequested(payload.email, ctx) ?? "(unknown)";
const lines: string[] = [];
if (payload.company) lines.push(`*Company:* ${payload.company}`);
if (payload.source) lines.push(`*Source:* ${payload.source}`);
if (payload.utm?.campaign) lines.push(`*Campaign:* ${payload.utm.campaign}`);
if (payload.utm?.source) lines.push(`*UTM-Source:* ${payload.utm.source}`);
if (payload.landingPage) lines.push(`*Landing:* ${payload.landingPage}`);
if (payload.conversionPath) lines.push(`*Conversion-Path:* ${payload.conversionPath}`);
if (payload.planId) lines.push(`*Plan:* ${payload.planId}`);
return {
text: `${eventHeadline(eventType)} — ${name} (${email})`,
blocks: [
{
type: "header",
text: { type: "plain_text", text: eventHeadline(eventType) },
},
{
type: "section",
text: { type: "mrkdwn", text: `*${name}* — ${email}` },
},
...(lines.length > 0
? [{ type: "section", text: { type: "mrkdwn", text: lines.join("\n") } }]
: []),
],
};
}
export const slackAdapter: MarketingOutboundAdapter<SlackConfig> = {
type: "slack",
parseConfig(config: unknown): SlackConfig {
if (!config || typeof config !== "object") {
throw new MarketingAdapterConfigError("slack config must be an object");
}
const c = config as Record<string, unknown>;
if (typeof c.webhookUrl !== "string" || c.webhookUrl.length === 0) {
throw new MarketingAdapterConfigError("slack config requires webhookUrl");
}
return {
webhookUrl: c.webhookUrl,
channel: typeof c.channel === "string" ? c.channel : undefined,
};
},
async send({ eventType, payload, config, ctx }): Promise<AdapterResult> {
const body = buildSlackBlocks(eventType, payload, ctx);
return adapterFetch(
config.webhookUrl,
{
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
...(body as object),
...(config.channel ? { channel: config.channel } : {}),
}),
},
ctx
);
},
};
@@ -0,0 +1,42 @@
/**
* Marketing-funnel Phase 2 outbound webhook adapters (Phase 05 #79).
*
* Each adapter implements `MarketingOutboundAdapter` and is registered
* in {@link adapterRegistry}. Worker code resolves the adapter by
* `MarketingIntegration.type` and dispatches outbox events through it.
*/
export * from "./types.js";
export { slackAdapter, type SlackConfig, buildSlackBlocks } from "./adapters/slack.js";
export { discordAdapter, type DiscordConfig, buildDiscordEmbed } from "./adapters/discord.js";
export { mailchimpAdapter, type MailchimpConfig, buildMailchimpPayload } from "./adapters/mailchimp.js";
export { hubspotAdapter, type HubSpotConfig, buildHubSpotPayload } from "./adapters/hubspot.js";
export { brevoAdapter, type BrevoConfig, buildBrevoPayload } from "./adapters/brevo.js";
export {
customWebhookAdapter,
type CustomWebhookConfig,
buildCustomPayload,
} from "./adapters/custom-webhook.js";
import type { MarketingOutboundAdapter } from "./types.js";
import { slackAdapter } from "./adapters/slack.js";
import { discordAdapter } from "./adapters/discord.js";
import { mailchimpAdapter } from "./adapters/mailchimp.js";
import { hubspotAdapter } from "./adapters/hubspot.js";
import { brevoAdapter } from "./adapters/brevo.js";
import { customWebhookAdapter } from "./adapters/custom-webhook.js";
export const adapterRegistry: Record<string, MarketingOutboundAdapter<unknown>> = {
slack: slackAdapter as MarketingOutboundAdapter<unknown>,
discord: discordAdapter as MarketingOutboundAdapter<unknown>,
mailchimp: mailchimpAdapter as MarketingOutboundAdapter<unknown>,
hubspot: hubspotAdapter as MarketingOutboundAdapter<unknown>,
brevo: brevoAdapter as MarketingOutboundAdapter<unknown>,
webhook: customWebhookAdapter as MarketingOutboundAdapter<unknown>,
};
export const ADAPTER_TYPES = Object.keys(adapterRegistry) as readonly string[];
export function resolveAdapter(type: string): MarketingOutboundAdapter<unknown> | undefined {
return adapterRegistry[type];
}
@@ -0,0 +1,157 @@
/**
* Shared types for Marketing-Funnel outbound webhook adapters
* (Phase 05 #79).
*
* Each adapter implements {@link MarketingOutboundAdapter} and is
* dispatched by the worker handler `marketing.lead.webhook` for outbox
* events whose eventType matches the adapter's `triggerEvents` array on
* the `MarketingIntegration` row.
*/
export type MarketingLeadEventType =
| "marketing.lead.captured"
| "marketing.lead.qualified"
| "marketing.lead.convertedtotrial"
| "marketing.lead.convertedtocustomer";
export interface MarketingLeadPayload {
/** Lead.id */
leadId: string;
email: string;
firstName?: string | null;
lastName?: string | null;
company?: string | null;
/** Free-text source label (Lead.source). */
source?: string | null;
utm?: {
source?: string | null;
medium?: string | null;
campaign?: string | null;
term?: string | null;
content?: string | null;
};
referrer?: string | null;
landingPage?: string | null;
/** Present only for conversion events. */
tenantId?: string | null;
targetStatus?: "trial" | "customer" | null;
conversionPath?: string | null;
planId?: string | null;
/** ISO timestamp. */
occurredAt?: string;
}
export interface AdapterContext {
/** Override window for unit tests. */
fetch?: typeof fetch;
/** Bound on the worker side; never undefined in production. */
timeoutMs?: number;
/**
* Mask PII from leaving the operator's domain. When `email` is set,
* adapters MUST replace the local-part with `***` before emitting the
* payload. UI maps to a per-integration toggle.
*/
maskPii?: { email?: boolean };
}
export interface AdapterResult {
ok: boolean;
status?: number;
/** Short non-PII error tag suitable for AuditEvent + Sentry. */
errorTag?: string;
}
export interface MarketingOutboundAdapter<TConfig = unknown> {
/** Stable adapter id matching MarketingIntegration.type. */
readonly type: string;
/** Validate + normalise the raw config blob coming out of the DB. */
parseConfig(config: unknown): TConfig;
send(args: {
eventType: MarketingLeadEventType;
payload: MarketingLeadPayload;
config: TConfig;
ctx: AdapterContext;
}): Promise<AdapterResult>;
}
/**
* Mask the local-part of an email when `maskPii.email` is enabled.
* `foo@bar.com` becomes `***@bar.com`. Returns the original input when
* masking is off or the input does not look like an email.
*/
export function maskEmailIfRequested(email: string | null | undefined, ctx: AdapterContext): string | null {
if (!email) return email ?? null;
if (!ctx.maskPii?.email) return email;
const at = email.indexOf("@");
if (at <= 0) return email;
return `***${email.slice(at)}`;
}
export class MarketingAdapterConfigError extends Error {
override readonly name = "MarketingAdapterConfigError";
}
export const DEFAULT_ADAPTER_TIMEOUT_MS = 10_000;
/**
* Shared fetch wrapper enforcing a timeout, a URL-allowlist check (HTTPS
* only, no localhost / RFC1918), and structured error tagging. Adapters
* funnel all outbound HTTP through this helper so SSRF and slow-loris
* mitigations live in one place.
*/
export async function adapterFetch(
url: string,
init: RequestInit,
ctx: AdapterContext
): Promise<AdapterResult> {
if (!isOutboundUrlAllowed(url)) {
return { ok: false, errorTag: "url_rejected_ssrf" };
}
const fetchImpl = ctx.fetch ?? fetch;
const controller = new AbortController();
const timeoutMs = ctx.timeoutMs ?? DEFAULT_ADAPTER_TIMEOUT_MS;
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetchImpl(url, { ...init, signal: controller.signal });
if (res.ok) return { ok: true, status: res.status };
return {
ok: false,
status: res.status,
errorTag: res.status >= 500 ? "upstream_5xx" : "upstream_4xx",
};
} catch (err) {
const tag = err instanceof Error && err.name === "AbortError" ? "timeout" : "network_error";
return { ok: false, errorTag: tag };
} finally {
clearTimeout(timer);
}
}
/**
* Reject internal-IP / non-HTTPS / loopback hosts. Identical posture to
* the form-widget webhook delivery guard so we can move both to a shared
* helper later if duplication grows.
*/
export function isOutboundUrlAllowed(url: string): boolean {
let parsed: URL;
try {
parsed = new URL(url);
} catch {
return false;
}
if (parsed.protocol !== "https:") return false;
const host = parsed.hostname.toLowerCase();
if (host === "localhost" || host.endsWith(".localhost")) return false;
if (host === "127.0.0.1" || host === "::1") return false;
if (host.startsWith("10.") || host.startsWith("192.168.")) return false;
if (/^172\.(1[6-9]|2\d|3[01])\./u.test(host)) return false;
if (host.startsWith("169.254.")) return false;
// Block AWS metadata + common cloud-internal suffixes.
if (host === "metadata.google.internal" || host.endsWith(".internal") || host.endsWith(".local") || host.endsWith(".lan")) return false;
return true;
}
export function formatLeadName(payload: MarketingLeadPayload): string {
const parts = [payload.firstName, payload.lastName].filter((p) => p && p.length > 0);
return parts.length > 0 ? parts.join(" ") : payload.email;
}
@@ -0,0 +1,13 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"allowJs": false,
"allowImportingTsExtensions": false,
"lib": ["ES2022"],
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noEmit": true,
"types": ["node"]
},
"include": ["src/**/*.ts"]
}