easy-ping 0.2.0 → 0.4.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-f0OR2DhY.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-f0OR2DhY.cjs';
+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 { StandardSchemaV1 } from '@standard-schema/spec';
-import { A as AnyPlugin, L as Logger } from './plugin-Bqj9xAOS.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-Bqj9xAOS.cjs';
+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 { E as EmailProvider } from './provider-CA45WVqt.cjs';
 export { a as EmailMessage, P as ProviderSendResult } from './provider-CA45WVqt.cjs';
 
@@ -38,6 +38,25 @@ 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;
+    /**
+     * 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.
+     */
+    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.
+ */
+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>;
@@ -77,10 +96,33 @@ 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 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.
+     */
+    machineSecret?: string;
+    /**
+     * In-process fixed-window limiter, applied before routing. Keyed by client
+     * address from the usual proxy headers unless `key` says otherwise.
+     */
+    rateLimit?: RateLimitConfig;
     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.
+     */
+    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 +153,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,6 +180,8 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
         batchSize?: number;
     }): Worker;
     healthCheck(): Promise<HealthReport>;
+    /** 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.
      *
@@ -146,8 +197,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 = {
@@ -165,7 +214,15 @@ type SweepResult = {
     claimed: number;
     sent: number;
     failed: number;
+    /** 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.
+ */
+declare const redactErrorMessage: (text: string) => string;
 declare function createRunner(deps: RunnerDeps): {
     runOnce: (options?: {
         limit?: number;
@@ -184,20 +241,29 @@ 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 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.
+ */
+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.
+ */
+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-f0OR2DhY.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-f0OR2DhY.js';
+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 { StandardSchemaV1 } from '@standard-schema/spec';
-import { A as AnyPlugin, L as Logger } from './plugin-bTJKmnlq.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-bTJKmnlq.js';
+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 { E as EmailProvider } from './provider-CA45WVqt.js';
 export { a as EmailMessage, P as ProviderSendResult } from './provider-CA45WVqt.js';
 
@@ -38,6 +38,25 @@ 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;
+    /**
+     * 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.
+     */
+    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.
+ */
+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>;
@@ -77,10 +96,33 @@ 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 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.
+     */
+    machineSecret?: string;
+    /**
+     * In-process fixed-window limiter, applied before routing. Keyed by client
+     * address from the usual proxy headers unless `key` says otherwise.
+     */
+    rateLimit?: RateLimitConfig;
     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.
+     */
+    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 +153,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,6 +180,8 @@ type EasyPing<TDefs extends NotificationDefinitions> = {
         batchSize?: number;
     }): Worker;
     healthCheck(): Promise<HealthReport>;
+    /** 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.
      *
@@ -146,8 +197,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 = {
@@ -165,7 +214,15 @@ type SweepResult = {
     claimed: number;
     sent: number;
     failed: number;
+    /** 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.
+ */
+declare const redactErrorMessage: (text: string) => string;
 declare function createRunner(deps: RunnerDeps): {
     runOnce: (options?: {
         limit?: number;
@@ -184,20 +241,29 @@ 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 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.
+ */
+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.
+ */
+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 };