@krantho/api 0.0.0-stage → 1.0.1

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+import type { AuthMode, KranthoConfig, WebhookTarget } from '@krantho/config';
+import type { IContentEngine } from '@krantho/core';
+import type { ContentDocument, IAuthAdapter, IPersistenceAdapter, Role } from '@krantho/persistence';
+import type { ContentConfig, PageDefinition } from '@krantho/schema';
+/** Framework-agnostic HTTP request */
+export interface ApiRequest {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    body?: unknown | undefined;
+    headers?: Record<string, string> | undefined;
+    rawRequest?: Request | undefined;
+    files?: Array<{
+        name: string;
+        data: Uint8Array;
+        filename: string;
+        mimeType: string;
+    }> | undefined;
+}
+/**
+ * How the host shows an editor a draft on the site: `draft-mode` — the host
+ * turns the API's answer into its own preview mode (Next.js draft mode);
+ * `signed-url` — the API sends the editor to the page with a short-lived
+ * signed token the page's server verifies
+ */
+export type SitePreviewMode = 'draft-mode' | 'signed-url';
+/** The server package hosting the API: `@krantho/server-next`, `-sveltekit` or `-node` */
+export type ServerFramework = 'next' | 'sveltekit' | 'node';
+/** Framework-agnostic HTTP response */
+export interface ApiResponse {
+    status: number;
+    /** JSON by default; a string or bytes as is; a `ReadableStream<Uint8Array>` is streamed to the client as is */
+    body: unknown;
+    headers?: Record<string, string> | undefined;
+    /** Set-Cookie values — one per cookie, emitted as separate header lines (RFC 6265). */
+    cookies?: readonly string[] | undefined;
+}
+/** Handler function signature */
+export type ApiHandler = (req: ApiRequest, ctx: ApiContext) => Promise<ApiResponse>;
+/** Webhook configuration: the `webhooks` entries of the configuration tree, or wiring passed to `createApiHandlers` */
+export type WebhookConfig = WebhookTarget;
+/** Shared context passed to all handlers */
+export interface ApiContext {
+    contentConfig: ContentConfig;
+    /** The resolved configuration tree — the only place a handler reads settings from */
+    config: KranthoConfig;
+    adapter: IPersistenceAdapter;
+    engine: IContentEngine;
+    auth?: AuthenticatedUser | undefined;
+    pages?: readonly PageDefinition[] | undefined;
+    /** Fire webhook callback after content mutations */
+    fireWebhook?: ((event: string, collection: string, slug: string) => void) | undefined;
+    /** The configured webhooks: a retried delivery is sent to the one with its URL, signed with its secret */
+    webhooks?: readonly WebhookConfig[] | undefined;
+    /** Lifecycle hooks */
+    contentHooks?: import('./hooks.js').ContentHooks | undefined;
+    /** Told about every committed write (see `announceChange`) */
+    changeListeners?: readonly import('@krantho/core').ContentChangeListener[] | undefined;
+    /** Keeps a background job running until it settles (see `CreateApiHandlersConfig.waitUntil`) */
+    waitUntil?: ((work: Promise<unknown>) => void) | undefined;
+    /** Media storage adapter */
+    mediaStorage?: import('@krantho/persistence').IMediaStorage | undefined;
+    /** Media folder storage adapter */
+    mediaFolderStorage?: import('@krantho/persistence').IMediaFolderStorage | undefined;
+    /** The file store's display name (e.g. 'Local disk', 'Vercel Blob') */
+    mediaStorageLabel?: string | undefined;
+    /** The file store's directory or bucket, when it has one */
+    mediaStoragePath?: string | undefined;
+    /** Image optimizer instance */
+    imageOptimizer?: import('./image-optimizer.js').ImageOptimizer | undefined;
+    /** Image variant cache */
+    imageCache?: import('./image-cache.js').ImageCache | undefined;
+    /** Checkpoint adapter for backup/restore operations */
+    checkpointAdapter?: import('@krantho/persistence').ICheckpointAdapter | undefined;
+    /** Current schema version from migration runner */
+    schemaVersion?: number | undefined;
+    /** Persistence adapter type */
+    persistenceType?: 'filesystem' | 'sqlite' | 'postgres' | undefined;
+    /** How the host renders drafts for editors on the site (see `CreateApiHandlersConfig.sitePreview`) */
+    sitePreview?: SitePreviewMode | undefined;
+    /** The server package hosting the API (see `CreateApiHandlersConfig.framework`) */
+    framework?: ServerFramework | undefined;
+    /** Content migration adapter for conflict resolution */
+    contentMigrationAdapter?: import('@krantho/persistence').IContentMigrationAdapter | undefined;
+    /** Auth adapter for user/token operations */
+    authAdapter?: IAuthAdapter | undefined;
+    /** Advisory lock adapter */
+    lockAdapter?: import('@krantho/persistence').ILockAdapter | undefined;
+    /** Webhook delivery log adapter */
+    webhookDeliveryAdapter?: import('@krantho/persistence').IWebhookDeliveryAdapter | undefined;
+    /** Version retention adapter */
+    retentionAdapter?: import('@krantho/persistence').IRetentionAdapter | undefined;
+    /** Site settings adapter */
+    siteSettingsAdapter?: import('@krantho/persistence').ISiteSettingsAdapter | undefined;
+    /** Vault that seals the secrets stored in site settings; none means a site stores none */
+    secrets?: import('@krantho/persistence').ISecretVault | undefined;
+    /** SEO configuration adapter */
+    seoConfigAdapter?: import('@krantho/persistence').ISeoConfigAdapter | undefined;
+    /** The page cache the site's instances share, when `cache.shared` is `database` */
+    pageCacheStore?: import('@krantho/persistence').IPageCacheStore | undefined;
+}
+/** Authenticated user attached to request context */
+export interface AuthenticatedUser {
+    id: string;
+    email: string;
+    name: string;
+    roles: Role[];
+    mode: AuthMode;
+}
+/** Content item response shape — mirrors ContentDocument from persistence */
+export type ContentItemResponse = ContentDocument;
+/** Error response shape */
+export interface ErrorResponse {
+    error: string;
+    details?: unknown | undefined;
+}
+/** Media wiring: metadata and folders from the persistence, bytes from the file store */
+export interface MediaConfig {
+    metadata: import('@krantho/persistence').IMediaMetadataAdapter;
+    folders: import('@krantho/persistence').IMediaFolderStorage;
+    files: import('@krantho/persistence').IFileStore;
+}
+/** Check if adapter supports version history (append-only adapters do) */
+export declare function hasVersioning(adapter: unknown): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/** Check if adapter supports version history (append-only adapters do) */
+export function hasVersioning(adapter) {
+    const a = adapter;
+    return typeof a['listVersions'] === 'function' && typeof a['getVersion'] === 'function';
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkIA,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,CAAC,GAAG,OAAkC,CAAA;IAC5C,OAAO,OAAO,CAAC,CAAC,cAAc,CAAC,KAAK,UAAU,IAAI,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,UAAU,CAAA;AACzF,CAAC"}

package/dist/validators.d.ts

@@ -0,0 +1,107 @@
+import type { MediaCrop, MediaHotspot } from '@krantho/persistence';
+import type { Collection } from '@krantho/schema';
+import type { ZodObject, ZodRawShape } from 'zod';
+import type { ApiContext, ApiResponse } from './types.js';
+/** Type-safe inclusion check for const arrays — avoids `as readonly string[]` casts. */
+export declare function isOneOf<T extends string>(arr: readonly T[], value: string): value is T;
+/** Validate that a collection exists in the content config */
+export declare function validateCollectionParam(collection: string | undefined, ctx: ApiContext): {
+    isValid: true;
+    collection: string;
+    collectionDef: Collection<ZodObject<ZodRawShape>>;
+} | {
+    isValid: false;
+    response: ApiResponse;
+};
+/** Validate request body is a non-null object */
+export declare function validateRequestBody(body: unknown): {
+    isValid: true;
+    body: Record<string, unknown>;
+} | {
+    isValid: false;
+    response: ApiResponse;
+};
+/** Parse and validate a status query parameter: draft, published or archived */
+export declare function parseStatusParam(value: string | undefined): 'draft' | 'published' | 'archived' | undefined;
+/** Parse and validate a positive integer query parameter */
+export declare function parsePositiveInt(value: string | undefined): number | undefined;
+/**
+ * Apply the configured page-size cap to a requested list limit.
+ *
+ * `content.list.maxLimit` is unset by default, and an unset cap means a list
+ * without a `limit` parameter returns every row — the behaviour the API has
+ * always had. Setting it both caps an oversized request and imposes a page size
+ * on a request that asked for none. A negative or NaN request counts as no
+ * request, so it can never slip past the cap (SQLite reads `LIMIT -1` as
+ * unbounded).
+ */
+export declare function applyListLimit(requested: number | undefined, maxLimit: number | undefined): number | undefined;
+/** Parse and validate a locale query parameter */
+export declare function parseLocaleParam(value: string | undefined): string | undefined;
+/** Validate that a named route parameter exists */
+export declare function requireParam(params: Record<string, string> | undefined, name: string): {
+    isValid: true;
+    value: string;
+} | {
+    isValid: false;
+    response: ApiResponse;
+};
+/** Validate that a slug parameter exists */
+export declare function validateSlugParam(slug: string | undefined): {
+    isValid: true;
+    slug: string;
+} | {
+    isValid: false;
+    response: ApiResponse;
+};
+/** Parse a named cookie from a cookie header string */
+export declare function parseCookie(cookieHeader: string | undefined, name: string): string | undefined;
+/**
+ * Validate a crop region. Crop must fit entirely within the image (x + w <= 100).
+ */
+export declare function validateCrop(crop: unknown): {
+    isValid: true;
+    crop: MediaCrop;
+} | {
+    isValid: false;
+    error: string;
+};
+/**
+ * Validate a hotspot center + ellipse. Unlike crop, hotspot can overflow image bounds
+ * because it represents a center of interest, not a hard crop boundary. The image
+ * optimizer clamps the computed crop region to image bounds at serve time.
+ * Width/height are stored for UI rendering (ellipse visualization) — only center (x, y)
+ * is used by the image optimizer for crop positioning.
+ */
+export declare function validateHotspot(hotspot: unknown): {
+    isValid: true;
+    hotspot: MediaHotspot;
+} | {
+    isValid: false;
+    error: string;
+};
+/** Parse and validate a checkpoint version from route params */
+export declare function parseCheckpointVersion(params: Record<string, string> | undefined): {
+    isValid: true;
+    version: number;
+} | {
+    isValid: false;
+    response: ApiResponse;
+};
+/** Type predicate: narrows ctx to have non-undefined mediaStorage */
+export declare function hasMediaStorage(ctx: ApiContext): ctx is ApiContext & {
+    mediaStorage: NonNullable<ApiContext['mediaStorage']>;
+};
+/** 501 response for missing media storage */
+export declare const MEDIA_NOT_CONFIGURED: ApiResponse;
+/** Format Zod validation errors into API response details */
+export declare function formatZodErrors(issues: ReadonlyArray<{
+    path: PropertyKey[];
+    message: string;
+    code?: string;
+    keys?: readonly string[];
+}>): Array<{
+    field: string;
+    message: string;
+}>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"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"}

package/dist/validators.js

@@ -0,0 +1,199 @@
+const VALID_STATUSES = ['draft', 'published', 'archived'];
+/** Type-safe inclusion check for const arrays — avoids `as readonly string[]` casts. */
+export function isOneOf(arr, value) {
+    return arr.includes(value);
+}
+/** Validate that a collection exists in the content config */
+export function validateCollectionParam(collection, ctx) {
+    if (!collection) {
+        return {
+            isValid: false,
+            response: { status: 400, body: { error: 'Missing collection parameter' } },
+        };
+    }
+    const collectionDef = ctx.contentConfig.collections.get(collection);
+    if (!collectionDef) {
+        return {
+            isValid: false,
+            response: { status: 404, body: { error: `Collection "${collection}" not found` } },
+        };
+    }
+    return { isValid: true, collection, collectionDef };
+}
+/** Validate request body is a non-null object */
+export function validateRequestBody(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return {
+            isValid: false,
+            response: { status: 400, body: { error: 'Request body must be a JSON object' } },
+        };
+    }
+    return { isValid: true, body: body };
+}
+/** Parse and validate a status query parameter: draft, published or archived */
+export function parseStatusParam(value) {
+    if (!value)
+        return undefined;
+    if (value === 'draft' || value === 'published' || value === 'archived') {
+        return value;
+    }
+    return undefined;
+}
+/** Parse and validate a positive integer query parameter */
+export function parsePositiveInt(value) {
+    if (!value)
+        return undefined;
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed < 0)
+        return undefined;
+    return parsed;
+}
+/**
+ * Apply the configured page-size cap to a requested list limit.
+ *
+ * `content.list.maxLimit` is unset by default, and an unset cap means a list
+ * without a `limit` parameter returns every row — the behaviour the API has
+ * always had. Setting it both caps an oversized request and imposes a page size
+ * on a request that asked for none. A negative or NaN request counts as no
+ * request, so it can never slip past the cap (SQLite reads `LIMIT -1` as
+ * unbounded).
+ */
+export function applyListLimit(requested, maxLimit) {
+    const wanted = requested !== undefined && requested >= 0 ? requested : undefined;
+    if (maxLimit === undefined)
+        return wanted;
+    if (wanted === undefined)
+        return maxLimit;
+    return Math.min(wanted, maxLimit);
+}
+/** Parse and validate a locale query parameter */
+export function parseLocaleParam(value) {
+    if (!value)
+        return undefined;
+    // Locale must be 2-5 char alphanumeric with optional hyphen (e.g., en, en-US, nb-NO)
+    if (/^[a-z]{2}(-[A-Za-z]{2,3})?$/.test(value))
+        return value;
+    return undefined;
+}
+/** Validate that a named route parameter exists */
+export function requireParam(params, name) {
+    const value = params?.[name];
+    if (!value) {
+        return {
+            isValid: false,
+            response: { status: 400, body: { error: `Missing parameter: ${name}` } },
+        };
+    }
+    return { isValid: true, value };
+}
+/** Validate that a slug parameter exists */
+export function validateSlugParam(slug) {
+    if (!slug) {
+        return { isValid: false, response: { status: 400, body: { error: 'Missing parameter: slug' } } };
+    }
+    return { isValid: true, slug };
+}
+/** Parse a named cookie from a cookie header string */
+export function parseCookie(cookieHeader, name) {
+    if (!cookieHeader)
+        return undefined;
+    const match = cookieHeader.split(';').find((c) => c.trim().startsWith(`${name}=`));
+    return match ? match.split('=')[1]?.trim() : undefined;
+}
+/**
+ * Validate a crop region. Crop must fit entirely within the image (x + w <= 100).
+ */
+export function validateCrop(crop) {
+    if (typeof crop !== 'object' || crop === null) {
+        return { isValid: false, error: 'Crop must be an object' };
+    }
+    const c = crop;
+    const x = typeof c['x'] === 'number' ? c['x'] : NaN;
+    const y = typeof c['y'] === 'number' ? c['y'] : NaN;
+    const w = typeof c['width'] === 'number' ? c['width'] : NaN;
+    const h = typeof c['height'] === 'number' ? c['height'] : NaN;
+    if (Number.isNaN(x) ||
+        Number.isNaN(y) ||
+        Number.isNaN(w) ||
+        Number.isNaN(h) ||
+        x < 0 ||
+        y < 0 ||
+        w <= 0 ||
+        h <= 0 ||
+        x + w > 100 ||
+        y + h > 100) {
+        return {
+            isValid: false,
+            error: 'Invalid crop: x, y, width, height must be numbers 0-100 with width/height > 0',
+        };
+    }
+    return { isValid: true, crop: { x, y, width: w, height: h } };
+}
+/**
+ * Validate a hotspot center + ellipse. Unlike crop, hotspot can overflow image bounds
+ * because it represents a center of interest, not a hard crop boundary. The image
+ * optimizer clamps the computed crop region to image bounds at serve time.
+ * Width/height are stored for UI rendering (ellipse visualization) — only center (x, y)
+ * is used by the image optimizer for crop positioning.
+ */
+export function validateHotspot(hotspot) {
+    if (typeof hotspot !== 'object' || hotspot === null) {
+        return { isValid: false, error: 'Hotspot must be an object' };
+    }
+    const h = hotspot;
+    const x = typeof h['x'] === 'number' ? h['x'] : NaN;
+    const y = typeof h['y'] === 'number' ? h['y'] : NaN;
+    const w = typeof h['width'] === 'number' ? h['width'] : NaN;
+    const ht = typeof h['height'] === 'number' ? h['height'] : NaN;
+    if (Number.isNaN(x) ||
+        Number.isNaN(y) ||
+        Number.isNaN(w) ||
+        Number.isNaN(ht) ||
+        x < 0 ||
+        y < 0 ||
+        w <= 0 ||
+        ht <= 0 ||
+        x > 100 ||
+        y > 100 ||
+        w > 100 ||
+        ht > 100) {
+        return {
+            isValid: false,
+            error: 'Invalid hotspot: x, y, width, height must be numbers 0-100 with width/height > 0',
+        };
+    }
+    return { isValid: true, hotspot: { x, y, width: w, height: ht } };
+}
+/** Parse and validate a checkpoint version from route params */
+export function parseCheckpointVersion(params) {
+    const result = requireParam(params, 'version');
+    if (!result.isValid)
+        return result;
+    const version = parseInt(result.value, 10);
+    if (Number.isNaN(version)) {
+        return { isValid: false, response: { status: 400, body: { error: 'Invalid version number' } } };
+    }
+    return { isValid: true, version };
+}
+/** Type predicate: narrows ctx to have non-undefined mediaStorage */
+export function hasMediaStorage(ctx) {
+    return ctx.mediaStorage !== undefined;
+}
+/** 501 response for missing media storage */
+export const MEDIA_NOT_CONFIGURED = {
+    status: 501,
+    body: { error: 'Media storage not configured' },
+};
+/** Format Zod validation errors into API response details */
+export function formatZodErrors(issues) {
+    return issues.flatMap((issue) => {
+        const paths = issue.code === 'unrecognized_keys' && issue.keys?.length
+            ? issue.keys.map((key) => [...issue.path, key])
+            : [issue.path];
+        return paths.map((path) => ({
+            field: path.map(String).join('.') || '(root)',
+            message: issue.message,
+        }));
+    });
+}
+//# sourceMappingURL=validators.js.map

package/dist/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"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"}

package/dist/webhooks.d.ts

@@ -0,0 +1,29 @@
+import type { WebhookEvent } from '@krantho/config';
+import { type IWebhookDeliveryAdapter } from '@krantho/persistence';
+import type { WebhookConfig } from './types.js';
+/**
+ * Fire webhooks for a content event.
+ *
+ * With a delivery adapter, deliveries are logged and failed deliveries are
+ * retried with backoff. Without one, falls back to fire-and-forget.
+ */
+export declare function fireWebhooks(webhooks: readonly WebhookConfig[], event: WebhookEvent, collection: string, slug: string, deliveries?: IWebhookDeliveryAdapter): void;
+/** A stored delivery to send again: its row, its event, the payload it carried and the attempts made */
+export interface Redelivery {
+    id: number;
+    event: string;
+    payload: string;
+    attempts: number;
+}
+/**
+ * Send a stored delivery to its webhook once more, now, signed afresh with
+ * the hook's secret; the row records how it went. Resolves when it has.
+ */
+export declare function redeliverWebhook(hook: WebhookConfig, delivery: Redelivery, deliveries: IWebhookDeliveryAdapter): Promise<void>;
+/**
+ * Send the deliveries that are due again: failed ones whose retry time has
+ * passed, and any whose first send never recorded an outcome. Resolves when
+ * every one has been sent and its outcome recorded.
+ */
+export declare function processWebhookRetries(webhooks: readonly WebhookConfig[], deliveries: IWebhookDeliveryAdapter): Promise<void>;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAAE,KAAK,uBAAuB,EAAwB,MAAM,sBAAsB,CAAA;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAiC/C;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,uBAAuB,GACnC,IAAI,CAcN;AA+CD,wGAAwG;AACxG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,UAAU,EAAE,uBAAuB,GAClC,OAAO,CAAC,IAAI,CAAC,CAyBf"}

package/dist/webhooks.js

@@ -0,0 +1,123 @@
+import { createHmac } from 'node:crypto';
+import { MAX_WEBHOOK_ATTEMPTS } from '@krantho/persistence';
+/**
+ * Retry delays in seconds, indexed by the attempts made: after a first attempt 30s, then 2min,
+ * 15min and 1h (index 0 is never used: every delivery has made one attempt by the time it is
+ * logged). The length equals MAX_WEBHOOK_ATTEMPTS from @krantho/persistence, which owns the limit.
+ */
+const RETRY_DELAYS = [0, 30, 120, 900, 3600];
+/** When a delivery that has made `attempts` attempts, the last of them failing or still in flight, is due again */
+function retryDueAt(attempts) {
+    const retryIndex = Math.min(attempts, MAX_WEBHOOK_ATTEMPTS - 1);
+    const delaySeconds = RETRY_DELAYS[retryIndex] ?? 3600;
+    return new Date(Date.now() + delaySeconds * 1000);
+}
+/** The sweep sends no more than this many deliveries at a time */
+const SWEEP_BATCH = 20;
+/**
+ * A send gives up after this long, well inside the first retry delay: a first
+ * send is logged as due for retry only after that delay, so the retry sweep
+ * never sends a delivery whose first send is still in flight.
+ */
+const SEND_TIMEOUT_MS = 10_000;
+/**
+ * Fire webhooks for a content event.
+ *
+ * With a delivery adapter, deliveries are logged and failed deliveries are
+ * retried with backoff. Without one, falls back to fire-and-forget.
+ */
+export function fireWebhooks(webhooks, event, collection, slug, deliveries) {
+    const payload = {
+        event,
+        collection,
+        slug,
+        timestamp: new Date().toISOString(),
+    };
+    const body = JSON.stringify(payload);
+    for (const hook of webhooks) {
+        if (!hook.events.includes(event))
+            continue;
+        deliverWebhook(hook, body, event, deliveries);
+    }
+}
+/** Sign a payload with HMAC and deliver via fetch. Returns the Response or null on network error. */
+function signAndDeliver(hook, body) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (hook.secret) {
+        const timestamp = Date.now().toString();
+        const signature = createHmac('sha256', hook.secret).update(`${timestamp}.${body}`).digest('hex');
+        headers['X-Webhook-Signature'] = `t=${timestamp},v1=${signature}`;
+    }
+    return fetch(hook.url, {
+        method: 'POST',
+        headers,
+        body,
+        signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    }).catch(() => null);
+}
+/** Deliver a single webhook, logging the send when there is a delivery log */
+function deliverWebhook(hook, body, event, deliveries) {
+    // Logged as due for a retry only after the first retry delay: until then the send is in flight
+    const logged = deliveries
+        ? deliveries.logDelivery({ url: hook.url, event, payload: body, retryAt: retryDueAt(1) })
+        : null;
+    Promise.all([logged, signAndDeliver(hook, body)])
+        .then(([deliveryId, res]) => {
+        if (!res?.ok) {
+            console.warn(`[webhook] ${event} to ${hook.url} failed with status ${res?.status ?? 0}`);
+        }
+        if (deliveries === undefined || deliveryId === null)
+            return;
+        return res?.ok
+            ? deliveries.markDelivered(deliveryId, res.status)
+            : deliveries.markFailed(deliveryId, res?.status ?? 0, retryDueAt(1));
+    })
+        .catch((err) => {
+        console.warn(`[webhook] ${event} to ${hook.url} could not be recorded:`, err);
+    });
+}
+/**
+ * Send a stored delivery to its webhook once more, now, signed afresh with
+ * the hook's secret; the row records how it went. Resolves when it has.
+ */
+export async function redeliverWebhook(hook, delivery, deliveries) {
+    const res = await signAndDeliver(hook, delivery.payload);
+    if (res?.ok) {
+        await deliveries.markDelivered(delivery.id, res.status);
+        return;
+    }
+    console.warn(`[webhook] Retry of ${delivery.event} to ${hook.url} failed: ${res?.status ?? 0}`);
+    await deliveries.markFailed(delivery.id, res?.status ?? 0, retryDueAt(delivery.attempts));
+}
+/**
+ * Send the deliveries that are due again: failed ones whose retry time has
+ * passed, and any whose first send never recorded an outcome. Resolves when
+ * every one has been sent and its outcome recorded.
+ */
+export async function processWebhookRetries(webhooks, deliveries) {
+    if (webhooks.length === 0)
+        return;
+    // Only the configured hooks: a delivery to a hook removed since stays unsent
+    // and must not take the places of the ones that can be sent. A claimed
+    // delivery is held for the first retry delay, well beyond a send's timeout,
+    // so no other sweep sends it meanwhile; its outcome then sets its next time
+    const now = new Date();
+    const pending = await deliveries.claimDueDeliveries({
+        urls: webhooks.map((hook) => hook.url),
+        now,
+        leaseUntil: new Date(now.getTime() + (RETRY_DELAYS[1] ?? 30) * 1000),
+        limit: SWEEP_BATCH,
+    });
+    const sends = pending.flatMap((delivery) => {
+        const hook = webhooks.find((h) => h.url === delivery.url);
+        if (!hook)
+            return [];
+        return [
+            redeliverWebhook(hook, delivery, deliveries).catch((err) => {
+                console.warn(`[webhook] Retry of delivery ${delivery.id} could not be recorded:`, err);
+            }),
+        ];
+    });
+    await Promise.all(sends);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}