easy-ping 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-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 { A as AnyPlugin, L as Logger } from './plugin-f5KaFWSN.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, E as EasyPingError, h as EasyPingPlugin, F as FieldDeclaration, i as FieldType, P as PluginHooks, j as PrepareContext, k as Promisable, R as ResolveChannelsContext, l as RouteContext, m as RouteDefinition, n as RouteScope, S as SchemaDeclaration, T as TableDeclaration, U as UnionToIntersection, V as ValidationError, o as consoleLogger, p as defineClientPlugin, q as definePlugin } from './plugin-f5KaFWSN.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';
 
@@ -23,10 +23,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[];
@@ -38,6 +35,16 @@ type PayloadOf<TDef> = TDef extends {
     schema: infer TSchema extends StandardSchemaV1;
 } ? StandardSchemaV1.InferOutput<TSchema> : Record<string, unknown>;
 
+type RateLimitConfig = {
+    /** Requests allowed per key per window. */
+    max: number;
+    windowMs: number;
+    /** Bucket key. Defaults to the client address from proxy headers; null exempts the request. */
+    key?: (request: Request) => string | null;
+};
+/** 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 = {
     /** null yields 401; throwing yields 500. Deliberately distinct. */
     getUserId: (request: Request) => string | null | Promise<string | null>;
@@ -51,10 +58,7 @@ type DeliveryConfig = {
     /** inline mode only. */
     throwOnError?: boolean;
     backoff?: "exponential" | ((attempt: number) => number);
-    /**
-     * Next.js `after`, Cloudflare `ctx.waitUntil`, or @vercel/functions.
-     * Injected, not detected: importing a maybe-absent package breaks bundlers.
-     */
+    /** Next.js `after` or Cloudflare `ctx.waitUntil`. Injected, not detected. */
     waitUntil?: (promise: Promise<unknown>) => void;
 };
 type ChannelsConfig = {
@@ -77,10 +81,22 @@ type EasyPingConfig<TDefs extends NotificationDefinitions> = {
     /** Required by `cron` and `deferred` modes. See RFC 0002 §4. */
     cron?: {
         secret: string;
+        /** Sweeps one POST /cron may run before returning. Defaults to 50. */
+        maxSweeps?: number;
     };
+    /** Bearer secret for plugin machine routes. Falls back to `cron.secret`. */
+    machineSecret?: string;
+    /** In-process fixed-window limiter, applied before routing. */
+    rateLimit?: RateLimitConfig;
     plugins?: readonly AnyPlugin[];
     /** Where the handler is mounted, used to strip the prefix off incoming URLs. */
     basePath?: string;
+    /** 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>;
+    /** Defaults to 64 KiB. */
+    maxBodyBytes?: number;
     /** Table-name prefix; must match the one given to the adapter. */
     tablePrefix?: string;
     logger?: Logger;
@@ -111,6 +127,13 @@ type SendResult = {
 type Worker = {
     stop: () => Promise<void>;
 };
+type MountedRoute = {
+    method: "GET" | "POST";
+    path: string;
+    scope: RouteScope;
+    /** "core" for the built-in routes, otherwise the plugin id. */
+    owner: string;
+};
 type HealthReport = {
     mode: DeliveryMode;
     cronMounted: boolean;
@@ -131,13 +154,9 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
         batchSize?: number;
     }): Worker;
     healthCheck(): Promise<HealthReport>;
-    /**
-     * 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.
-     */
+    /** 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. Wire it to an admin page or an alert. */
     getFailedDeliveries(options?: {
         /** Defaults to the last 24 hours. */
         since?: Date;
@@ -146,8 +165,6 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
     }): Promise<readonly DeliveryRecord[]>;
 };
 
-declare function easyPing<TDefs extends NotificationDefinitions>(config: EasyPingConfig<TDefs>): EasyPing<TDefs>;
-
 type Backoff = "exponential" | ((attempt: number) => number);
 
 type RunnerDeps = {
@@ -168,6 +185,8 @@ type SweepResult = {
     /** Deliveries that had nothing to do. Not errors; see DeliveryOutcome. */
     skipped: number;
 };
+/** 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?: {
         limit?: number;
@@ -186,20 +205,20 @@ declare function createRunner(deps: RunnerDeps): {
 };
 type Runner = ReturnType<typeof createRunner>;
 
-type TokenClaims = {
-    /** Subject — the user the token acts for. */
-    uid: string;
-    /** What the token is allowed to do. Verification requires an exact match. */
-    purpose: string;
-    /** Expiry, epoch seconds. */
-    exp: number;
-    /** Free-form, purpose-specific. */
-    data?: Record<string, string>;
-};
-declare function signToken(secret: string, claims: TokenClaims): Promise<string>;
-/** null for every failure mode. Distinguishing them tells an attacker which part to fix. */
-declare function verifyToken(secret: string, token: string, purpose: string, now?: Date): Promise<TokenClaims | null>;
-declare const DEFAULT_TOKEN_TTL_SECONDS: number;
-declare const expiresIn: (seconds: number, now?: Date) => number;
+/** Every JSON body is capped here. Nothing legitimate the routes accept is bigger. */
+declare const MAX_BODY_BYTES: number;
+type JsonBody = {
+    body: Record<string, unknown>;
+} | {
+    error: Response;
+};
+/** 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 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, DEFAULT_TOKEN_TTL_SECONDS, DatabaseAdapter, type DeliveryConfig, DeliveryMode, DeliveryRecord, type EasyPing, type EasyPingConfig, EmailProvider, type EmailTemplate, type HealthReport, Logger, type NotificationDefinition, type NotificationDefinitions, type PayloadFromSchema, type PayloadOf, Recipient, type Runner, type RunnerDeps, type SendArgs, type SendResult, type SessionConfig, SkipReason, type SweepResult, type TokenClaims, type Worker, createRunner, decodeBase64Url, defineNotification, easyPing, encodeBase64Url, expiresIn, signToken, verifyToken };
+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 };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-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 { A as AnyPlugin, L as Logger } from './plugin-CmPOFVmn.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, E as EasyPingError, h as EasyPingPlugin, F as FieldDeclaration, i as FieldType, P as PluginHooks, j as PrepareContext, k as Promisable, R as ResolveChannelsContext, l as RouteContext, m as RouteDefinition, n as RouteScope, S as SchemaDeclaration, T as TableDeclaration, U as UnionToIntersection, V as ValidationError, o as consoleLogger, p as defineClientPlugin, q as definePlugin } from './plugin-CmPOFVmn.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';
 
@@ -23,10 +23,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[];
@@ -38,6 +35,16 @@ type PayloadOf<TDef> = TDef extends {
     schema: infer TSchema extends StandardSchemaV1;
 } ? StandardSchemaV1.InferOutput<TSchema> : Record<string, unknown>;
 
+type RateLimitConfig = {
+    /** Requests allowed per key per window. */
+    max: number;
+    windowMs: number;
+    /** Bucket key. Defaults to the client address from proxy headers; null exempts the request. */
+    key?: (request: Request) => string | null;
+};
+/** 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 = {
     /** null yields 401; throwing yields 500. Deliberately distinct. */
     getUserId: (request: Request) => string | null | Promise<string | null>;
@@ -51,10 +58,7 @@ type DeliveryConfig = {
     /** inline mode only. */
     throwOnError?: boolean;
     backoff?: "exponential" | ((attempt: number) => number);
-    /**
-     * Next.js `after`, Cloudflare `ctx.waitUntil`, or @vercel/functions.
-     * Injected, not detected: importing a maybe-absent package breaks bundlers.
-     */
+    /** Next.js `after` or Cloudflare `ctx.waitUntil`. Injected, not detected. */
     waitUntil?: (promise: Promise<unknown>) => void;
 };
 type ChannelsConfig = {
@@ -77,10 +81,22 @@ type EasyPingConfig<TDefs extends NotificationDefinitions> = {
     /** Required by `cron` and `deferred` modes. See RFC 0002 §4. */
     cron?: {
         secret: string;
+        /** Sweeps one POST /cron may run before returning. Defaults to 50. */
+        maxSweeps?: number;
     };
+    /** Bearer secret for plugin machine routes. Falls back to `cron.secret`. */
+    machineSecret?: string;
+    /** In-process fixed-window limiter, applied before routing. */
+    rateLimit?: RateLimitConfig;
     plugins?: readonly AnyPlugin[];
     /** Where the handler is mounted, used to strip the prefix off incoming URLs. */
     basePath?: string;
+    /** 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>;
+    /** Defaults to 64 KiB. */
+    maxBodyBytes?: number;
     /** Table-name prefix; must match the one given to the adapter. */
     tablePrefix?: string;
     logger?: Logger;
@@ -111,6 +127,13 @@ type SendResult = {
 type Worker = {
     stop: () => Promise<void>;
 };
+type MountedRoute = {
+    method: "GET" | "POST";
+    path: string;
+    scope: RouteScope;
+    /** "core" for the built-in routes, otherwise the plugin id. */
+    owner: string;
+};
 type HealthReport = {
     mode: DeliveryMode;
     cronMounted: boolean;
@@ -131,13 +154,9 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
         batchSize?: number;
     }): Worker;
     healthCheck(): Promise<HealthReport>;
-    /**
-     * 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.
-     */
+    /** 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. Wire it to an admin page or an alert. */
     getFailedDeliveries(options?: {
         /** Defaults to the last 24 hours. */
         since?: Date;
@@ -146,8 +165,6 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
     }): Promise<readonly DeliveryRecord[]>;
 };
 
-declare function easyPing<TDefs extends NotificationDefinitions>(config: EasyPingConfig<TDefs>): EasyPing<TDefs>;
-
 type Backoff = "exponential" | ((attempt: number) => number);
 
 type RunnerDeps = {
@@ -168,6 +185,8 @@ type SweepResult = {
     /** Deliveries that had nothing to do. Not errors; see DeliveryOutcome. */
     skipped: number;
 };
+/** 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?: {
         limit?: number;
@@ -186,20 +205,20 @@ declare function createRunner(deps: RunnerDeps): {
 };
 type Runner = ReturnType<typeof createRunner>;
 
-type TokenClaims = {
-    /** Subject — the user the token acts for. */
-    uid: string;
-    /** What the token is allowed to do. Verification requires an exact match. */
-    purpose: string;
-    /** Expiry, epoch seconds. */
-    exp: number;
-    /** Free-form, purpose-specific. */
-    data?: Record<string, string>;
-};
-declare function signToken(secret: string, claims: TokenClaims): Promise<string>;
-/** null for every failure mode. Distinguishing them tells an attacker which part to fix. */
-declare function verifyToken(secret: string, token: string, purpose: string, now?: Date): Promise<TokenClaims | null>;
-declare const DEFAULT_TOKEN_TTL_SECONDS: number;
-declare const expiresIn: (seconds: number, now?: Date) => number;
+/** Every JSON body is capped here. Nothing legitimate the routes accept is bigger. */
+declare const MAX_BODY_BYTES: number;
+type JsonBody = {
+    body: Record<string, unknown>;
+} | {
+    error: Response;
+};
+/** 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 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, DEFAULT_TOKEN_TTL_SECONDS, DatabaseAdapter, type DeliveryConfig, DeliveryMode, DeliveryRecord, type EasyPing, type EasyPingConfig, EmailProvider, type EmailTemplate, type HealthReport, Logger, type NotificationDefinition, type NotificationDefinitions, type PayloadFromSchema, type PayloadOf, Recipient, type Runner, type RunnerDeps, type SendArgs, type SendResult, type SessionConfig, SkipReason, type SweepResult, type TokenClaims, type Worker, createRunner, decodeBase64Url, defineNotification, easyPing, encodeBase64Url, expiresIn, signToken, verifyToken };
+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 };