easy-ping 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,10 +1,12 @@
-import { C as Channel, b as DeliveryMode, S as SkipReason, c as DeliveryRecord, D as DatabaseAdapter, R as Recipient } from './adapter-BfLe2J0t.cjs';
-export { d as ClaimArgs, e as ClaimedDelivery, f as DeliveryOutcome, g as DeliveryRelease, a as DeliveryStatus, h as FeedPage, i as FeedQuery, F as Frequency, I as InsertDelivery, j as InsertNotification, N as NotificationRecord, P as PreferenceRecord } from './adapter-BfLe2J0t.cjs';
+import { C as Channel, b as DeliveryMode, S as SkipReason, c as DeliveryRecord, D as DatabaseAdapter, R as Recipient } from './adapter-D3lTy-4E.cjs';
+export { d as ClaimArgs, e as ClaimedDelivery, f as DeliveryOutcome, g as DeliveryRelease, a as DeliveryStatus, h as FeedPage, i as FeedQuery, F as Frequency, I as InsertDelivery, j as InsertNotification, N as NotificationRecord, P as PreferenceRecord } from './adapter-D3lTy-4E.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { R as RouteScope, A as AnyPlugin, P as Promisable, L as Logger } from './plugin-CiMsGlQe.cjs';
-export { a as ActionsOf, b as AfterDeliverContext, c as AnyClientPlugin, B as BeforeSendContext, d as BeforeSendResult, C as ChannelDecision, e as ClientFetch, f as ClientPlugin, g as ConfigError, D as DEFAULT_TOKEN_TTL_SECONDS, E as EasyPingError, h as EasyPingPlugin, F as FieldDeclaration, i as FieldType, M as MAX_TOKEN_TTL_SECONDS, j as PluginHooks, k as PrepareContext, l as ResolveChannelsContext, m as RouteContext, n as RouteDefinition, S as SchemaDeclaration, o as SignRequest, T as TableDeclaration, p as TokenClaims, U as UnionToIntersection, V as ValidationError, q as consoleLogger, r as defineClientPlugin, s as definePlugin, t as expiresIn, u as signToken, v as verifyToken } from './plugin-CiMsGlQe.cjs';
+import { R as RouteScope, A as AnyPlugin, P as Promisable, L as Logger } from './plugin-CHd2ZiGC.cjs';
+export { a as ActionsOf, b as AfterDeliverContext, c as AnyClientPlugin, B as BeforeSendContext, d as BeforeSendResult, C as ChannelDecision, e as ClientFetch, f as ClientPlugin, g as ConfigError, D as DEFAULT_TOKEN_TTL_SECONDS, E as EasyPingError, h as EasyPingPlugin, F as FieldDeclaration, i as FieldType, M as MAX_TOKEN_TTL_SECONDS, j as PluginHooks, k as PrepareContext, l as ResolveChannelsContext, m as RouteContext, n as RouteDefinition, S as SchemaDeclaration, o as SignRequest, T as TableDeclaration, p as TokenClaims, U as UnionToIntersection, V as ValidationError, q as consoleLogger, r as defineClientPlugin, s as definePlugin, t as expiresIn, u as signToken, v as verifyToken } from './plugin-CHd2ZiGC.cjs';
 import { E as EmailProvider } from './provider-CA45WVqt.cjs';
 export { a as EmailMessage, P as ProviderSendResult } from './provider-CA45WVqt.cjs';
+import { S as Signals } from './signals-kPmOlKDX.cjs';
+export { D as DELIVERIES_CHANNEL, c as createBridgedSignals, a as createMemorySignals, i as inboxChannel } from './signals-kPmOlKDX.cjs';
 
 declare function encodeBase64Url(input: string | Uint8Array): string;
 declare function decodeBase64Url(value: string): string | null;
@@ -23,10 +25,7 @@ type NotificationDefinition<TSchema extends StandardSchemaV1 | undefined = Stand
 };
 /** Binds TSchema so email callbacks infer the payload; TS cannot infer from a sibling property. */
 declare function defineNotification<TSchema extends StandardSchemaV1 | undefined = undefined>(definition: NotificationDefinition<TSchema>): NotificationDefinition<TSchema>;
-/**
- * Erased form. `EmailTemplate<never>` because callbacks are contravariant —
- * anything else makes every schema-typed definition fail to assign.
- */
+/** Erased form. `EmailTemplate<never>` because callbacks are contravariant. */
 type AnyNotificationDefinition = {
     schema?: StandardSchemaV1 | undefined;
     channels: readonly Channel[];
@@ -42,19 +41,10 @@ type RateLimitConfig = {
     /** Requests allowed per key per window. */
     max: number;
     windowMs: number;
-    /**
-     * Which bucket a request lands in. Defaults to the client address as the
-     * usual proxy headers report it; returning null exempts the request. Behind
-     * no proxy those headers are absent, so supply your own key there.
-     */
+    /** Bucket key. Defaults to the client address from proxy headers; null exempts the request. */
     key?: (request: Request) => string | null;
 };
-/**
- * Fixed-window counter held in process memory. Per isolate on edge runtimes
- * and per replica anywhere else, so it bounds one client's cost to one
- * process rather than enforcing a global quota. That is enough to blunt
- * secret guessing and poll storms, which is what it is for.
- */
+/** Fixed window in process memory: per isolate or replica, so a bound rather than a quota. */
 declare function createRateLimiter(config: RateLimitConfig): (request: Request) => Response | null;
 
 type SessionConfig = {
@@ -70,11 +60,28 @@ type DeliveryConfig = {
     /** inline mode only. */
     throwOnError?: boolean;
     backoff?: "exponential" | ((attempt: number) => number);
+    /** Next.js `after` or Cloudflare `ctx.waitUntil`. Injected, not detected. */
+    waitUntil?: (promise: Promise<unknown>) => void;
     /**
-     * Next.js `after`, Cloudflare `ctx.waitUntil`, or @vercel/functions.
-     * Injected, not detected: importing a maybe-absent package breaks bundlers.
+     * Run one small claim-and-deliver pass after any request the handler serves,
+     * at most once per `everyMs` per process. Delivery then rides on your own
+     * traffic and the cron becomes a backstop. Ignored in `inline` mode. RFC 0006 idea 5.
      */
-    waitUntil?: (promise: Promise<unknown>) => void;
+    sweepOnRequest?: true | {
+        everyMs?: number;
+        limit?: number;
+    };
+};
+type EventsConfig = {
+    /** Comment line keeping proxies from closing an idle stream. Default 25 s. */
+    heartbeatMs?: number;
+    /**
+     * Without a cross-process signal source, each stream checks the database
+     * for changes this often on its subscriber's behalf. Default 30 s; 0 disables.
+     */
+    probeIntervalMs?: number;
+    /** Close the stream after this long; the client reconnects. 0 (default) leaves it open. */
+    maxDurationMs?: number;
 };
 type ChannelsConfig = {
     inApp?: {
@@ -99,25 +106,22 @@ type EasyPingConfig<TDefs extends NotificationDefinitions> = {
         /** Sweeps one POST /cron may run before returning. Defaults to 50. */
         maxSweeps?: number;
     };
-    /**
-     * Bearer secret for plugins' machine routes (`/push/prune`, `/digests/cron`).
-     * Falls back to `cron.secret`; set it when the scheduler that hits /cron
-     * should not also be able to prune devices or fire digests.
-     */
+    /** Bearer secret for plugin machine routes. Falls back to `cron.secret`. */
     machineSecret?: string;
+    /** In-process fixed-window limiter, applied before routing. */
+    rateLimit?: RateLimitConfig;
     /**
-     * In-process fixed-window limiter, applied before routing. Keyed by client
-     * address from the usual proxy headers unless `key` says otherwise.
+     * How "something changed" travels between the sender, the worker and open
+     * event streams. Defaults to in-process. Supply a LISTEN/NOTIFY or change
+     * stream implementation to cross replicas. RFC 0006 §4C.
      */
-    rateLimit?: RateLimitConfig;
+    signals?: Signals;
+    /** `GET /events`, a Server-Sent Events stream per user. `false` unmounts it. */
+    events?: EventsConfig | false;
     plugins?: readonly AnyPlugin[];
     /** Where the handler is mounted, used to strip the prefix off incoming URLs. */
     basePath?: string;
-    /**
-     * Origins allowed to POST besides the request's own host. Cross-origin
-     * POSTs are otherwise refused with 403, and every POST must be
-     * `application/json`. `"*.example.com"` matches subdomains.
-     */
+    /** Origins other than the request host that may POST. `"*.example.com"` matches subdomains. */
     trustedOrigins?: readonly string[];
     /** Runs before routing. Return a Response to short-circuit — a rate limiter's 429, say. */
     onRequest?: (request: Request) => Promisable<Response | undefined | void>;
@@ -167,6 +171,8 @@ type HealthReport = {
     cronRequiredButMissing: boolean;
     warnings: readonly string[];
 };
+/** Response header carrying a per-user inbox version, so app traffic can replace polling. */
+declare const INBOX_VERSION_HEADER = "x-easy-ping-inbox";
 type EasyPing<TDefs extends NotificationDefinitions> = {
     send<TKey extends keyof TDefs & string>(type: TKey, args: SendArgs<TDefs, TKey>): Promise<SendResult>;
     handler: {
@@ -175,6 +181,7 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
         GET: (request: Request) => Promise<Response>;
         POST: (request: Request) => Promise<Response>;
     };
+    /** Idle interval defaults to 10 s; a send in this process wakes the loop at once. */
     startWorker(options?: {
         intervalMs?: number;
         batchSize?: number;
@@ -183,12 +190,12 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
     /** Every mounted route with its auth scope, so `custom`-scoped ones stay visible. RFC 0002 §3. */
     listRoutes(): readonly MountedRoute[];
     /**
-     * Deliveries that exhausted their attempts, newest first.
-     *
-     * The retry machinery is otherwise a black box: rows go quiet and the only
-     * way to ask what happened is SQL against tables the library owns. Wire this
-     * to an admin page or an alert.
+     * Headers to attach to any response your app sends this user. The client's
+     * `instrument(fetch)` reads them and refreshes only when the version moved,
+     * so an active user never needs a dedicated poll. RFC 0006 idea 1.
      */
+    inboxHeaders(userId: string): Record<string, string>;
+    /** Deliveries that exhausted their attempts, newest first. Wire it to an admin page or an alert. */
     getFailedDeliveries(options?: {
         /** Defaults to the last 24 hours. */
         since?: Date;
@@ -209,6 +216,8 @@ type RunnerDeps = {
     leaseMs: number;
     batchSize: number;
     backoff: Backoff;
+    /** Wakes an idle worker the moment a send commits, so the idle interval can be long. */
+    signals?: Signals | undefined;
 };
 type SweepResult = {
     claimed: number;
@@ -217,11 +226,7 @@ type SweepResult = {
     /** Deliveries that had nothing to do. Not errors; see DeliveryOutcome. */
     skipped: number;
 };
-/**
- * What gets persisted to `last_error`. Provider responses quote the offending
- * field, which for a bad recipient is the address itself; that column outlives
- * the notification and is read by admin tooling, so addresses do not go in.
- */
+/** Persisted to `last_error`, which admin tooling reads: addresses do not go in. */
 declare const redactErrorMessage: (text: string) => string;
 declare function createRunner(deps: RunnerDeps): {
     runOnce: (options?: {
@@ -248,22 +253,13 @@ type JsonBody = {
 } | {
     error: Response;
 };
-/**
- * Reads a JSON object body with a byte cap enforced while streaming, so an
- * oversized body is refused before it is buffered. Malformed JSON is 400; an
- * empty body is `{}`. Plugin routes should use this rather than
- * `request.json()`, which has no limit.
- */
+/** Reads a JSON object body with a streaming byte cap. Malformed JSON is 400; an empty body is `{}`. */
 declare function readJsonBody(request: Request, maxBytes?: number): Promise<JsonBody>;
 
-/**
- * For email templates built with template literals. Anything in a payload
- * that a user typed — a display name, a comment excerpt — goes through this
- * or the recipient gets that user's HTML delivered from your sending domain.
- */
+/** For template literals: anything a user typed goes through this, or their HTML ships from your domain. */
 declare const escapeHtml: (value: unknown) => string;
 
 declare const MIN_SECRET_LENGTH = 16;
 declare function easyPing<TDefs extends NotificationDefinitions>(config: EasyPingConfig<TDefs>): EasyPing<TDefs>;
 
-export { type AnyNotificationDefinition, AnyPlugin, Channel, type ChannelsConfig, DatabaseAdapter, type DeliveryConfig, DeliveryMode, DeliveryRecord, type EasyPing, type EasyPingConfig, EmailProvider, type EmailTemplate, type HealthReport, type JsonBody, Logger, MAX_BODY_BYTES, MIN_SECRET_LENGTH, type MountedRoute, type NotificationDefinition, type NotificationDefinitions, type PayloadFromSchema, type PayloadOf, Promisable, type RateLimitConfig, Recipient, RouteScope, type Runner, type RunnerDeps, type SendArgs, type SendResult, type SessionConfig, SkipReason, type SweepResult, type Worker, createRateLimiter, createRunner, decodeBase64Url, defineNotification, easyPing, encodeBase64Url, escapeHtml, readJsonBody, redactErrorMessage };
+export { type AnyNotificationDefinition, AnyPlugin, Channel, type ChannelsConfig, DatabaseAdapter, type DeliveryConfig, DeliveryMode, DeliveryRecord, type EasyPing, type EasyPingConfig, EmailProvider, type EmailTemplate, type EventsConfig, type HealthReport, INBOX_VERSION_HEADER, type JsonBody, Logger, MAX_BODY_BYTES, MIN_SECRET_LENGTH, type MountedRoute, type NotificationDefinition, type NotificationDefinitions, type PayloadFromSchema, type PayloadOf, Promisable, type RateLimitConfig, Recipient, RouteScope, type Runner, type RunnerDeps, type SendArgs, type SendResult, type SessionConfig, Signals, SkipReason, type SweepResult, type Worker, createRateLimiter, createRunner, decodeBase64Url, defineNotification, easyPing, encodeBase64Url, escapeHtml, readJsonBody, redactErrorMessage };

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-import { C as Channel, b as DeliveryMode, S as SkipReason, c as DeliveryRecord, D as DatabaseAdapter, R as Recipient } from './adapter-BfLe2J0t.js';
-export { d as ClaimArgs, e as ClaimedDelivery, f as DeliveryOutcome, g as DeliveryRelease, a as DeliveryStatus, h as FeedPage, i as FeedQuery, F as Frequency, I as InsertDelivery, j as InsertNotification, N as NotificationRecord, P as PreferenceRecord } from './adapter-BfLe2J0t.js';
+import { C as Channel, b as DeliveryMode, S as SkipReason, c as DeliveryRecord, D as DatabaseAdapter, R as Recipient } from './adapter-D3lTy-4E.js';
+export { d as ClaimArgs, e as ClaimedDelivery, f as DeliveryOutcome, g as DeliveryRelease, a as DeliveryStatus, h as FeedPage, i as FeedQuery, F as Frequency, I as InsertDelivery, j as InsertNotification, N as NotificationRecord, P as PreferenceRecord } from './adapter-D3lTy-4E.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { R as RouteScope, A as AnyPlugin, P as Promisable, L as Logger } from './plugin-C9Hoxus2.js';
-export { a as ActionsOf, b as AfterDeliverContext, c as AnyClientPlugin, B as BeforeSendContext, d as BeforeSendResult, C as ChannelDecision, e as ClientFetch, f as ClientPlugin, g as ConfigError, D as DEFAULT_TOKEN_TTL_SECONDS, E as EasyPingError, h as EasyPingPlugin, F as FieldDeclaration, i as FieldType, M as MAX_TOKEN_TTL_SECONDS, j as PluginHooks, k as PrepareContext, l as ResolveChannelsContext, m as RouteContext, n as RouteDefinition, S as SchemaDeclaration, o as SignRequest, T as TableDeclaration, p as TokenClaims, U as UnionToIntersection, V as ValidationError, q as consoleLogger, r as defineClientPlugin, s as definePlugin, t as expiresIn, u as signToken, v as verifyToken } from './plugin-C9Hoxus2.js';
+import { R as RouteScope, A as AnyPlugin, P as Promisable, L as Logger } from './plugin-Cg9usuUi.js';
+export { a as ActionsOf, b as AfterDeliverContext, c as AnyClientPlugin, B as BeforeSendContext, d as BeforeSendResult, C as ChannelDecision, e as ClientFetch, f as ClientPlugin, g as ConfigError, D as DEFAULT_TOKEN_TTL_SECONDS, E as EasyPingError, h as EasyPingPlugin, F as FieldDeclaration, i as FieldType, M as MAX_TOKEN_TTL_SECONDS, j as PluginHooks, k as PrepareContext, l as ResolveChannelsContext, m as RouteContext, n as RouteDefinition, S as SchemaDeclaration, o as SignRequest, T as TableDeclaration, p as TokenClaims, U as UnionToIntersection, V as ValidationError, q as consoleLogger, r as defineClientPlugin, s as definePlugin, t as expiresIn, u as signToken, v as verifyToken } from './plugin-Cg9usuUi.js';
 import { E as EmailProvider } from './provider-CA45WVqt.js';
 export { a as EmailMessage, P as ProviderSendResult } from './provider-CA45WVqt.js';
+import { S as Signals } from './signals-kPmOlKDX.js';
+export { D as DELIVERIES_CHANNEL, c as createBridgedSignals, a as createMemorySignals, i as inboxChannel } from './signals-kPmOlKDX.js';
 
 declare function encodeBase64Url(input: string | Uint8Array): string;
 declare function decodeBase64Url(value: string): string | null;
@@ -23,10 +25,7 @@ type NotificationDefinition<TSchema extends StandardSchemaV1 | undefined = Stand
 };
 /** Binds TSchema so email callbacks infer the payload; TS cannot infer from a sibling property. */
 declare function defineNotification<TSchema extends StandardSchemaV1 | undefined = undefined>(definition: NotificationDefinition<TSchema>): NotificationDefinition<TSchema>;
-/**
- * Erased form. `EmailTemplate<never>` because callbacks are contravariant —
- * anything else makes every schema-typed definition fail to assign.
- */
+/** Erased form. `EmailTemplate<never>` because callbacks are contravariant. */
 type AnyNotificationDefinition = {
     schema?: StandardSchemaV1 | undefined;
     channels: readonly Channel[];
@@ -42,19 +41,10 @@ type RateLimitConfig = {
     /** Requests allowed per key per window. */
     max: number;
     windowMs: number;
-    /**
-     * Which bucket a request lands in. Defaults to the client address as the
-     * usual proxy headers report it; returning null exempts the request. Behind
-     * no proxy those headers are absent, so supply your own key there.
-     */
+    /** Bucket key. Defaults to the client address from proxy headers; null exempts the request. */
     key?: (request: Request) => string | null;
 };
-/**
- * Fixed-window counter held in process memory. Per isolate on edge runtimes
- * and per replica anywhere else, so it bounds one client's cost to one
- * process rather than enforcing a global quota. That is enough to blunt
- * secret guessing and poll storms, which is what it is for.
- */
+/** Fixed window in process memory: per isolate or replica, so a bound rather than a quota. */
 declare function createRateLimiter(config: RateLimitConfig): (request: Request) => Response | null;
 
 type SessionConfig = {
@@ -70,11 +60,28 @@ type DeliveryConfig = {
     /** inline mode only. */
     throwOnError?: boolean;
     backoff?: "exponential" | ((attempt: number) => number);
+    /** Next.js `after` or Cloudflare `ctx.waitUntil`. Injected, not detected. */
+    waitUntil?: (promise: Promise<unknown>) => void;
     /**
-     * Next.js `after`, Cloudflare `ctx.waitUntil`, or @vercel/functions.
-     * Injected, not detected: importing a maybe-absent package breaks bundlers.
+     * Run one small claim-and-deliver pass after any request the handler serves,
+     * at most once per `everyMs` per process. Delivery then rides on your own
+     * traffic and the cron becomes a backstop. Ignored in `inline` mode. RFC 0006 idea 5.
      */
-    waitUntil?: (promise: Promise<unknown>) => void;
+    sweepOnRequest?: true | {
+        everyMs?: number;
+        limit?: number;
+    };
+};
+type EventsConfig = {
+    /** Comment line keeping proxies from closing an idle stream. Default 25 s. */
+    heartbeatMs?: number;
+    /**
+     * Without a cross-process signal source, each stream checks the database
+     * for changes this often on its subscriber's behalf. Default 30 s; 0 disables.
+     */
+    probeIntervalMs?: number;
+    /** Close the stream after this long; the client reconnects. 0 (default) leaves it open. */
+    maxDurationMs?: number;
 };
 type ChannelsConfig = {
     inApp?: {
@@ -99,25 +106,22 @@ type EasyPingConfig<TDefs extends NotificationDefinitions> = {
         /** Sweeps one POST /cron may run before returning. Defaults to 50. */
         maxSweeps?: number;
     };
-    /**
-     * Bearer secret for plugins' machine routes (`/push/prune`, `/digests/cron`).
-     * Falls back to `cron.secret`; set it when the scheduler that hits /cron
-     * should not also be able to prune devices or fire digests.
-     */
+    /** Bearer secret for plugin machine routes. Falls back to `cron.secret`. */
     machineSecret?: string;
+    /** In-process fixed-window limiter, applied before routing. */
+    rateLimit?: RateLimitConfig;
     /**
-     * In-process fixed-window limiter, applied before routing. Keyed by client
-     * address from the usual proxy headers unless `key` says otherwise.
+     * How "something changed" travels between the sender, the worker and open
+     * event streams. Defaults to in-process. Supply a LISTEN/NOTIFY or change
+     * stream implementation to cross replicas. RFC 0006 §4C.
      */
-    rateLimit?: RateLimitConfig;
+    signals?: Signals;
+    /** `GET /events`, a Server-Sent Events stream per user. `false` unmounts it. */
+    events?: EventsConfig | false;
     plugins?: readonly AnyPlugin[];
     /** Where the handler is mounted, used to strip the prefix off incoming URLs. */
     basePath?: string;
-    /**
-     * Origins allowed to POST besides the request's own host. Cross-origin
-     * POSTs are otherwise refused with 403, and every POST must be
-     * `application/json`. `"*.example.com"` matches subdomains.
-     */
+    /** Origins other than the request host that may POST. `"*.example.com"` matches subdomains. */
     trustedOrigins?: readonly string[];
     /** Runs before routing. Return a Response to short-circuit — a rate limiter's 429, say. */
     onRequest?: (request: Request) => Promisable<Response | undefined | void>;
@@ -167,6 +171,8 @@ type HealthReport = {
     cronRequiredButMissing: boolean;
     warnings: readonly string[];
 };
+/** Response header carrying a per-user inbox version, so app traffic can replace polling. */
+declare const INBOX_VERSION_HEADER = "x-easy-ping-inbox";
 type EasyPing<TDefs extends NotificationDefinitions> = {
     send<TKey extends keyof TDefs & string>(type: TKey, args: SendArgs<TDefs, TKey>): Promise<SendResult>;
     handler: {
@@ -175,6 +181,7 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
         GET: (request: Request) => Promise<Response>;
         POST: (request: Request) => Promise<Response>;
     };
+    /** Idle interval defaults to 10 s; a send in this process wakes the loop at once. */
     startWorker(options?: {
         intervalMs?: number;
         batchSize?: number;
@@ -183,12 +190,12 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
     /** Every mounted route with its auth scope, so `custom`-scoped ones stay visible. RFC 0002 §3. */
     listRoutes(): readonly MountedRoute[];
     /**
-     * Deliveries that exhausted their attempts, newest first.
-     *
-     * The retry machinery is otherwise a black box: rows go quiet and the only
-     * way to ask what happened is SQL against tables the library owns. Wire this
-     * to an admin page or an alert.
+     * Headers to attach to any response your app sends this user. The client's
+     * `instrument(fetch)` reads them and refreshes only when the version moved,
+     * so an active user never needs a dedicated poll. RFC 0006 idea 1.
      */
+    inboxHeaders(userId: string): Record<string, string>;
+    /** Deliveries that exhausted their attempts, newest first. Wire it to an admin page or an alert. */
     getFailedDeliveries(options?: {
         /** Defaults to the last 24 hours. */
         since?: Date;
@@ -209,6 +216,8 @@ type RunnerDeps = {
     leaseMs: number;
     batchSize: number;
     backoff: Backoff;
+    /** Wakes an idle worker the moment a send commits, so the idle interval can be long. */
+    signals?: Signals | undefined;
 };
 type SweepResult = {
     claimed: number;
@@ -217,11 +226,7 @@ type SweepResult = {
     /** Deliveries that had nothing to do. Not errors; see DeliveryOutcome. */
     skipped: number;
 };
-/**
- * What gets persisted to `last_error`. Provider responses quote the offending
- * field, which for a bad recipient is the address itself; that column outlives
- * the notification and is read by admin tooling, so addresses do not go in.
- */
+/** Persisted to `last_error`, which admin tooling reads: addresses do not go in. */
 declare const redactErrorMessage: (text: string) => string;
 declare function createRunner(deps: RunnerDeps): {
     runOnce: (options?: {
@@ -248,22 +253,13 @@ type JsonBody = {
 } | {
     error: Response;
 };
-/**
- * Reads a JSON object body with a byte cap enforced while streaming, so an
- * oversized body is refused before it is buffered. Malformed JSON is 400; an
- * empty body is `{}`. Plugin routes should use this rather than
- * `request.json()`, which has no limit.
- */
+/** Reads a JSON object body with a streaming byte cap. Malformed JSON is 400; an empty body is `{}`. */
 declare function readJsonBody(request: Request, maxBytes?: number): Promise<JsonBody>;
 
-/**
- * For email templates built with template literals. Anything in a payload
- * that a user typed — a display name, a comment excerpt — goes through this
- * or the recipient gets that user's HTML delivered from your sending domain.
- */
+/** For template literals: anything a user typed goes through this, or their HTML ships from your domain. */
 declare const escapeHtml: (value: unknown) => string;
 
 declare const MIN_SECRET_LENGTH = 16;
 declare function easyPing<TDefs extends NotificationDefinitions>(config: EasyPingConfig<TDefs>): EasyPing<TDefs>;
 
-export { type AnyNotificationDefinition, AnyPlugin, Channel, type ChannelsConfig, DatabaseAdapter, type DeliveryConfig, DeliveryMode, DeliveryRecord, type EasyPing, type EasyPingConfig, EmailProvider, type EmailTemplate, type HealthReport, type JsonBody, Logger, MAX_BODY_BYTES, MIN_SECRET_LENGTH, type MountedRoute, type NotificationDefinition, type NotificationDefinitions, type PayloadFromSchema, type PayloadOf, Promisable, type RateLimitConfig, Recipient, RouteScope, type Runner, type RunnerDeps, type SendArgs, type SendResult, type SessionConfig, SkipReason, type SweepResult, type Worker, createRateLimiter, createRunner, decodeBase64Url, defineNotification, easyPing, encodeBase64Url, escapeHtml, readJsonBody, redactErrorMessage };
+export { type AnyNotificationDefinition, AnyPlugin, Channel, type ChannelsConfig, DatabaseAdapter, type DeliveryConfig, DeliveryMode, DeliveryRecord, type EasyPing, type EasyPingConfig, EmailProvider, type EmailTemplate, type EventsConfig, type HealthReport, INBOX_VERSION_HEADER, type JsonBody, Logger, MAX_BODY_BYTES, MIN_SECRET_LENGTH, type MountedRoute, type NotificationDefinition, type NotificationDefinitions, type PayloadFromSchema, type PayloadOf, Promisable, type RateLimitConfig, Recipient, RouteScope, type Runner, type RunnerDeps, type SendArgs, type SendResult, type SessionConfig, Signals, SkipReason, type SweepResult, type Worker, createRateLimiter, createRunner, decodeBase64Url, defineNotification, easyPing, encodeBase64Url, escapeHtml, readJsonBody, redactErrorMessage };

package/dist/index.js

@@ -1,12 +1,17 @@
-import { createRunner } from './chunk-CYKAM7LE.js';
-export { createRunner, redactErrorMessage } from './chunk-CYKAM7LE.js';
-export { defineClientPlugin, definePlugin } from './chunk-W6I3B2CI.js';
-import { createHandler, createScopedSigner } from './chunk-DG3ZL5NP.js';
-export { DEFAULT_TOKEN_TTL_SECONDS, MAX_BODY_BYTES, MAX_TOKEN_TTL_SECONDS, expiresIn, readJsonBody, signToken, verifyToken } from './chunk-DG3ZL5NP.js';
-import { consoleLogger, ConfigError, createPluginStore, ValidationError } from './chunk-3Y2MBUAW.js';
-export { ConfigError, EasyPingError, ValidationError, consoleLogger } from './chunk-3Y2MBUAW.js';
+import { createRunner } from './chunk-JKTMUMQK.js';
+export { createRunner, redactErrorMessage } from './chunk-JKTMUMQK.js';
+export { defineClientPlugin, definePlugin } from './chunk-E4IZ2CQC.js';
+import { createHandler, createScopedSigner } from './chunk-USQ6CQTJ.js';
+export { DEFAULT_TOKEN_TTL_SECONDS, MAX_BODY_BYTES, MAX_TOKEN_TTL_SECONDS, expiresIn, readJsonBody, signToken, verifyToken } from './chunk-USQ6CQTJ.js';
+import { createMemorySignals, inboxChannel, DELIVERIES_CHANNEL } from './chunk-ORZKH224.js';
+export { DELIVERIES_CHANNEL, createBridgedSignals, createMemorySignals, inboxChannel } from './chunk-ORZKH224.js';
+import { consoleLogger, ConfigError, createPluginStore, ValidationError } from './chunk-3VOQOGDR.js';
+export { ConfigError, EasyPingError, ValidationError, consoleLogger } from './chunk-3VOQOGDR.js';
+import './chunk-AEYYTE5I.js';
 export { decodeBase64Url, encodeBase64Url } from './chunk-PTGHMCCG.js';
-import './chunk-PSJHXZPR.js';
+
+// src/core/config.ts
+var INBOX_VERSION_HEADER = "x-easy-ping-inbox";
 
 // src/core/definition.ts
 function defineNotification(definition) {
@@ -197,8 +202,7 @@ async function runSend(type, input, deps) {
       id: newId(),
       channel: decision.channel,
       maxAttempts: definition.maxAttempts ?? deps.maxAttempts,
-      // `defer` needs no machinery beyond not_before — the claim query
-      // already refuses rows whose time has not come. RFC 0004 §4.2.
+      // defer is just not_before; the claim query refuses rows whose time has not come. RFC 0004 §4.2.
       notBefore: decision.action === "defer" && decision.notBefore ? decision.notBefore : now
     }));
     if (deliveries.length === 0) {
@@ -254,6 +258,7 @@ var CORE_ROUTES = [
   { method: "POST", path: "/seen", scope: { type: "user" }, owner: "core" },
   { method: "POST", path: "/read", scope: { type: "user" }, owner: "core" },
   { method: "POST", path: "/read-all", scope: { type: "user" }, owner: "core" },
+  { method: "GET", path: "/events", scope: { type: "user" }, owner: "core" },
   { method: "POST", path: "/cron", scope: { type: "machine" }, owner: "core" }
 ];
 var DEFAULTS = {
@@ -378,6 +383,20 @@ function easyPing(config) {
     }
   }
   for (const warning of warnings) logger.warn(warning);
+  const baseSignals = config.signals ?? createMemorySignals();
+  const inboxVersions = /* @__PURE__ */ new Map();
+  const signals = {
+    crossProcess: baseSignals.crossProcess,
+    publish(channel) {
+      if (channel.startsWith("inbox:")) {
+        if (inboxVersions.size > 5e4) inboxVersions.clear();
+        const userId = channel.slice("inbox:".length);
+        inboxVersions.set(userId, (inboxVersions.get(userId) ?? 0) + 1);
+      }
+      baseSignals.publish(channel);
+    },
+    subscribe: (channel, handler2) => baseSignals.subscribe(channel, handler2)
+  };
   const runner = createRunner({
     adapter: config.database,
     definitions: config.notifications,
@@ -387,15 +406,34 @@ function easyPing(config) {
     logger,
     leaseMs,
     batchSize: config.delivery?.batchSize ?? DEFAULTS.batchSize,
-    backoff: config.delivery?.backoff ?? "exponential"
+    backoff: config.delivery?.backoff ?? "exponential",
+    signals
   });
   const pluginRoutes = plugins.flatMap((plugin) => plugin.routes ?? []);
+  const events = config.events === false ? false : {
+    heartbeatMs: config.events?.heartbeatMs ?? 25e3,
+    probeIntervalMs: config.events?.probeIntervalMs ?? 3e4,
+    maxDurationMs: config.events?.maxDurationMs ?? 0
+  };
+  const sweepConfig = config.delivery?.sweepOnRequest;
+  let lastRequestSweep = 0;
+  const sweepOnRequest = sweepConfig && mode !== "inline" ? () => {
+    const settings = sweepConfig === true ? {} : sweepConfig;
+    const now = Date.now();
+    if (now - lastRequestSweep < (settings.everyMs ?? 5e3)) return;
+    lastRequestSweep = now;
+    const pass = runner.runOnce({ limit: settings.limit ?? 5 }).catch((error) => logger.error("request-driven sweep failed", { error }));
+    config.delivery?.waitUntil?.(pass);
+  } : void 0;
   const handler = createHandler({
     adapter: config.database,
     session: config.session,
     runner,
     logger,
     secret: config.secret,
+    signals,
+    events,
+    sweepOnRequest,
     basePath: config.basePath ?? DEFAULTS.basePath,
     pluginRoutes,
     trustedOrigins: config.trustedOrigins,
@@ -427,6 +465,10 @@ function easyPing(config) {
       }
     );
     if (result.notifications.length > 0) {
+      for (const notification of result.notifications) {
+        signals.publish(inboxChannel(notification.userId));
+      }
+      signals.publish(DELIVERIES_CHANNEL);
       const ids = result.notifications.flatMap(
         (notification) => notification.deliveries.map((delivery) => delivery.id)
       );
@@ -459,8 +501,13 @@ function easyPing(config) {
     send,
     handler,
     startWorker: (options) => runner.startWorker(options ?? {}),
+    inboxHeaders: (userId) => ({
+      [INBOX_VERSION_HEADER]: String(inboxVersions.get(userId) ?? 0)
+    }),
     listRoutes: () => [
-      ...CORE_ROUTES.filter((route) => route.path !== "/cron" || Boolean(config.cron?.secret)),
+      ...CORE_ROUTES.filter(
+        (route) => (route.path !== "/cron" || Boolean(config.cron?.secret)) && (route.path !== "/events" || events !== false)
+      ),
       ...plugins.flatMap(
         (plugin) => (plugin.routes ?? []).map((route) => ({
           method: route.method,
@@ -486,6 +533,6 @@ function easyPing(config) {
   };
 }
 
-export { MIN_SECRET_LENGTH, createRateLimiter, defineNotification, easyPing, escapeHtml };
+export { INBOX_VERSION_HEADER, MIN_SECRET_LENGTH, createRateLimiter, defineNotification, easyPing, escapeHtml };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map