@ingram-tech/nk-marketing 0.2.0

package/README.md

@@ -0,0 +1,98 @@
+# @ingram-tech/nk-marketing
+
+Postgres-backed **marketing & lifecycle email**: contacts and consent,
+newsletter audiences/subscriptions (broadcast), and **idempotent triggered
+campaigns** (post-signup drips). RFC 8058 one-click unsubscribe throughout.
+Sends via [`@ingram-tech/nk-email`](../nk-email).
+
+This is the Postgres-native successor to `@ingram-tech/newsletter` (which was
+Supabase-bound). It **owns its tables** and ships the migration; you inject an
+`@ingram-tech/nk-db` pool (or any `pg` client) and a base URL. It defines its own
+row types and never reaches into your schema.
+
+## Install
+
+```bash
+bun add @ingram-tech/nk-marketing @ingram-tech/nk-email
+```
+
+## 1. Apply the schema
+
+The migration lives in the package. Fold `migrations/0001_marketing.sql` into
+your `drizzle/` pipeline (or apply it directly). It creates `marketing_contacts`,
+`marketing_audiences`, `marketing_subscriptions`, and `marketing_deliveries` —
+no RLS (reach them through your app role, like nk-billing).
+
+## 2. Wire it up
+
+```ts
+import { createMarketing } from "@ingram-tech/nk-marketing";
+import { pool } from "@/lib/db"; // your shared nk-db pool
+
+const marketing = createMarketing({
+	db: pool,
+	baseUrl: "https://example.com",
+	// unsubscribePath defaults to "/api/marketing/unsubscribe"
+});
+```
+
+Point one route at `marketing.unsubscribe(token)` — it resolves either a
+per-list subscription token (drops that audience) or a contact token (global
+marketing opt-out) and is idempotent.
+
+## Newsletters (broadcast)
+
+```ts
+await marketing.subscribe({ audienceSlug: "product-updates", email });
+
+await marketing.sendBroadcast({
+	audienceSlug: "product-updates",
+	subject: "What's new",
+	content: "First line.\n\nSecond paragraph.",
+	cta: { label: "Read more", href: "https://example.com/post" },
+	campaignKey: "2026-06-issue", // optional — makes a re-run idempotent
+	// onlyTo: ["you@example.com"], // test send
+});
+```
+
+Each recipient gets a per-subscription unsubscribe link; a globally opted-out
+contact is excluded automatically.
+
+## Lifecycle / triggered campaigns
+
+For "send your first invoice 1 month after signup if they haven't yet" and
+similar drips. **The division of labour:**
+
+- **Your app owns the trigger.** A daily cron queries *your* schema for due
+  contacts (signed up 30+ days ago, no invoice sent, etc.) — that condition
+  depends on your tables, so it stays with you.
+- **nk-marketing owns the cross-cutting parts.** For each due contact you call
+  `sendLifecycle`, which suppresses global opt-outs, sends **at most once** per
+  `campaignKey` per contact (claimed before send), attaches one-click
+  unsubscribe, and renders.
+
+```ts
+// in /internal/cron/onboarding-followup, for each due contact:
+const result = await marketing.sendLifecycle({
+	campaignKey: "first-invoice-nudge",
+	email: contact.email,
+	userId: contact.userId,
+	from: { name: "Peppost" },
+	subject: "Send your first Stripe e-invoice with Peppost",
+	content: "You're all set up — here's how to send your first invoice…",
+	cta: { label: "Open dashboard", href: "https://example.com/dashboard" },
+	footerReason: "you have a Peppost account",
+});
+// result.status: "sent" | "duplicate" | "suppressed"
+```
+
+`sendLifecycle` throws only if the underlying send fails (releasing its claim
+first so the next run retries) — wrap it best-effort so a mail outage never
+blocks your cron.
+
+## Rendering
+
+The built-in renderer produces clean, dependency-free HTML + text. Override it
+with `createMarketing({ render })` to use your own template (e.g. React Email).
+
+Requires `@ingram-tech/nk-email`'s env (`CLOUDFLARE_*`, `EMAIL_FROM_DOMAIN`).

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The marketing client: contacts + consent, newsletter audiences/subscriptions
+ * (broadcast), and idempotent triggered campaigns (lifecycle). Follows
+ * nextkit's Django-app model — the package owns its tables (migrations/) and
+ * takes the database by injection; the consuming site owns tenancy, scheduling,
+ * and the conditions that decide *who* gets a lifecycle email *when*.
+ *
+ * The division of labour for lifecycle email (the "send your first invoice"
+ * nudge): the SITE runs a daily cron and queries its own schema to find due
+ * contacts (e.g. signed up 30+ days ago, never sent an invoice). For each, it
+ * calls {@link sendLifecycle}, which owns the cross-cutting parts — suppression
+ * (global opt-out), exactly-once delivery (claim before send), one-click
+ * unsubscribe, and rendering. The site never re-implements those.
+ */
+import { type Queryable } from "./db.js";
+import { type MarketingRenderInput } from "./render.js";
+import type { Audience, BroadcastOptions, BroadcastResult, Contact, IdentifyOptions, LifecycleOptions, LifecycleResult, SubscribeOptions, Subscription, UnsubscribeResult } from "./types.js";
+export interface MarketingConfig {
+    /** A `pg` Pool/PoolClient or nk-db query interface (see {@link Queryable}). */
+    db: Queryable;
+    /** Absolute base URL for unsubscribe links, e.g. "https://example.com". */
+    baseUrl: string;
+    /** Unsubscribe route path. Default "/api/marketing/unsubscribe". */
+    unsubscribePath?: string;
+    /** Override the built-in HTML/text rendering. */
+    render?: (input: MarketingRenderInput) => {
+        html: string;
+        text: string;
+    };
+}
+export declare const createMarketing: (config: MarketingConfig) => {
+    identify: (options: IdentifyOptions) => Promise<Contact>;
+    getAudienceBySlug: (slug: string) => Promise<Audience | null>;
+    subscribe: (options: SubscribeOptions) => Promise<Subscription>;
+    unsubscribe: (token: string) => Promise<UnsubscribeResult>;
+    sendBroadcast: (options: BroadcastOptions) => Promise<BroadcastResult>;
+    sendLifecycle: (options: LifecycleOptions) => Promise<LifecycleResult>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAEN,KAAK,oBAAoB,EAGzB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACX,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,eAAe,EAEf,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC/B,+EAA+E;IAC/E,EAAE,EAAE,SAAS,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAKD,eAAO,MAAM,eAAe,GAAI,QAAQ,eAAe;wBAiBrB,eAAe,KAAG,OAAO,CAAC,OAAO,CAAC;8BAiB5B,MAAM,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;yBAoBtC,gBAAgB,KAAG,OAAO,CAAC,YAAY,CAAC;yBAgCxC,MAAM,KAAG,OAAO,CAAC,iBAAiB,CAAC;6BA8F3D,gBAAgB,KACvB,OAAO,CAAC,eAAe,CAAC;6BAqFjB,gBAAgB,KACvB,OAAO,CAAC,eAAe,CAAC;CA8C3B,CAAC"}

package/dist/client.js

@@ -0,0 +1,266 @@
+/**
+ * The marketing client: contacts + consent, newsletter audiences/subscriptions
+ * (broadcast), and idempotent triggered campaigns (lifecycle). Follows
+ * nextkit's Django-app model — the package owns its tables (migrations/) and
+ * takes the database by injection; the consuming site owns tenancy, scheduling,
+ * and the conditions that decide *who* gets a lifecycle email *when*.
+ *
+ * The division of labour for lifecycle email (the "send your first invoice"
+ * nudge): the SITE runs a daily cron and queries its own schema to find due
+ * contacts (e.g. signed up 30+ days ago, never sent an invoice). For each, it
+ * calls {@link sendLifecycle}, which owns the cross-cutting parts — suppression
+ * (global opt-out), exactly-once delivery (claim before send), one-click
+ * unsubscribe, and rendering. The site never re-implements those.
+ */
+import { fromAddress, sendEmail } from "@ingram-tech/nk-email";
+import { generateToken, normalizeEmail } from "./db.js";
+import { derivePreviewText, renderMarketingHtml, renderMarketingText, } from "./render.js";
+/** The bare address inside a "Name <addr>" string (or the string itself). */
+const bareAddress = (from) => from.match(/<([^>]+)>/)?.[1] ?? from;
+export const createMarketing = (config) => {
+    const { db, baseUrl } = config;
+    const unsubscribePath = config.unsubscribePath ?? "/api/marketing/unsubscribe";
+    const unsubscribeUrl = (token) => `${baseUrl}${unsubscribePath}?token=${encodeURIComponent(token)}`;
+    const renderFn = config.render ??
+        ((input) => ({
+            html: renderMarketingHtml(input),
+            text: renderMarketingText(input),
+        }));
+    /**
+     * Upsert a contact by email. New email → insert (with a fresh unsubscribe
+     * token); existing → backfill user_id/locale without overwriting consent or
+     * the token. The unit every other call resolves to.
+     */
+    const identify = async (options) => {
+        const email = normalizeEmail(options.email);
+        const { rows } = await db.query(`insert into marketing_contacts (email, user_id, locale, unsubscribe_token)
+			 values ($1, $2, $3, $4)
+			 on conflict (email) do update set
+			   user_id = coalesce(marketing_contacts.user_id, excluded.user_id),
+			   locale = coalesce(excluded.locale, marketing_contacts.locale),
+			   updated_at = now()
+			 returning id, email, user_id, locale, unsubscribe_token, unsubscribed_all_at`, [email, options.userId ?? null, options.locale ?? null, generateToken()]);
+        const contact = rows[0];
+        if (!contact)
+            throw new Error("nk-marketing: failed to upsert contact");
+        return contact;
+    };
+    const getAudienceBySlug = async (slug) => {
+        const { rows } = await db.query(`select id, slug, name, from_name, from_local_part, reply_to, is_active
+			 from marketing_audiences where slug = $1`, [slug]);
+        return rows[0] ?? null;
+    };
+    const requireAudience = async (slug) => {
+        const audience = await getAudienceBySlug(slug);
+        if (!audience)
+            throw new Error(`nk-marketing: unknown audience "${slug}"`);
+        return audience;
+    };
+    /**
+     * Idempotent subscribe to a broadcast audience: new → insert; existing →
+     * resurrect (clear unsubscribed_at) and backfill source. Identifies the
+     * contact first so consent and identity share one row.
+     */
+    const subscribe = async (options) => {
+        const audience = await requireAudience(options.audienceSlug);
+        if (!audience.is_active) {
+            throw new Error(`nk-marketing: audience is not active "${options.audienceSlug}"`);
+        }
+        const contact = await identify({
+            email: options.email,
+            userId: options.userId,
+        });
+        const { rows } = await db.query(`insert into marketing_subscriptions (audience_id, contact_id, unsubscribe_token, source)
+			 values ($1, $2, $3, $4)
+			 on conflict (audience_id, contact_id) do update set
+			   unsubscribed_at = null,
+			   source = coalesce(excluded.source, marketing_subscriptions.source),
+			   updated_at = now()
+			 returning id, audience_id, contact_id, unsubscribe_token, unsubscribed_at, source`, [audience.id, contact.id, generateToken(), options.source ?? null]);
+        const subscription = rows[0];
+        if (!subscription)
+            throw new Error("nk-marketing: failed to subscribe");
+        return subscription;
+    };
+    /**
+     * Resolve an unsubscribe token and act on it. A subscription token drops just
+     * that audience; a contact token is a global marketing opt-out (suppresses
+     * everything). Idempotent — a second click reports "already". Point your
+     * unsubscribe route straight at this.
+     */
+    const unsubscribe = async (token) => {
+        const sub = await db.query(`select id, unsubscribed_at from marketing_subscriptions where unsubscribe_token = $1`, [token]);
+        const subRow = sub.rows[0];
+        if (subRow) {
+            if (subRow.unsubscribed_at)
+                return { status: "already" };
+            await db.query(`update marketing_subscriptions set unsubscribed_at = now(), updated_at = now()
+				 where id = $1`, [subRow.id]);
+            return { status: "unsubscribed", scope: "audience" };
+        }
+        const contact = await db.query(`select id, unsubscribed_all_at from marketing_contacts where unsubscribe_token = $1`, [token]);
+        const contactRow = contact.rows[0];
+        if (contactRow) {
+            if (contactRow.unsubscribed_all_at)
+                return { status: "already" };
+            await db.query(`update marketing_contacts set unsubscribed_all_at = now(), updated_at = now()
+				 where id = $1`, [contactRow.id]);
+            return { status: "unsubscribed", scope: "global" };
+        }
+        return { status: "unknown" };
+    };
+    /** Claim (campaign_key, contact) before a send. Returns false if already taken. */
+    const claimDelivery = async (campaignKey, contactId) => {
+        const { rows } = await db.query(`insert into marketing_deliveries (campaign_key, contact_id) values ($1, $2)
+			 on conflict (campaign_key, contact_id) do nothing returning contact_id`, [campaignKey, contactId]);
+        return rows.length > 0;
+    };
+    /** Release a claim so a failed send can be retried on the next run. */
+    const releaseDelivery = async (campaignKey, contactId) => {
+        await db.query(`delete from marketing_deliveries where campaign_key = $1 and contact_id = $2`, [campaignKey, contactId]);
+    };
+    const send = async (args) => {
+        const { html, text } = renderFn(args.input);
+        await sendEmail({
+            to: args.to,
+            from: args.from,
+            replyTo: args.replyTo,
+            subject: args.subject,
+            html,
+            text,
+            listUnsubscribe: {
+                url: args.input.unsubscribeUrl,
+                mailto: bareAddress(args.from),
+            },
+        });
+    };
+    /**
+     * Send a broadcast to every active subscriber of an audience (a global
+     * opt-out excludes them too). Each recipient gets a per-subscription
+     * unsubscribe link. Failures are caught per-recipient so one bad address
+     * can't poison the batch. Pass `campaignKey` to make a re-run idempotent
+     * (recipients already delivered under that key are skipped).
+     *
+     * Sends are sequential with no built-in rate limiting — fine for the lists we
+     * run today; revisit (batching/backoff) before large sends.
+     */
+    const sendBroadcast = async (options) => {
+        const audience = await requireAudience(options.audienceSlug);
+        const { rows: recipients } = await db.query(`select s.unsubscribe_token as sub_token, c.id as contact_id, c.email as email
+			 from marketing_subscriptions s
+			 join marketing_contacts c on c.id = s.contact_id
+			 where s.audience_id = $1
+			   and s.unsubscribed_at is null
+			   and c.unsubscribed_all_at is null
+			 order by s.subscribed_at asc`, [audience.id]);
+        const targets = options.onlyTo
+            ? (() => {
+                const allowed = new Set(options.onlyTo.map(normalizeEmail));
+                return recipients.filter((r) => allowed.has(r.email));
+            })()
+            : recipients;
+        const from = fromAddress(audience.from_name, audience.from_local_part);
+        const previewText = options.previewText ?? derivePreviewText(options.content);
+        const result = {
+            totalRecipients: targets.length,
+            sentCount: 0,
+            skippedCount: 0,
+            failedCount: 0,
+            failures: [],
+        };
+        for (const r of targets) {
+            if (options.campaignKey) {
+                const claimed = await claimDelivery(options.campaignKey, r.contact_id);
+                if (!claimed) {
+                    result.skippedCount += 1;
+                    continue;
+                }
+            }
+            try {
+                await send({
+                    to: r.email,
+                    from,
+                    replyTo: audience.reply_to ?? undefined,
+                    subject: options.subject,
+                    input: {
+                        subject: options.subject,
+                        content: options.content,
+                        cta: options.cta,
+                        unsubscribeUrl: unsubscribeUrl(r.sub_token),
+                        previewText,
+                        footerReason: `you subscribed to ${audience.name}`,
+                    },
+                });
+                result.sentCount += 1;
+            }
+            catch (err) {
+                if (options.campaignKey) {
+                    await releaseDelivery(options.campaignKey, r.contact_id);
+                }
+                result.failedCount += 1;
+                result.failures.push({
+                    email: r.email,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return result;
+    };
+    /**
+     * Send one lifecycle/triggered email to one contact, at most once per
+     * `campaignKey`. Upserts the contact, then: skips if globally opted out
+     * ({@link LifecycleResult} "suppressed"); claims the delivery and skips if
+     * already sent ("duplicate"); otherwise sends with a global one-click
+     * unsubscribe link and returns "sent". The claim is released if the send
+     * throws, so the caller's next run retries. The *scheduling and eligibility*
+     * (when, and to whom) are the caller's job — see this module's header.
+     *
+     * @throws if the underlying send fails (after releasing the claim). Callers
+     *   should wrap best-effort so a mail outage never blocks their cron.
+     */
+    const sendLifecycle = async (options) => {
+        const contact = await identify({
+            email: options.email,
+            userId: options.userId,
+            locale: options.locale,
+        });
+        if (contact.unsubscribed_all_at)
+            return { status: "suppressed" };
+        const claimed = await claimDelivery(options.campaignKey, contact.id);
+        if (!claimed)
+            return { status: "duplicate" };
+        const sender = options.from;
+        const from = fromAddress(sender.name, sender.localPart);
+        try {
+            await send({
+                to: contact.email,
+                from,
+                replyTo: sender.replyTo,
+                subject: options.subject,
+                input: {
+                    subject: options.subject,
+                    content: options.content,
+                    cta: options.cta,
+                    unsubscribeUrl: unsubscribeUrl(contact.unsubscribe_token),
+                    previewText: options.previewText ?? derivePreviewText(options.content),
+                    footerReason: options.footerReason ??
+                        `you have an account with ${sender.name}`,
+                },
+            });
+        }
+        catch (err) {
+            await releaseDelivery(options.campaignKey, contact.id);
+            throw err;
+        }
+        return { status: "sent" };
+    };
+    return {
+        identify,
+        getAudienceBySlug,
+        subscribe,
+        unsubscribe,
+        sendBroadcast,
+        sendLifecycle,
+    };
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/db.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The database surface nk-marketing needs, by injection — identical in spirit to
+ * `@ingram-tech/nk-billing`'s `Queryable`. A structural `pg` Pool/PoolClient and
+ * nk-db's query helpers both satisfy it, so the consuming site passes whatever
+ * it already has and owns the tenancy/transaction story.
+ */
+export interface Queryable {
+    query<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/** Normalise an email for storage and lookup — trimmed + lowercased. */
+export declare const normalizeEmail: (email: string) => string;
+/**
+ * A 256-bit random token, hex-encoded, for an unsubscribe link. Generated in
+ * app code (not via a pgcrypto column default) so the migration stays
+ * extension-free and the value never leaks a row id.
+ */
+export declare const generateToken: () => string;
+//# sourceMappingURL=db.d.ts.map

package/dist/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,SAAS;IAGzB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GAChB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CAC1B;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAAoC,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAO,MAAyC,CAAC"}

package/dist/db.js

@@ -0,0 +1,16 @@
+/**
+ * The database surface nk-marketing needs, by injection — identical in spirit to
+ * `@ingram-tech/nk-billing`'s `Queryable`. A structural `pg` Pool/PoolClient and
+ * nk-db's query helpers both satisfy it, so the consuming site passes whatever
+ * it already has and owns the tenancy/transaction story.
+ */
+import { randomBytes } from "node:crypto";
+/** Normalise an email for storage and lookup — trimmed + lowercased. */
+export const normalizeEmail = (email) => email.trim().toLowerCase();
+/**
+ * A 256-bit random token, hex-encoded, for an unsubscribe link. Generated in
+ * app code (not via a pgcrypto column default) so the migration stays
+ * extension-free and the value never leaks a row id.
+ */
+export const generateToken = () => randomBytes(32).toString("hex");
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW1C,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAW,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createMarketing, type MarketingConfig } from "./client.js";
+export { type Queryable } from "./db.js";
+export { derivePreviewText, type MarketingRenderInput, renderMarketingHtml, renderMarketingText, } from "./render.js";
+export type { Audience, BroadcastOptions, BroadcastResult, Contact, Cta, IdentifyOptions, LifecycleOptions, LifecycleResult, Sender, SubscribeOptions, Subscription, UnsubscribeResult, } from "./types.js";
+//# 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":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EACN,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,mBAAmB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,OAAO,EACP,GAAG,EACH,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,MAAM,EACN,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createMarketing } from "./client.js";
+export { derivePreviewText, renderMarketingHtml, renderMarketingText, } from "./render.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAwB,MAAM,aAAa,CAAC;AAEpE,OAAO,EACN,iBAAiB,EAEjB,mBAAmB,EACnB,mBAAmB,GACnB,MAAM,aAAa,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The default, dependency-free HTML + text renderer for marketing email. Shared
+ * by broadcasts and lifecycle sends; override per `createMarketing({ render })`
+ * to drop in your own template (e.g. React Email). HTML escaping comes from
+ * `@ingram-tech/nk-email` so there is exactly one copy of it.
+ */
+import type { Cta } from "./types.js";
+/** Inputs the default renderer (or a custom one) receives per recipient. */
+export interface MarketingRenderInput {
+    subject: string;
+    /** Plain-text body; blank lines split paragraphs. */
+    content: string;
+    cta?: Cta | null;
+    /** Absolute one-click unsubscribe URL for this recipient. */
+    unsubscribeUrl: string;
+    /** Inbox-preview headline. */
+    previewText?: string;
+    /**
+     * Why this person is receiving the email, completing "You're receiving this
+     * because …" — e.g. "you subscribed to Acme Updates" or "you have an Acme
+     * account".
+     */
+    footerReason: string;
+}
+/** Minimal, dependency-free HTML email. */
+export declare const renderMarketingHtml: (input: MarketingRenderInput) => string;
+/** Plain-text counterpart of {@link renderMarketingHtml}. */
+export declare const renderMarketingText: (input: MarketingRenderInput) => string;
+/** First non-empty line, trimmed to ~140 chars — a sensible preview default. */
+export declare const derivePreviewText: (content: string) => string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACjB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,2CAA2C;AAC3C,eAAO,MAAM,mBAAmB,GAAI,OAAO,oBAAoB,KAAG,MAuBjE,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,GAAI,OAAO,oBAAoB,KAAG,MAGgC,CAAC;AAEnG,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,KAAG,MAOnD,CAAC"}

package/dist/render.js

@@ -0,0 +1,40 @@
+/**
+ * The default, dependency-free HTML + text renderer for marketing email. Shared
+ * by broadcasts and lifecycle sends; override per `createMarketing({ render })`
+ * to drop in your own template (e.g. React Email). HTML escaping comes from
+ * `@ingram-tech/nk-email` so there is exactly one copy of it.
+ */
+import { escapeHtml } from "@ingram-tech/nk-email";
+/** Minimal, dependency-free HTML email. */
+export const renderMarketingHtml = (input) => {
+    const paragraphs = input.content
+        .split(/\n\s*\n/)
+        .map((p) => p.trim())
+        .filter(Boolean)
+        .map((p) => `<p style="margin:0 0 16px;line-height:1.6;">${escapeHtml(p).replace(/\n/g, "<br/>")}</p>`)
+        .join("\n");
+    const cta = input.cta
+        ? `<p style="margin:24px 0;"><a href="${escapeHtml(input.cta.href)}" style="background:#111;color:#fff;padding:12px 20px;border-radius:8px;text-decoration:none;display:inline-block;">${escapeHtml(input.cta.label)}</a></p>`
+        : "";
+    return `<!doctype html><html><body style="font-family:Arial,Helvetica,sans-serif;max-width:600px;margin:0 auto;padding:24px;color:#111;">
+<div style="display:none;max-height:0;overflow:hidden;">${escapeHtml(input.previewText ?? "")}</div>
+<h1 style="font-size:20px;margin:0 0 16px;">${escapeHtml(input.subject)}</h1>
+${paragraphs}
+${cta}
+<hr style="border:none;border-top:1px solid #e5e5e5;margin:32px 0 16px;"/>
+<p style="font-size:12px;color:#888;">You're receiving this because ${escapeHtml(input.footerReason)}. <a href="${escapeHtml(input.unsubscribeUrl)}" style="color:#888;">Unsubscribe</a>.</p>
+</body></html>`;
+};
+/** Plain-text counterpart of {@link renderMarketingHtml}. */
+export const renderMarketingText = (input) => `${input.subject}\n\n${input.content}\n\n${input.cta ? `${input.cta.label}: ${input.cta.href}\n\n` : ""}---\nYou're receiving this because ${input.footerReason}.\nUnsubscribe: ${input.unsubscribeUrl}`;
+/** First non-empty line, trimmed to ~140 chars — a sensible preview default. */
+export const derivePreviewText = (content) => {
+    const first = content
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    if (!first)
+        return "";
+    return first.length > 140 ? `${first.slice(0, 137)}…` : first;
+};
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAqBnD,2CAA2C;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAA2B,EAAU,EAAE;IAC1E,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO;SAC9B,KAAK,CAAC,SAAS,CAAC;SAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CACH,CAAC,CAAC,EAAE,EAAE,CACL,+CAA+C,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAC3F;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG;QACpB,CAAC,CAAC,sCAAsC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,uHAAuH,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU;QAC9N,CAAC,CAAC,EAAE,CAAC;IAEN,OAAO;0DACkD,UAAU,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC;8CAC/C,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC;EACrE,UAAU;EACV,GAAG;;sEAEiE,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,cAAc,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC;eACnI,CAAC;AAChB,CAAC,CAAC;AAEF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAA2B,EAAU,EAAE,CAC1E,GAAG,KAAK,CAAC,OAAO,OAAO,KAAK,CAAC,OAAO,OACnC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAC3D,sCAAsC,KAAK,CAAC,YAAY,mBAAmB,KAAK,CAAC,cAAc,EAAE,CAAC;AAEnG,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAU,EAAE;IAC5D,MAAM,KAAK,GAAG,OAAO;SACnB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AAC/D,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Row interfaces for the package's own tables (see migrations/0001_marketing.sql)
+ * and the public option/result shapes. Following the nk-billing precedent, these
+ * are plain typed interfaces read via `db.query<Row>(...)` rather than Zod
+ * schemas: the rows come back from a typed `pg`/nk-db query, not from untyped
+ * Supabase JSON, so the boundary that the "validate with Zod" rule guards isn't
+ * crossed here.
+ *
+ * Timestamps are typed as `string` — a nextkit site configures `pg` to return
+ * timestamptz as ISO strings (nk-db's `configureTimestampsAsStrings`). The
+ * client only ever reads them for null-ness, so the exact representation does
+ * not matter to this package.
+ */
+/** Row of `marketing_contacts`. */
+export interface Contact {
+    id: string;
+    email: string;
+    user_id: string | null;
+    locale: string | null;
+    unsubscribe_token: string;
+    unsubscribed_all_at: string | null;
+}
+/** Row of `marketing_audiences`. */
+export interface Audience {
+    id: string;
+    slug: string;
+    name: string;
+    from_name: string;
+    from_local_part: string;
+    reply_to: string | null;
+    is_active: boolean;
+}
+/** Row of `marketing_subscriptions`. */
+export interface Subscription {
+    id: string;
+    audience_id: string;
+    contact_id: string;
+    unsubscribe_token: string;
+    unsubscribed_at: string | null;
+    source: string | null;
+}
+/** A call-to-action button rendered in the email body. */
+export interface Cta {
+    label: string;
+    href: string;
+}
+/** Sender identity for a lifecycle send (broadcasts take it from the audience). */
+export interface Sender {
+    /** Display name, e.g. "Peppost". */
+    name: string;
+    /** Local part of the from address; defaults to "notifications". */
+    localPart?: string;
+    replyTo?: string;
+}
+export interface IdentifyOptions {
+    email: string;
+    userId?: string;
+    locale?: string;
+}
+export interface SubscribeOptions {
+    audienceSlug: string;
+    email: string;
+    source?: string;
+    userId?: string;
+}
+export interface BroadcastOptions {
+    audienceSlug: string;
+    subject: string;
+    /** Plain-text body; blank lines split paragraphs in the default renderer. */
+    content: string;
+    previewText?: string;
+    cta?: Cta;
+    /** If set, only send to these addresses (case-insensitive). For test sends. */
+    onlyTo?: string[];
+    /**
+     * If set, each recipient is claimed in `marketing_deliveries` under this key
+     * before sending, making a re-run idempotent (the issue id is a good value).
+     * Omit to send unconditionally to every active subscriber (legacy behaviour).
+     */
+    campaignKey?: string;
+}
+export interface LifecycleOptions {
+    /** Stable program/step key, e.g. "first-invoice-nudge". Dedupes per contact. */
+    campaignKey: string;
+    email: string;
+    userId?: string;
+    locale?: string;
+    subject: string;
+    content: string;
+    previewText?: string;
+    cta?: Cta;
+    from: Sender;
+    /**
+     * Footer line explaining why the contact received this, e.g. "you have a
+     * Peppost account". Defaults to a generic account-based reason.
+     */
+    footerReason?: string;
+}
+export interface BroadcastResult {
+    totalRecipients: number;
+    sentCount: number;
+    /** Recipients skipped because already delivered under `campaignKey`. */
+    skippedCount: number;
+    failedCount: number;
+    failures: {
+        email: string;
+        error: string;
+    }[];
+}
+export type LifecycleResult = {
+    status: "sent";
+}
+/** Contact has globally opted out of marketing. */
+ | {
+    status: "suppressed";
+}
+/** Already delivered to this contact under this campaignKey. */
+ | {
+    status: "duplicate";
+};
+export type UnsubscribeResult = {
+    status: "unsubscribed";
+    scope: "audience" | "global";
+}
+/** Token matched but was already unsubscribed. */
+ | {
+    status: "already";
+}
+/** No subscription or contact carries this token. */
+ | {
+    status: "unknown";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * Row interfaces for the package's own tables (see migrations/0001_marketing.sql)
+ * and the public option/result shapes. Following the nk-billing precedent, these
+ * are plain typed interfaces read via `db.query<Row>(...)` rather than Zod
+ * schemas: the rows come back from a typed `pg`/nk-db query, not from untyped
+ * Supabase JSON, so the boundary that the "validate with Zod" rule guards isn't
+ * crossed here.
+ *
+ * Timestamps are typed as `string` — a nextkit site configures `pg` to return
+ * timestamptz as ISO strings (nk-db's `configureTimestampsAsStrings`). The
+ * client only ever reads them for null-ness, so the exact representation does
+ * not matter to this package.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/migrations/0001_marketing.sql

@@ -0,0 +1,87 @@
+-- @ingram-tech/nk-marketing — contacts, audiences, subscriptions, deliveries.
+--
+-- The stateful slice powering newsletter broadcasts AND post-signup lifecycle
+-- email. This is the Postgres-native successor to @ingram-tech/newsletter
+-- (which was Supabase/RLS-bound). Like @ingram-tech/nk-billing's ledger, these
+-- tables carry NO row-level security: a nextkit site reaches them through its
+-- app role and filters in the app layer. Add your own RLS only if your stack
+-- needs it.
+--
+-- Ship this as a Drizzle schema fragment + generated SQL so it composes with the
+-- consuming site's drizzle-kit pipeline (see docs/marketing.md). Table names are
+-- hardcoded by the client; adjust only on a collision.
+--
+-- updated_at is maintained in app code (the client sets `updated_at = now()` on
+-- every UPDATE) rather than by a trigger, to keep this migration plpgsql-free
+-- and identical across Postgres and PGlite.
+
+-- One contact per email address per site. The unit of identity and consent.
+create table if not exists marketing_contacts (
+	id                  uuid        primary key default gen_random_uuid(),
+	-- Lowercased email is the natural key.
+	email               text        not null unique,
+	-- Optional link to the site's own user/account id; lets you target by user.
+	user_id             text,
+	-- BCP-47 locale for localized sends; null = site default.
+	locale              text,
+	-- 256-bit random token behind the GLOBAL one-click unsubscribe link.
+	-- Generated in app code (no pgcrypto dependency); never the row id.
+	unsubscribe_token   text        not null unique,
+	-- Global marketing opt-out. NULL = opted in. Set by a contact-token
+	-- unsubscribe; suppresses BOTH lifecycle sends and broadcasts.
+	unsubscribed_all_at timestamptz,
+	created_at          timestamptz not null default now(),
+	updated_at          timestamptz not null default now(),
+	constraint marketing_contacts_email_lower check (email = lower(email)),
+	constraint marketing_contacts_email_format check (email ~ '^[^@\s]+@[^@\s]+\.[^@\s]+$')
+);
+
+-- Registry of broadcast lists (newsletters). The sending address is
+-- "<from_local_part>@<EMAIL_FROM_DOMAIN>". Lifecycle campaigns do NOT need an
+-- audience row — they pass their sender inline and target contacts directly.
+create table if not exists marketing_audiences (
+	id              uuid        primary key default gen_random_uuid(),
+	slug            text        not null unique,
+	name            text        not null,
+	from_name       text        not null,
+	from_local_part text        not null default 'news',
+	reply_to        text,
+	is_active       boolean     not null default true,
+	created_at      timestamptz not null default now(),
+	updated_at      timestamptz not null default now(),
+	constraint marketing_audiences_slug_format check (slug ~ '^[a-z0-9][a-z0-9-]*$'),
+	constraint marketing_audiences_from_local_part_format check (from_local_part ~ '^[a-z0-9][a-z0-9._-]*$')
+);
+
+-- A contact's opt-in to one audience. One row per (audience, contact); kept on
+-- unsubscribe so a re-subscribe is detectable.
+create table if not exists marketing_subscriptions (
+	id                uuid        primary key default gen_random_uuid(),
+	audience_id       uuid        not null references marketing_audiences (id) on delete cascade,
+	contact_id        uuid        not null references marketing_contacts (id) on delete cascade,
+	-- Per-subscription token: a broadcast unsubscribe link drops just THIS list,
+	-- distinct from the contact's global token.
+	unsubscribe_token text        not null unique,
+	subscribed_at     timestamptz not null default now(),
+	unsubscribed_at   timestamptz,
+	source            text,
+	created_at        timestamptz not null default now(),
+	updated_at        timestamptz not null default now(),
+	constraint marketing_subscriptions_audience_contact_key unique (audience_id, contact_id)
+);
+
+create index if not exists idx_marketing_subscriptions_audience on marketing_subscriptions (audience_id);
+create index if not exists idx_marketing_subscriptions_contact on marketing_subscriptions (contact_id);
+-- Hot path: enumerating active subscribers for a broadcast.
+create index if not exists idx_marketing_subscriptions_active on marketing_subscriptions (audience_id) where unsubscribed_at is null;
+
+-- Idempotency log. One row per (campaign_key, contact), claimed BEFORE a send so
+-- a retry or an overlapping cron can never deliver the same campaign twice. For
+-- lifecycle: campaign_key is the program/step key ("first-invoice-nudge"). For
+-- broadcasts: pass the issue id as campaign_key to make a re-run idempotent.
+create table if not exists marketing_deliveries (
+	campaign_key text        not null,
+	contact_id   uuid        not null references marketing_contacts (id) on delete cascade,
+	sent_at      timestamptz not null default now(),
+	primary key (campaign_key, contact_id)
+);

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@ingram-tech/nk-marketing",
+	"version": "0.2.0",
+	"description": "Postgres-backed marketing & lifecycle email: contacts, consent, newsletter audiences, and idempotent triggered campaigns with RFC 8058 one-click unsubscribe. Sends via @ingram-tech/nk-email.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/nk-marketing"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"migrations"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./migrations/*": "./migrations/*"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@ingram-tech/nk-email": "^0.3.0"
+	},
+	"devDependencies": {
+		"@ingram-tech/nk-dev": "0.2.3",
+		"@types/node": "^25.0.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
+	}
+}