@stacksjs/newsletter 0.70.23

package/README.md

@@ -0,0 +1,51 @@
+# @stacksjs/newsletter
+
+Promotional email + newsletter primitives for Stacks. Sits on top of
+`@stacksjs/email` — does not introduce a new transport.
+
+```ts
+import { newsletter } from '@stacksjs/newsletter'
+
+// list management
+const list = await newsletter.lists.create({ name: 'Weekly Digest', slug: 'weekly' })
+
+// subscribe / unsubscribe (returns the per-list unsubscribe token)
+await newsletter.subscribe('jane@example.com', { list: 'weekly', source: 'homepage' })
+await newsletter.unsubscribe(token)
+
+// campaigns
+const campaign = await newsletter.campaigns.create({
+  name: 'May Edition',
+  subject: 'What\'s new this month',
+  template: 'newsletter-may',
+  emailListId: list.id,
+})
+
+await newsletter.campaigns.sendNow(campaign.id) // dispatches SendCampaignJob
+await newsletter.campaigns.schedule(campaign.id, new Date('2026-05-15T09:00:00Z'))
+```
+
+## What this package owns
+
+- `EmailList`, `Campaign`, `CampaignSend`, `EmailListSubscriber` (pivot)
+- Per-list, per-subscriber unsubscribe tokens
+- `List-Unsubscribe` + `List-Unsubscribe-Post` headers (RFC 8058)
+- Chunked send via `SendCampaignJob` → `mail.send()` per recipient
+
+## What this package does NOT own
+
+- Email transports (use `@stacksjs/email` drivers — SES, SendGrid, Mailgun, …)
+- Open / click tracking pixels (planned)
+- Bounce / complaint webhooks (planned, per driver)
+- Drip / automation sequences (planned)
+- Provider-side audience sync (planned, opt-in)
+
+## Deliverability checklist
+
+This package can scaffold the headers and unsubscribe loop. Sending reputation
+is on you:
+
+- DKIM, SPF, and DMARC must pass on your sending domain
+- Warm dedicated IPs gradually if you're sending serious volume
+- Honor unsubscribes within the same business day
+- Monitor complaint rate (target < 0.1%) — exceeding 0.3% gets you blocked

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+var H=import.meta.require;function K(x){return x.toLowerCase().trim().replace(/[^\w\s-]+/g,"").replace(/\s+/g,"-").replace(/-+/g,"-")}var J={async create(x){let{EmailList:z}=await import("@stacksjs/orm"),D=x.slug??K(x.name);return z.create({name:x.name,slug:D,description:x.description??null,status:"active",isPublic:x.isPublic===!1?0:1,doubleOptIn:x.doubleOptIn===!1?0:1,subscriberCount:0,activeCount:0,unsubscribedCount:0,bouncedCount:0})},async find(x){let{EmailList:z}=await import("@stacksjs/orm");if(typeof x==="number")return z.find(x);return z.where("slug",x).first()},async all(){let{EmailList:x}=await import("@stacksjs/orm");return x.where("status","active").get()},async archive(x){let z=await J.find(x);if(!z)throw Error(`[newsletter] List '${String(x)}' not found`);return z.update({status:"archived"})}};async function P(x){if(x.emailListId)return x.emailListId;if(x.emailListSlug){let z=await J.find(x.emailListSlug);if(!z)throw Error(`[newsletter] List '${x.emailListSlug}' not found`);return z.id}throw Error("[newsletter] Campaign requires emailListId or emailListSlug")}var W={async create(x){let{Campaign:z}=await import("@stacksjs/orm"),D=await P(x),F=x.scheduledAt?"scheduled":"draft";return z.create({name:x.name,description:x.description??null,type:"email",status:F,subject:x.subject,template:x.template,text:x.text??null,from_name:x.fromName??null,from_address:x.fromAddress??null,email_list_id:D,scheduled_at:x.scheduledAt??null,sentCount:0})},async find(x){let{Campaign:z}=await import("@stacksjs/orm");return z.find(x)},async update(x,z){let D=await W.find(x);if(!D)throw Error(`[newsletter] Campaign ${x} not found`);if(D.status!=="draft"&&D.status!=="scheduled")throw Error(`[newsletter] Cannot edit campaign in status '${D.status}'`);return D.update(z)},async sendNow(x,z={}){let D=await W.find(x);if(!D)throw Error(`[newsletter] Campaign ${x} not found`);if(D.status==="sending"||D.status==="sent")throw Error(`[newsletter] Campaign ${x} already ${D.status}`);await D.update({status:"sending"});let{job:F}=await import("@stacksjs/queue");return await F("SendCampaign",{campaignId:x,chunkSize:z.chunkSize??50,dryRun:z.dryRun??!1}).onQueue("campaigns").dispatch(),{ok:!0,campaignId:x}},async schedule(x,z,D={}){let F=await W.find(x);if(!F)throw Error(`[newsletter] Campaign ${x} not found`);let G=z instanceof Date?z:new Date(z),M=Math.max(0,Math.floor((G.getTime()-Date.now())/1000));await F.update({status:M===0?"sending":"scheduled",scheduled_at:G.toISOString()});let{job:V}=await import("@stacksjs/queue");return await V("SendCampaign",{campaignId:x,chunkSize:D.chunkSize??50,dryRun:D.dryRun??!1}).onQueue("campaigns").delay(M).dispatch(),{ok:!0,campaignId:x,scheduledAt:G.toISOString()}},async cancel(x){let z=await W.find(x);if(!z)throw Error(`[newsletter] Campaign ${x} not found`);if(z.status==="sent")throw Error(`[newsletter] Campaign ${x} already sent \u2014 cannot cancel`);return z.update({status:"cancelled"})}};function U(x){if(!x.url||!/^https?:\/\//i.test(x.url))throw Error("[newsletter] List-Unsubscribe URL must be absolute (http/https)");let z=[];if(x.mailto)z.push(`<mailto:${x.mailto}>`);return z.push(`<${x.url}>`),{"List-Unsubscribe":z.join(", "),"List-Unsubscribe-Post":"List-Unsubscribe=One-Click"}}async function Q(x){if(x==null){let D=await J.find("default");if(!D)D=await J.create({name:"Default",slug:"default"});return D.id}let z=await J.find(x);if(!z)throw Error(`[newsletter] List '${String(x)}' not found`);return z.id}async function Y(x,z={}){if(!x||!x.includes("@"))throw Error("[newsletter] subscribe() requires a valid email address");let{Subscriber:D,EmailListSubscriber:F}=await import("@stacksjs/orm"),G=await Q(z.list),M=z.source??"api",V=await D.where("email",x).first();if(!V)V=await D.create({email:x,status:"subscribed",source:M});let X=await F.where("subscriber_id",V.id).where("email_list_id",G).first();if(X){if(X.status==="unsubscribed")await X.update({status:"subscribed",unsubscribed_at:null});return{created:!1,email:x,listId:G,token:X.uuid}}let B=await F.create({subscriber_id:V.id,email_list_id:G,status:"subscribed",source:M});return{created:!0,email:x,listId:G,token:B.uuid}}async function Z(x){if(!x)return{ok:!1};let{EmailListSubscriber:z,Subscriber:D}=await import("@stacksjs/orm"),F=await z.where("uuid",x).first();if(!F)return{ok:!1};if(F.status==="unsubscribed")return{ok:!0,alreadyUnsubscribed:!0,email:(await D.find(F.subscriber_id))?.email,listId:F.email_list_id};return await F.update({status:"unsubscribed",unsubscribed_at:new Date().toISOString()}),{ok:!0,email:(await D.find(F.subscriber_id))?.email,listId:F.email_list_id}}async function $(x){let{Subscriber:z,EmailListSubscriber:D}=await import("@stacksjs/orm"),F=await z.where("email",x).first();if(!F)return 0;let G=await D.where("subscriber_id",F.id).where("status","subscribed").get();for(let M of G)await M.update({status:"unsubscribed",unsubscribed_at:new Date().toISOString()});return G.length}var f={lists:J,campaigns:W,subscribe:Y,unsubscribe:Z,unsubscribeAll:$};export{$ as unsubscribeAll,Z as unsubscribe,Y as subscribe,f as newsletter,J as lists,W as campaigns,U as buildUnsubscribeHeaders};

package/dist/src/campaigns.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   create: () => unknown,
+ *   find: () => unknown,
+ *   update: () => unknown,
+ *   cancel: () => unknown
+ * }
+ * ```
+ */
+export declare const campaigns: {
+  create: (input: CreateCampaignInput) => Promise<void>;
+  find: (id: number) => Promise<void>;
+  update: (id: number, patch: Partial<CreateCampaignInput>) => Promise<void>;
+  /** Move a draft straight into the queue. */
+  async sendNow: (id: number, options?: SendCampaignOptions) => unknown;
+  /**
+   * Persist a `scheduled_at` and dispatch the job with a delay computed
+   * from now. If the time is in the past, falls back to immediate send.
+   */
+  async schedule: (id: number, scheduledAt: Date | string, options?: SendCampaignOptions) => unknown;
+  cancel: (id: number) => Promise<void>
+};

package/dist/src/headers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build the headers for an outbound campaign email.
+ *
+ * Returns a flat header map that drivers can copy into the outgoing
+ * MIME envelope.
+ */
+export declare function buildUnsubscribeHeaders(opts: UnsubscribeHeaderOptions): Record<string, string>;
+/**
+ * RFC 8058 / RFC 2369 List-Unsubscribe header construction.
+ *
+ * Why both mailto: and https://?  Some clients (older Outlook, some
+ * webmails) only honor `mailto:`; modern clients prefer the one-click
+ * HTTPS form. Including both lets every client unsubscribe without
+ * forcing the user to look for a tiny in-body link.
+ *
+ * `List-Unsubscribe-Post: List-Unsubscribe=One-Click` is what tells
+ * Gmail/Yahoo/etc. that POSTing to the https URL with no body is a
+ * valid one-click unsubscribe. Without that header those mailbox
+ * providers fall back to *clicking* the URL — which means a normal
+ * GET handler. RFC 8058 clients will POST.
+ */
+export declare interface UnsubscribeHeaderOptions {
+  url: string
+  mailto?: string
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './campaigns';
+export * from './headers';
+export * from './lists';
+export * from './newsletter';
+export * from './subscriptions';
+export * from './types';

package/dist/src/lists.d.ts

@@ -0,0 +1,8 @@
+/** @defaultValue `{ create: () => unknown, all: () => unknown, archive: () => unknown }` */
+export declare const lists: {
+  create: (input: CreateListInput) => Promise<void>;
+  /** Look up by slug first, then by id — slugs are the public-facing handle. */
+  async find: (idOrSlug: number | string) => unknown;
+  all: () => Promise<void>;
+  archive: (idOrSlug: number | string) => Promise<void>
+};

package/dist/src/newsletter.d.ts

@@ -0,0 +1,17 @@
+import { campaigns } from './campaigns';
+import { lists } from './lists';
+import { subscribe, unsubscribe, unsubscribeAll } from './subscriptions';
+/**
+ * Top-level Newsletter facade.
+ *
+ * Keeps the import surface tiny — most call sites only need
+ * `newsletter.subscribe()` or `newsletter.campaigns.sendNow()`.
+ */
+export declare const newsletter: {
+  lists: typeof lists
+  campaigns: typeof campaigns
+  subscribe: typeof subscribe
+  unsubscribe: typeof unsubscribe
+  unsubscribeAll: typeof unsubscribeAll
+};
+export { campaigns, lists, subscribe, unsubscribe, unsubscribeAll };

package/dist/src/subscriptions.d.ts

@@ -0,0 +1,5 @@
+import type { SubscribeOptions, SubscribeResult, UnsubscribeResult } from './types';
+export declare function subscribe(email: string, options?: SubscribeOptions): Promise<SubscribeResult>;
+export declare function unsubscribe(token: string): Promise<UnsubscribeResult>;
+/** Bulk unsubscribe by email — used by bounce/complaint handlers. */
+export declare function unsubscribeAll(email: string): Promise<number>;

package/dist/src/types.d.ts

@@ -0,0 +1,64 @@
+export declare interface CreateListInput {
+  name: string
+  slug?: string
+  description?: string
+  doubleOptIn?: boolean
+  isPublic?: boolean
+}
+export declare interface CreateCampaignInput {
+  name: string
+  subject: string
+  template: string
+  text?: string
+  emailListId?: number
+  emailListSlug?: string
+  fromName?: string
+  fromAddress?: string
+  scheduledAt?: string
+  description?: string
+}
+export declare interface SubscribeOptions {
+  list?: string | number
+  source?: string
+  upsert?: boolean
+}
+export declare interface SubscribeResult {
+  created: boolean
+  email: string
+  listId: number
+  token: string
+}
+export declare interface UnsubscribeResult {
+  ok: boolean
+  email?: string
+  listId?: number
+  alreadyUnsubscribed?: boolean
+}
+export declare interface SendCampaignOptions {
+  chunkSize?: number
+  dryRun?: boolean
+}
+/**
+ * Public types for the @stacksjs/newsletter package.
+ *
+ * The shapes here describe the *facade input/output*, not the underlying
+ * model rows — that lets us keep the public API stable even as model
+ * attribute lists evolve.
+ */
+export type EmailListStatus = 'active' | 'inactive' | 'archived';
+export type CampaignStatus = | 'draft'
+    | 'scheduled'
+    | 'sending'
+    | 'sent'
+    | 'paused'
+    | 'cancelled'
+    | 'failed';
+export type SubscriptionStatus = | 'subscribed'
+    | 'unsubscribed'
+    | 'pending'
+    | 'bounced';
+export type CampaignSendStatus = | 'queued'
+    | 'sent'
+    | 'failed'
+    | 'bounced'
+    | 'complained';

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@stacksjs/newsletter",
+  "type": "module",
+  "version": "0.70.23",
+  "description": "Promotional email & newsletter primitives for Stacks. Lists, campaigns, subscribers, and one-click unsubscribe — sent through @stacksjs/email.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/newsletter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/newsletter"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "newsletter",
+    "marketing",
+    "email",
+    "campaigns",
+    "stacks",
+    "broadcast",
+    "promotional",
+    "subscribers"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "bun": "./src/*",
+      "import": "./dist/*"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@stacksjs/cli": "0.70.23",
+    "@stacksjs/config": "0.70.23",
+    "better-dx": "^0.2.12",
+    "@stacksjs/error-handling": "0.70.23",
+    "@stacksjs/types": "0.70.23"
+  }
+}