easy-ping 0.1.0

package/dist/plugin-bTJKmnlq.d.ts

@@ -0,0 +1,217 @@
+import { R as Recipient, C as Channel, f as DeliveryOutcome, k as PluginStore } from './adapter-f0OR2DhY.js';
+
+declare class EasyPingError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a payload fails its Standard Schema. Developer error. */
+declare class ValidationError extends EasyPingError {
+    readonly issues: readonly {
+        message: string;
+        path?: string;
+    }[];
+    constructor(type: string, issues: readonly {
+        message: string;
+        path?: string;
+    }[]);
+}
+/** Thrown at startup for a malformed config. Never at send time. */
+declare class ConfigError extends EasyPingError {
+    constructor(message: string);
+}
+type Logger = {
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+};
+declare const consoleLogger: Logger;
+
+type Promisable<T> = T | Promise<T>;
+type PrepareContext = {
+    type: string;
+    recipients: readonly Recipient[];
+};
+type BeforeSendContext = {
+    type: string;
+    recipient: Recipient;
+    payload: unknown;
+    actorId: string | null;
+    dedupeKey: string | null;
+    /** Whatever this plugin's own prepare() returned for this send. */
+    prepared: unknown;
+};
+type BeforeSendResult = {
+    action: "continue";
+    payload?: unknown;
+    dedupeKey?: string;
+} | {
+    action: "cancel";
+    reason: string;
+};
+type ChannelDecision = {
+    channel: Channel;
+    action: "send" | "skip" | "defer";
+    /** defer only. Written to notification_delivery.not_before. */
+    notBefore?: Date | undefined;
+};
+type ResolveChannelsContext = {
+    type: string;
+    recipient: Recipient;
+    payload: unknown;
+    decisions: readonly ChannelDecision[];
+    /** Whatever this plugin's own prepare() returned for this send. */
+    prepared: unknown;
+};
+type DeliverContext = {
+    channel: Channel;
+    deliveryId: string;
+    attempt: number;
+    recipient: Recipient;
+    notification: {
+        id: string;
+        userId: string;
+        type: string;
+        payload: unknown;
+    };
+    /** Aborted on the runner's timeout. */
+    signal: AbortSignal;
+};
+type AfterSendContext = {
+    type: string;
+    payload: unknown;
+    /** Committed rows. Ids exist only at this point. */
+    notifications: readonly {
+        id: string;
+        userId: string;
+    }[];
+    /** Whatever this plugin's own prepare() returned for this send. */
+    prepared: unknown;
+};
+type AfterDeliverContext = {
+    deliveryId: string;
+    notificationId: string;
+    userId: string;
+    channel: Channel;
+    outcome: DeliveryOutcome;
+    attempt: number;
+    isTerminal: boolean;
+};
+/** beforeSend and resolveChannels fail closed; afterDeliver fails open. */
+type PluginHooks = {
+    /** Once per send, for bulk loading — the per-recipient hooks would be an N+1. */
+    prepare?: (ctx: PrepareContext) => Promisable<unknown>;
+    beforeSend?: (ctx: BeforeSendContext) => Promisable<BeforeSendResult>;
+    resolveChannels?: (ctx: ResolveChannelsContext) => Promisable<readonly ChannelDecision[]>;
+    /**
+     * Once per send, after the rows are committed. The only hook that sees
+     * notification ids, which digests needs to bucket an entry against one.
+     * Fails open: the notification is already written.
+     */
+    afterSend?: (ctx: AfterSendContext) => Promisable<void>;
+    /**
+     * Delivers one of the plugin's declared `channels`. Core carries inApp and
+     * email; everything else arrives here, which is how push, sms and slack are
+     * added without core learning about them.
+     */
+    deliver?: (ctx: DeliverContext) => Promisable<DeliveryOutcome>;
+    afterDeliver?: (ctx: AfterDeliverContext) => Promisable<void>;
+};
+type FieldType = "string" | "number" | "boolean" | "date" | "json";
+type FieldDeclaration = {
+    type: FieldType;
+    required?: boolean;
+    default?: string | number | boolean;
+    /** date fields only. Renders as defaultNow() / CURRENT_TIMESTAMP. */
+    defaultNow?: boolean;
+};
+type IndexDeclaration = {
+    on: readonly string[];
+    unique?: boolean;
+    name?: string;
+};
+type TableDeclaration = {
+    tableName: string;
+    fields: Record<string, FieldDeclaration>;
+    primaryKey?: readonly string[];
+    indexes?: readonly IndexDeclaration[];
+};
+type SchemaDeclaration = Record<string, TableDeclaration>;
+type RouteScope = {
+    type: "user";
+} | {
+    type: "machine";
+} | {
+    type: "signed";
+    purpose: string;
+} | {
+    type: "custom";
+    justification: string;
+};
+type RouteContext = {
+    request: Request;
+    /** Resolved for user-scoped routes, so a handler cannot forget to scope. */
+    userId: string | null;
+    /** Verified before dispatch, so a handler cannot forget to check. */
+    claims: {
+        uid: string;
+        purpose: string;
+        exp: number;
+        data?: Record<string, string>;
+    } | null;
+    params: Record<string, string>;
+};
+type RouteDefinition = {
+    path: string;
+    method: "GET" | "POST";
+    scope: RouteScope;
+    handler: (ctx: RouteContext) => Promise<Response>;
+};
+/** Handed to a plugin at startup so it need not be given the database twice. */
+type PluginInitContext = {
+    /** Scoped to the tables this plugin declares in schema(). */
+    store: PluginStore;
+    /** The top-level signing secret, for plugins issuing signed links. */
+    secret: string;
+    logger: Logger;
+    /** The app's resolver, for plugins that need timezones or addresses. */
+    getRecipients: (userIds: readonly string[]) => Promise<readonly Recipient[]>;
+    /**
+     * The instance's own send(). A plugin composing a message (a digest, say)
+     * routes it back through the pipeline rather than reaching for a provider,
+     * so it inherits retry, backoff and idempotency for free.
+     */
+    send: (type: string, args: {
+        to: string | readonly string[];
+        payload: unknown;
+        dedupeKey?: string;
+    }) => Promise<unknown>;
+};
+type EasyPingPlugin<TId extends string = string, TSchema extends SchemaDeclaration = SchemaDeclaration> = {
+    id: TId;
+    dependsOn?: readonly string[];
+    schema?: TSchema;
+    routes?: readonly RouteDefinition[];
+    hooks?: PluginHooks;
+    /** Channels this plugin delivers. Makes them usable in a notification. */
+    channels?: readonly Channel[];
+    /** Called once by easyPing() before any hook or route can run. */
+    init?: (ctx: PluginInitContext) => void;
+};
+type AnyPlugin = EasyPingPlugin<string, SchemaDeclaration>;
+declare function definePlugin<TId extends string, TSchema extends SchemaDeclaration>(plugin: EasyPingPlugin<TId, TSchema>): EasyPingPlugin<TId, TSchema>;
+type ClientFetch = (path: string, init?: RequestInit) => Promise<unknown>;
+type ClientPlugin<TId extends string = string, TActions extends Record<string, unknown> = Record<string, unknown>> = {
+    id: TId;
+    /** Phantom. Links client types to the server plugin so a mismatch is a type error. */
+    $InferServerPlugin?: AnyPlugin;
+    actions: (fetch: ClientFetch) => TActions;
+};
+type AnyClientPlugin = ClientPlugin<string, Record<string, unknown>>;
+declare function defineClientPlugin<TId extends string, TActions extends Record<string, unknown>>(plugin: ClientPlugin<TId, TActions>): ClientPlugin<TId, TActions>;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** Naked type parameter, so the conditional distributes over the union. */
+type ExtractActions<TPlugin> = TPlugin extends {
+    actions: (fetch: never) => infer TActions;
+} ? TActions : never;
+/** Indexes the tuple rather than recursing: a fold blows the instantiation depth limit. */
+type ActionsOf<TPlugins extends readonly AnyClientPlugin[]> = UnionToIntersection<ExtractActions<TPlugins[number]>>;
+
+export { type AnyPlugin as A, type BeforeSendContext as B, type ChannelDecision as C, EasyPingError as E, type FieldDeclaration as F, type Logger as L, type PluginHooks as P, type ResolveChannelsContext as R, type SchemaDeclaration as S, type TableDeclaration as T, type UnionToIntersection as U, ValidationError as V, type ActionsOf as a, type AfterDeliverContext as b, type AnyClientPlugin as c, type BeforeSendResult as d, type ClientFetch as e, type ClientPlugin as f, ConfigError as g, type EasyPingPlugin as h, type FieldType as i, type PrepareContext as j, type Promisable as k, type RouteContext as l, type RouteDefinition as m, type RouteScope as n, consoleLogger as o, defineClientPlugin as p, definePlugin as q };

package/dist/plugins/digests.cjs

@@ -0,0 +1,206 @@
+'use strict';
+
+// src/plugins/digests/schedule.ts
+var WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+function localMoment(timezone, now) {
+  const formatter = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    hourCycle: "h23",
+    weekday: "short"
+  });
+  const parts = {};
+  for (const part of formatter.formatToParts(now)) parts[part.type] = part.value;
+  return {
+    date: `${parts.year}-${parts.month}-${parts.day}`,
+    hour: Number(parts.hour ?? 0),
+    weekday: Math.max(0, WEEKDAYS.indexOf(parts.weekday ?? "Sun"))
+  };
+}
+var shiftDays = (date, days) => {
+  const shifted = /* @__PURE__ */ new Date(`${date}T00:00:00Z`);
+  shifted.setUTCDate(shifted.getUTCDate() - days);
+  return shifted.toISOString().slice(0, 10);
+};
+function periodKey(window, moment, sendWeekday) {
+  if (window === "daily") return moment.date;
+  const since = (moment.weekday - sendWeekday + 7) % 7;
+  return shiftDays(moment.date, since);
+}
+function isDue(window, moment, sendHour, sendWeekday) {
+  if (window === "daily") return moment.hour >= sendHour;
+  const period = periodKey("weekly", moment, sendWeekday);
+  return moment.date > period || moment.hour >= sendHour;
+}
+
+// src/plugins/digests/index.ts
+var ENTRY = "notification_digest_entry";
+var STATE = "notification_digest_state";
+var isDigestWindow = (frequency) => frequency === "daily" || frequency === "weekly";
+function digests(options = {}) {
+  const digestType = options.digestType ?? "digest";
+  const sendHour = options.sendHour ?? 9;
+  const sendWeekday = options.sendWeekday ?? 1;
+  const channel = options.channel ?? "email";
+  const maxUsersPerRun = options.maxUsersPerRun ?? 500;
+  let ctx;
+  async function windowFor(userIds, type) {
+    const rows = await ctx.store.find("notification_preference", { userId: { in: [...userIds] }, type, channel });
+    const windows = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (row.enabled && isDigestWindow(row.frequency)) windows.set(row.userId, row.frequency);
+    }
+    return windows;
+  }
+  return {
+    id: "digests",
+    dependsOn: ["preferences"],
+    init: (context) => {
+      ctx = context;
+    },
+    schema: {
+      digestEntry: {
+        tableName: ENTRY,
+        fields: {
+          id: { type: "string", required: true },
+          userId: { type: "string", required: true },
+          type: { type: "string", required: true },
+          notificationId: { type: "string", required: true },
+          payload: { type: "json" },
+          window: { type: "string", required: true },
+          createdAt: { type: "date", required: true, defaultNow: true }
+        },
+        primaryKey: ["id"],
+        indexes: [{ on: ["userId", "window"], name: "digest_entry_user_idx" }]
+      },
+      digestState: {
+        tableName: STATE,
+        fields: {
+          userId: { type: "string", required: true },
+          window: { type: "string", required: true },
+          /** Last period actually sent. The idempotency key for the schedule. */
+          lastPeriod: { type: "string", required: true },
+          updatedAt: { type: "date", required: true, defaultNow: true }
+        },
+        primaryKey: ["userId", "window"]
+      },
+      // Read-only here; owned by the preferences plugin.
+      notificationPreference: {
+        tableName: "notification_preference",
+        fields: {
+          userId: { type: "string", required: true },
+          type: { type: "string", required: true },
+          channel: { type: "string", required: true },
+          enabled: { type: "boolean", required: true },
+          frequency: { type: "string", required: true }
+        },
+        primaryKey: ["userId", "type", "channel"]
+      }
+    },
+    hooks: {
+      prepare: async (context) => {
+        if (context.type === digestType) return { deferred: /* @__PURE__ */ new Map() };
+        return {
+          deferred: await windowFor(
+            context.recipients.map((recipient) => recipient.userId),
+            context.type
+          )
+        };
+      },
+      resolveChannels: (context) => {
+        const prepared = context.prepared;
+        if (!prepared?.deferred.has(context.recipient.userId)) return context.decisions;
+        return context.decisions.map(
+          (decision) => decision.channel === channel ? { ...decision, action: "skip" } : decision
+        );
+      },
+      // The only hook that sees notification ids.
+      afterSend: async (context) => {
+        const prepared = context.prepared;
+        if (!prepared || prepared.deferred.size === 0) return;
+        const entries = context.notifications.filter((notification) => prepared.deferred.has(notification.userId)).map((notification) => ({
+          id: crypto.randomUUID(),
+          userId: notification.userId,
+          type: context.type,
+          notificationId: notification.id,
+          payload: context.payload,
+          window: prepared.deferred.get(notification.userId),
+          createdAt: /* @__PURE__ */ new Date()
+        }));
+        if (entries.length > 0) await ctx.store.insert(ENTRY, entries);
+      }
+    },
+    routes: [
+      {
+        /**
+         * Point an hourly cron here. Hourly rather than daily because "9am"
+         * is 24 different UTC moments, and which ones shift with DST.
+         */
+        path: "/digests/cron",
+        method: "POST",
+        scope: { type: "machine" },
+        handler: async () => {
+          const now = /* @__PURE__ */ new Date();
+          const pending = await ctx.store.find(ENTRY, {}, { limit: 1e4 });
+          if (pending.length === 0) return Response.json({ sent: 0, users: 0 });
+          const byUser = /* @__PURE__ */ new Map();
+          for (const entry of pending) {
+            const bucket = byUser.get(entry.userId);
+            if (bucket) bucket.push(entry);
+            else byUser.set(entry.userId, [entry]);
+          }
+          const userIds = [...byUser.keys()].slice(0, maxUsersPerRun);
+          const recipients = await ctx.getRecipients(userIds);
+          const zones = new Map(recipients.map((r) => [r.userId, r.timezone]));
+          const states = await ctx.store.find(STATE, { userId: { in: userIds } });
+          const lastPeriods = new Map(states.map((s) => [`${s.userId} ${s.window}`, s.lastPeriod]));
+          let sent = 0;
+          for (const userId of userIds) {
+            const entries = byUser.get(userId) ?? [];
+            const moment = localMoment(zones.get(userId) ?? "UTC", now);
+            for (const window of ["daily", "weekly"]) {
+              const forWindow = entries.filter((entry) => entry.window === window);
+              if (forWindow.length === 0) continue;
+              const period = periodKey(window, moment, sendWeekday);
+              if (lastPeriods.get(`${userId} ${window}`) === period) continue;
+              if (!isDue(window, moment, sendHour, sendWeekday)) continue;
+              await ctx.send(digestType, {
+                to: userId,
+                payload: {
+                  window,
+                  period,
+                  items: forWindow.map((entry) => ({
+                    type: entry.type,
+                    payload: entry.payload,
+                    createdAt: entry.createdAt
+                  }))
+                },
+                dedupeKey: `digest:${window}:${period}:${userId}`
+              });
+              await ctx.store.upsert(
+                STATE,
+                [{ userId, window, lastPeriod: period, updatedAt: /* @__PURE__ */ new Date() }],
+                { onConflict: ["userId", "window"] }
+              );
+              await ctx.store.remove(ENTRY, {
+                id: { in: forWindow.map((entry) => entry.id) }
+              });
+              sent += 1;
+            }
+          }
+          return Response.json({ sent, users: userIds.length });
+        }
+      }
+    ]
+  };
+}
+
+exports.digests = digests;
+exports.isDue = isDue;
+exports.localMoment = localMoment;
+exports.periodKey = periodKey;
+//# sourceMappingURL=digests.cjs.map
+//# sourceMappingURL=digests.cjs.map

package/dist/plugins/digests.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugins/digests/schedule.ts","../../src/plugins/digests/index.ts"],"names":[],"mappings":"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","file":"digests.cjs","sourcesContent":["export type DigestWindow = \"daily\" | \"weekly\";\n\nexport type LocalMoment = {\n  /** YYYY-MM-DD in the recipient's zone. */\n  date: string;\n  hour: number;\n  /** 0 = Sunday. */\n  weekday: number;\n};\n\nconst WEEKDAYS = [\"Sun\", \"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\"];\n\n/**\n * Reads the wall clock in a recipient's zone.\n *\n * hourCycle h23 rather than hour12:false — the latter renders midnight as \"24\"\n * in several locales, which silently makes the send-hour comparison wrong for\n * one hour a day.\n */\nexport function localMoment(timezone: string, now: Date): LocalMoment {\n  const formatter = new Intl.DateTimeFormat(\"en-CA\", {\n    timeZone: timezone,\n    year: \"numeric\",\n    month: \"2-digit\",\n    day: \"2-digit\",\n    hour: \"2-digit\",\n    hourCycle: \"h23\",\n    weekday: \"short\",\n  });\n\n  const parts: Record<string, string> = {};\n  for (const part of formatter.formatToParts(now)) parts[part.type] = part.value;\n\n  return {\n    date: `${parts.year}-${parts.month}-${parts.day}`,\n    hour: Number(parts.hour ?? 0),\n    weekday: Math.max(0, WEEKDAYS.indexOf(parts.weekday ?? \"Sun\")),\n  };\n}\n\nconst shiftDays = (date: string, days: number): string => {\n  const shifted = new Date(`${date}T00:00:00Z`);\n  shifted.setUTCDate(shifted.getUTCDate() - days);\n  return shifted.toISOString().slice(0, 10);\n};\n\n/**\n * Identifies the digest period a moment falls in.\n *\n * Scheduling keys off this string rather than bucketing users by UTC offset.\n * Offsets shift twice a year, and getting that wrong sends someone two digests\n * or none. A period key cannot: it is derived from the local calendar, so DST\n * is already accounted for and a missed cron run simply catches up.\n */\nexport function periodKey(window: DigestWindow, moment: LocalMoment, sendWeekday: number): string {\n  if (window === \"daily\") return moment.date;\n\n  const since = (moment.weekday - sendWeekday + 7) % 7;\n  return shiftDays(moment.date, since);\n}\n\n/** Whether the send moment for the current period has arrived. */\nexport function isDue(\n  window: DigestWindow,\n  moment: LocalMoment,\n  sendHour: number,\n  sendWeekday: number,\n): boolean {\n  if (window === \"daily\") return moment.hour >= sendHour;\n\n  const period = periodKey(\"weekly\", moment, sendWeekday);\n  // Past the send day means a run was missed; catch up rather than skip a week.\n  return moment.date > period || moment.hour >= sendHour;\n}\n","import type {\n  AfterSendContext,\n  EasyPingPlugin,\n  PluginInitContext,\n  PrepareContext,\n  ResolveChannelsContext,\n} from \"../../core/plugin\";\nimport type { Frequency } from \"../../core/types\";\nimport { type DigestWindow, isDue, localMoment, periodKey } from \"./schedule\";\n\nconst ENTRY = \"notification_digest_entry\";\nconst STATE = \"notification_digest_state\";\n\nexport type DigestEntry = {\n  id: string;\n  userId: string;\n  type: string;\n  notificationId: string;\n  payload: unknown;\n  window: DigestWindow;\n  createdAt: Date;\n};\n\nexport type DigestsOptions = {\n  /**\n   * The notification type the composed digest is sent as. The app defines it\n   * with an email template taking `{ items }`.\n   */\n  digestType?: string;\n  /** Local hour at which a digest becomes due. */\n  sendHour?: number;\n  /** Weekly digests only; 0 = Sunday. */\n  sendWeekday?: number;\n  /** Channels a digest defers. Only email makes sense today. */\n  channel?: \"email\";\n  /** Safety valve on one cron run. */\n  maxUsersPerRun?: number;\n};\n\ntype Prepared = {\n  /** userId -> window, for recipients whose preference defers this type. */\n  deferred: Map<string, DigestWindow>;\n};\n\nconst isDigestWindow = (frequency: Frequency): frequency is DigestWindow =>\n  frequency === \"daily\" || frequency === \"weekly\";\n\n/**\n * Collects notifications a user has chosen to receive on a schedule, then\n * sends them as one message.\n *\n * Deliberately not implemented with `defer`: deferring N emails to 9am sends N\n * emails at 9am. A digest is one email containing N items, so the channel is\n * skipped and the item is bucketed instead.\n *\n * Depends on `preferences` for the per-type frequency it reads.\n */\nexport function digests(options: DigestsOptions = {}): EasyPingPlugin<\"digests\"> {\n  const digestType = options.digestType ?? \"digest\";\n  const sendHour = options.sendHour ?? 9;\n  const sendWeekday = options.sendWeekday ?? 1;\n  const channel = options.channel ?? \"email\";\n  const maxUsersPerRun = options.maxUsersPerRun ?? 500;\n\n  let ctx: PluginInitContext;\n\n  /** Reads the frequency the preferences plugin stored for this type. */\n  async function windowFor(\n    userIds: readonly string[],\n    type: string,\n  ): Promise<Map<string, DigestWindow>> {\n    const rows = await ctx.store.find<{\n      userId: string;\n      type: string;\n      channel: string;\n      frequency: Frequency;\n      enabled: boolean;\n    }>(\"notification_preference\", { userId: { in: [...userIds] }, type, channel });\n\n    const windows = new Map<string, DigestWindow>();\n    for (const row of rows) {\n      if (row.enabled && isDigestWindow(row.frequency)) windows.set(row.userId, row.frequency);\n    }\n    return windows;\n  }\n\n  return {\n    id: \"digests\",\n    dependsOn: [\"preferences\"],\n\n    init: (context) => {\n      ctx = context;\n    },\n\n    schema: {\n      digestEntry: {\n        tableName: ENTRY,\n        fields: {\n          id: { type: \"string\", required: true },\n          userId: { type: \"string\", required: true },\n          type: { type: \"string\", required: true },\n          notificationId: { type: \"string\", required: true },\n          payload: { type: \"json\" },\n          window: { type: \"string\", required: true },\n          createdAt: { type: \"date\", required: true, defaultNow: true },\n        },\n        primaryKey: [\"id\"],\n        indexes: [{ on: [\"userId\", \"window\"], name: \"digest_entry_user_idx\" }],\n      },\n\n      digestState: {\n        tableName: STATE,\n        fields: {\n          userId: { type: \"string\", required: true },\n          window: { type: \"string\", required: true },\n          /** Last period actually sent. The idempotency key for the schedule. */\n          lastPeriod: { type: \"string\", required: true },\n          updatedAt: { type: \"date\", required: true, defaultNow: true },\n        },\n        primaryKey: [\"userId\", \"window\"],\n      },\n\n      // Read-only here; owned by the preferences plugin.\n      notificationPreference: {\n        tableName: \"notification_preference\",\n        fields: {\n          userId: { type: \"string\", required: true },\n          type: { type: \"string\", required: true },\n          channel: { type: \"string\", required: true },\n          enabled: { type: \"boolean\", required: true },\n          frequency: { type: \"string\", required: true },\n        },\n        primaryKey: [\"userId\", \"type\", \"channel\"],\n      },\n    },\n\n    hooks: {\n      prepare: async (context: PrepareContext): Promise<Prepared> => {\n        if (context.type === digestType) return { deferred: new Map() };\n\n        return {\n          deferred: await windowFor(\n            context.recipients.map((recipient) => recipient.userId),\n            context.type,\n          ),\n        };\n      },\n\n      resolveChannels: (context: ResolveChannelsContext) => {\n        const prepared = context.prepared as Prepared | undefined;\n        if (!prepared?.deferred.has(context.recipient.userId)) return context.decisions;\n\n        return context.decisions.map((decision) =>\n          decision.channel === channel ? { ...decision, action: \"skip\" as const } : decision,\n        );\n      },\n\n      // The only hook that sees notification ids.\n      afterSend: async (context: AfterSendContext) => {\n        const prepared = context.prepared as Prepared | undefined;\n        if (!prepared || prepared.deferred.size === 0) return;\n\n        const entries = context.notifications\n          .filter((notification) => prepared.deferred.has(notification.userId))\n          .map((notification) => ({\n            id: crypto.randomUUID(),\n            userId: notification.userId,\n            type: context.type,\n            notificationId: notification.id,\n            payload: context.payload,\n            window: prepared.deferred.get(notification.userId) as DigestWindow,\n            createdAt: new Date(),\n          }));\n\n        if (entries.length > 0) await ctx.store.insert(ENTRY, entries);\n      },\n    },\n\n    routes: [\n      {\n        /**\n         * Point an hourly cron here. Hourly rather than daily because \"9am\"\n         * is 24 different UTC moments, and which ones shift with DST.\n         */\n        path: \"/digests/cron\",\n        method: \"POST\",\n        scope: { type: \"machine\" },\n        handler: async () => {\n          const now = new Date();\n\n          const pending = await ctx.store.find<DigestEntry>(ENTRY, {}, { limit: 10_000 });\n          if (pending.length === 0) return Response.json({ sent: 0, users: 0 });\n\n          const byUser = new Map<string, DigestEntry[]>();\n          for (const entry of pending) {\n            const bucket = byUser.get(entry.userId);\n            if (bucket) bucket.push(entry);\n            else byUser.set(entry.userId, [entry]);\n          }\n\n          const userIds = [...byUser.keys()].slice(0, maxUsersPerRun);\n          const recipients = await ctx.getRecipients(userIds);\n          const zones = new Map(recipients.map((r) => [r.userId, r.timezone]));\n\n          const states = await ctx.store.find<{\n            userId: string;\n            window: DigestWindow;\n            lastPeriod: string;\n          }>(STATE, { userId: { in: userIds } });\n\n          const lastPeriods = new Map(states.map((s) => [`${s.userId} ${s.window}`, s.lastPeriod]));\n\n          let sent = 0;\n\n          for (const userId of userIds) {\n            const entries = byUser.get(userId) ?? [];\n            const moment = localMoment(zones.get(userId) ?? \"UTC\", now);\n\n            for (const window of [\"daily\", \"weekly\"] as const) {\n              const forWindow = entries.filter((entry) => entry.window === window);\n              if (forWindow.length === 0) continue;\n\n              const period = periodKey(window, moment, sendWeekday);\n              // The schedule is idempotent on this comparison, not on timing:\n              // a cron that runs twice in an hour cannot send twice.\n              if (lastPeriods.get(`${userId} ${window}`) === period) continue;\n              if (!isDue(window, moment, sendHour, sendWeekday)) continue;\n\n              await ctx.send(digestType, {\n                to: userId,\n                payload: {\n                  window,\n                  period,\n                  items: forWindow.map((entry) => ({\n                    type: entry.type,\n                    payload: entry.payload,\n                    createdAt: entry.createdAt,\n                  })),\n                },\n                dedupeKey: `digest:${window}:${period}:${userId}`,\n              });\n\n              await ctx.store.upsert(\n                STATE,\n                [{ userId, window, lastPeriod: period, updatedAt: new Date() }],\n                { onConflict: [\"userId\", \"window\"] },\n              );\n\n              // Only after the send is recorded, so a crash re-sends rather\n              // than dropping the batch.\n              await ctx.store.remove(ENTRY, {\n                id: { in: forWindow.map((entry) => entry.id) },\n              });\n\n              sent += 1;\n            }\n          }\n\n          return Response.json({ sent, users: userIds.length });\n        },\n      },\n    ],\n  };\n}\n\nexport type { DigestWindow, LocalMoment } from \"./schedule\";\nexport { isDue, localMoment, periodKey } from \"./schedule\";\n"]}

package/dist/plugins/digests.d.cts

@@ -0,0 +1,68 @@
+import { h as EasyPingPlugin } from '../plugin-Bqj9xAOS.cjs';
+import '../adapter-f0OR2DhY.cjs';
+
+type DigestWindow = "daily" | "weekly";
+type LocalMoment = {
+    /** YYYY-MM-DD in the recipient's zone. */
+    date: string;
+    hour: number;
+    /** 0 = Sunday. */
+    weekday: number;
+};
+/**
+ * Reads the wall clock in a recipient's zone.
+ *
+ * hourCycle h23 rather than hour12:false — the latter renders midnight as "24"
+ * in several locales, which silently makes the send-hour comparison wrong for
+ * one hour a day.
+ */
+declare function localMoment(timezone: string, now: Date): LocalMoment;
+/**
+ * Identifies the digest period a moment falls in.
+ *
+ * Scheduling keys off this string rather than bucketing users by UTC offset.
+ * Offsets shift twice a year, and getting that wrong sends someone two digests
+ * or none. A period key cannot: it is derived from the local calendar, so DST
+ * is already accounted for and a missed cron run simply catches up.
+ */
+declare function periodKey(window: DigestWindow, moment: LocalMoment, sendWeekday: number): string;
+/** Whether the send moment for the current period has arrived. */
+declare function isDue(window: DigestWindow, moment: LocalMoment, sendHour: number, sendWeekday: number): boolean;
+
+type DigestEntry = {
+    id: string;
+    userId: string;
+    type: string;
+    notificationId: string;
+    payload: unknown;
+    window: DigestWindow;
+    createdAt: Date;
+};
+type DigestsOptions = {
+    /**
+     * The notification type the composed digest is sent as. The app defines it
+     * with an email template taking `{ items }`.
+     */
+    digestType?: string;
+    /** Local hour at which a digest becomes due. */
+    sendHour?: number;
+    /** Weekly digests only; 0 = Sunday. */
+    sendWeekday?: number;
+    /** Channels a digest defers. Only email makes sense today. */
+    channel?: "email";
+    /** Safety valve on one cron run. */
+    maxUsersPerRun?: number;
+};
+/**
+ * Collects notifications a user has chosen to receive on a schedule, then
+ * sends them as one message.
+ *
+ * Deliberately not implemented with `defer`: deferring N emails to 9am sends N
+ * emails at 9am. A digest is one email containing N items, so the channel is
+ * skipped and the item is bucketed instead.
+ *
+ * Depends on `preferences` for the per-type frequency it reads.
+ */
+declare function digests(options?: DigestsOptions): EasyPingPlugin<"digests">;
+
+export { type DigestEntry, type DigestWindow, type DigestsOptions, type LocalMoment, digests, isDue, localMoment, periodKey };

package/dist/plugins/digests.d.ts

@@ -0,0 +1,68 @@
+import { h as EasyPingPlugin } from '../plugin-bTJKmnlq.js';
+import '../adapter-f0OR2DhY.js';
+
+type DigestWindow = "daily" | "weekly";
+type LocalMoment = {
+    /** YYYY-MM-DD in the recipient's zone. */
+    date: string;
+    hour: number;
+    /** 0 = Sunday. */
+    weekday: number;
+};
+/**
+ * Reads the wall clock in a recipient's zone.
+ *
+ * hourCycle h23 rather than hour12:false — the latter renders midnight as "24"
+ * in several locales, which silently makes the send-hour comparison wrong for
+ * one hour a day.
+ */
+declare function localMoment(timezone: string, now: Date): LocalMoment;
+/**
+ * Identifies the digest period a moment falls in.
+ *
+ * Scheduling keys off this string rather than bucketing users by UTC offset.
+ * Offsets shift twice a year, and getting that wrong sends someone two digests
+ * or none. A period key cannot: it is derived from the local calendar, so DST
+ * is already accounted for and a missed cron run simply catches up.
+ */
+declare function periodKey(window: DigestWindow, moment: LocalMoment, sendWeekday: number): string;
+/** Whether the send moment for the current period has arrived. */
+declare function isDue(window: DigestWindow, moment: LocalMoment, sendHour: number, sendWeekday: number): boolean;
+
+type DigestEntry = {
+    id: string;
+    userId: string;
+    type: string;
+    notificationId: string;
+    payload: unknown;
+    window: DigestWindow;
+    createdAt: Date;
+};
+type DigestsOptions = {
+    /**
+     * The notification type the composed digest is sent as. The app defines it
+     * with an email template taking `{ items }`.
+     */
+    digestType?: string;
+    /** Local hour at which a digest becomes due. */
+    sendHour?: number;
+    /** Weekly digests only; 0 = Sunday. */
+    sendWeekday?: number;
+    /** Channels a digest defers. Only email makes sense today. */
+    channel?: "email";
+    /** Safety valve on one cron run. */
+    maxUsersPerRun?: number;
+};
+/**
+ * Collects notifications a user has chosen to receive on a schedule, then
+ * sends them as one message.
+ *
+ * Deliberately not implemented with `defer`: deferring N emails to 9am sends N
+ * emails at 9am. A digest is one email containing N items, so the channel is
+ * skipped and the item is bucketed instead.
+ *
+ * Depends on `preferences` for the per-type frequency it reads.
+ */
+declare function digests(options?: DigestsOptions): EasyPingPlugin<"digests">;
+
+export { type DigestEntry, type DigestWindow, type DigestsOptions, type LocalMoment, digests, isDue, localMoment, periodKey };