@stacksjs/newsletter 0.70.88 → 0.70.91

package/dist/campaigns.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Campaign CRUD + dispatch.
+ *
+ * `sendNow()` and `schedule()` both end up dispatching the
+ * `SendCampaignJob` queue handler — `schedule()` just adds a `delay()`
+ * computed against the campaign's `scheduled_at`. The job is the one
+ * source of truth for actually fanning out emails so that a manual
+ * `sendNow()` from the dashboard and a cron-fired scheduled run go
+ * through identical machinery.
+ */
+declare function resolveListId(input: CreateCampaignInput): Promise<number>;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   create: () => unknown,
+ *   find: () => unknown,
+ *   update: () => unknown,
+ *   sendNow: () => unknown,
+ *   schedule: () => 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. */
+  sendNow: (id: number, options?: SendCampaignOptions) => Promise<void>;
+  /**
+   * 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.
+   */
+  schedule: (id: number, scheduledAt: Date | string, options?: SendCampaignOptions) => Promise<void>;
+  cancel: (id: number) => Promise<void>
+};

package/dist/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/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/index.js

@@ -0,0 +1,2 @@
+// @bun
+var H=import.meta.require;function B(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??B(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 K(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 V={async create(x){let{Campaign:z}=await import("@stacksjs/orm"),D=await K(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 V.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 V.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 V.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:Q}=await import("@stacksjs/queue");return await Q("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 V.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 P(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 X(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 P(z.list),M=z.source??"api",Q=await D.where("email",x).first();if(!Q)Q=await D.create({email:x,status:"subscribed",source:M});let W=await F.where("subscriber_id",Q.id).where("email_list_id",G).first();if(W){if(W.status==="unsubscribed")await W.update({status:"subscribed",unsubscribed_at:null});return{created:!1,email:x,listId:G,token:W.uuid}}let $=await F.create({subscriber_id:Q.id,email_list_id:G,status:"subscribed",source:M});return{created:!0,email:x,listId:G,token:$.uuid}}async function Y(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 Z(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 I={lists:J,campaigns:V,subscribe:X,unsubscribe:Y,unsubscribeAll:Z};export{Z as unsubscribeAll,Y as unsubscribe,X as subscribe,I as newsletter,J as lists,V as campaigns,U as buildUnsubscribeHeaders};

package/dist/lists.d.ts

@@ -0,0 +1,26 @@
+/**
+ * EmailList CRUD wrapper.
+ *
+ * The model lives in `defaults/app/Models/EmailList.ts`; here we expose
+ * a friendlier surface for application code so callers don't depend on
+ * raw ORM idioms (which changes across releases).
+ */
+declare function slugify(input: string): string;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   create: () => unknown,
+ *   find: () => 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. */
+  find: (idOrSlug: number | string) => Promise<void>;
+  all: () => Promise<void>;
+  archive: (idOrSlug: number | string) => Promise<void>
+};

package/dist/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/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/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

@@ -2,7 +2,7 @@
   "name": "@stacksjs/newsletter",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "Promotional email & newsletter primitives for Stacks. Lists, campaigns, subscribers, and one-click unsubscribe — sent through @stacksjs/email.",
   "author": "Chris Breuer",
   "contributors": [
@@ -56,10 +56,10 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.88",
-    "@stacksjs/config": "0.70.88",
+    "@stacksjs/cli": "0.70.91",
+    "@stacksjs/config": "0.70.91",
     "better-dx": "^0.2.16",
-    "@stacksjs/error-handling": "0.70.88",
-    "@stacksjs/types": "0.70.88"
+    "@stacksjs/error-handling": "0.70.91",
+    "@stacksjs/types": "0.70.91"
   }
 }