authhero 4.102.0 → 4.103.0

package/dist/authhero.d.ts

@@ -51851,6 +51851,15 @@ export interface WebhookInvokerParams {
 	data: Record<string, unknown>;
 	/** The tenant ID */
 	tenant_id: string;
+	/**
+	 * Outbox event id for this invocation. Matches the value the default
+	 * invoker sends as the `Idempotency-Key` header — custom invokers should
+	 * forward it as the same header (or an equivalent dedupe key) so
+	 * downstream receivers can dedupe on outbox retries. Only set when the
+	 * invocation originates from the transactional outbox; the legacy inline
+	 * dispatcher has no stable event id to forward.
+	 */
+	idempotency_key?: string;
 	/**
 	 * Lazily creates a service token for authenticating with the webhook endpoint.
 	 * Only creates the token when called — no overhead if you use your own auth.
@@ -52556,6 +52565,59 @@ export interface OutboxCleanupParams {
  * Intended for use in a scheduled handler / cron job.
  */
 export declare function cleanupOutbox(outbox: OutboxAdapter, params?: OutboxCleanupParams): Promise<number>;
+/**
+ * Mints a Bearer token for a given tenant. `scope` is forwarded so a custom
+ * `webhookInvoker` can request a non-default scope for its outbound call.
+ */
+export type GetServiceToken = (tenantId: string, scope?: string) => Promise<string>;
+export interface WebhookInvocation {
+	eventId: string;
+	tenantId: string;
+	triggerId: string;
+	payload: {
+		tenant_id: string;
+		trigger_id: string;
+		user?: unknown;
+		request?: unknown;
+	};
+}
+export interface WebhookDestinationOptions {
+	timeoutMs?: number;
+	/**
+	 * Replaces the default HTTP invoker. When set, each matching webhook is
+	 * dispatched by calling `webhookInvoker({ hook, data, tenant_id,
+	 * createServiceToken })` instead of issuing a raw `fetch` with a Bearer
+	 * token. `createServiceToken(scope?)` lazily mints a token bound to the
+	 * invocation's tenant, matching the shape passed to the legacy inline
+	 * dispatcher in `hooks/webhooks.ts`.
+	 */
+	webhookInvoker?: WebhookInvoker;
+}
+/**
+ * Delivers `hook.*` outbox events to HTTP webhooks configured for the matching
+ * trigger_id. Each POST includes `Idempotency-Key: {event.id}` so downstream
+ * webhook handlers can dedupe if the outbox retries.
+ *
+ * The destination is constructed per-request (via `outboxMiddleware`'s
+ * `getDestinations(ctx)` factory) so it can close over a ctx-bound service
+ * token generator. The same class is also used by the cron `runOutboxRelay`
+ * helper — a consumer's `webhookInvoker` configured via `init()` propagates
+ * to both paths so cron-drained deliveries don't diverge from per-request
+ * ones.
+ */
+export declare class WebhookDestination implements EventDestination {
+	name: string;
+	private hooks;
+	private getServiceToken;
+	private timeoutMs;
+	private webhookInvoker?;
+	constructor(hooks: HooksAdapter, getServiceToken: GetServiceToken, options?: WebhookDestinationOptions);
+	accepts(event: AuditEvent): boolean;
+	transform(event: AuditEvent): WebhookInvocation;
+	deliver(events: WebhookInvocation[]): Promise<void>;
+	private invokeCustom;
+	private invokeDefault;
+}
 export interface CreateDefaultDestinationsConfig {
 	/**
 	 * Data adapter — only the `logs`, `hooks`, and `users` adapters are used
@@ -52569,9 +52631,17 @@ export interface CreateDefaultDestinationsConfig {
 	 * Required if you want `hook.*` events to be drained. Omit for cron
 	 * drains that only need to sweep up log events.
 	 */
-	getServiceToken?: (tenantId: string) => Promise<string>;
+	getServiceToken?: GetServiceToken;
 	/** Webhook HTTP request timeout in ms (default: 10_000). */
 	webhookTimeoutMs?: number;
+	/**
+	 * Custom webhook invoker — same shape as the `webhookInvoker` option on
+	 * `init()`. When provided, `hook.*` events are dispatched by calling this
+	 * function instead of issuing a raw `fetch` with a Bearer token. Use this
+	 * to match a consumer-configured invoker exactly, so cron-drained
+	 * deliveries don't diverge from inline per-request ones.
+	 */
+	webhookInvoker?: WebhookInvoker;
 }
 /**
  * Build the same array of outbox destinations that authhero's per-request
@@ -52599,6 +52669,62 @@ export interface CreateDefaultDestinationsConfig {
  * ```
  */
 export declare function createDefaultDestinations(config: CreateDefaultDestinationsConfig): EventDestination[];
+export interface RunOutboxRelayConfig {
+	/** Same `DataAdapters` passed to `init()`. Must include `outbox` to drain. */
+	dataAdapter: DataAdapters;
+	/**
+	 * Issuer URL used when minting per-tenant `auth-service` tokens (typically
+	 * your `env.ISSUER`). Webhook handlers that validate `iss` against this
+	 * URL will accept tokens from both the inline dispatcher and this cron
+	 * relay.
+	 */
+	issuer: string;
+	/**
+	 * Optional webhook invoker — same shape as the one accepted by `init()`.
+	 * When provided, cron-drained `hook.*` events go through this invoker,
+	 * matching the inline per-request dispatch path exactly.
+	 */
+	webhookInvoker?: WebhookInvoker;
+	/** Days to retain processed events before cleanup. Default 7. */
+	retentionDays?: number;
+	/** Forwarded to `drainOutbox`. */
+	batchSize?: number;
+	/** Forwarded to `drainOutbox`. */
+	maxRetries?: number;
+	/** Webhook HTTP timeout (ms), when the default invoker is used. */
+	webhookTimeoutMs?: number;
+}
+/**
+ * One-call outbox relay for cron / scheduled handlers.
+ *
+ * Internally:
+ * 1. Skips gracefully when `dataAdapter.outbox` is undefined.
+ * 2. Builds the same destination array as the inline dispatcher
+ *    (`LogsDestination`, `WebhookDestination`, `RegistrationFinalizerDestination`).
+ * 3. Mints per-tenant service tokens via the same in-process path
+ *    (`createServiceTokenCore`) that the request-time webhookInvoker uses,
+ *    driven by the supplied dataAdapter.
+ * 4. Runs `drainOutbox`, then `cleanupOutbox`.
+ *
+ * This is intended to be the entire body of a consumer's scheduled handler
+ * for outbox maintenance — consumers should not need to call `drainOutbox` /
+ * `cleanupOutbox` / `createDefaultDestinations` directly.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async scheduled(_event, env) {
+ *     await runOutboxRelay({
+ *       dataAdapter,
+ *       issuer: env.ISSUER,
+ *       webhookInvoker,   // same function passed to init()
+ *       retentionDays: 7,
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export declare function runOutboxRelay(config: RunOutboxRelayConfig): Promise<void>;
 export declare class LogsDestination implements EventDestination {
 	name: string;
 	private logs;
@@ -52617,39 +52743,6 @@ export declare class LogsDestination implements EventDestination {
 		log: LogInsert;
 	}[]): Promise<void>;
 }
-export type GetServiceToken = (tenantId: string) => Promise<string>;
-export interface WebhookInvocation {
-	eventId: string;
-	tenantId: string;
-	triggerId: string;
-	payload: {
-		tenant_id: string;
-		trigger_id: string;
-		user?: unknown;
-		request?: unknown;
-	};
-}
-/**
- * Delivers `hook.*` outbox events to HTTP webhooks configured for the matching
- * trigger_id. Each POST includes `Idempotency-Key: {event.id}` so downstream
- * webhook handlers can dedupe if the outbox retries.
- *
- * The destination is constructed per-request (via `outboxMiddleware`'s
- * `getDestinations(ctx)` factory) so it can close over a ctx-bound service
- * token generator.
- */
-export declare class WebhookDestination implements EventDestination {
-	name: string;
-	private hooks;
-	private getServiceToken;
-	private timeoutMs;
-	constructor(hooks: HooksAdapter, getServiceToken: GetServiceToken, options?: {
-		timeoutMs?: number;
-	});
-	accepts(event: AuditEvent): boolean;
-	transform(event: AuditEvent): WebhookInvocation;
-	deliver(events: WebhookInvocation[]): Promise<void>;
-}
 export interface FinalizationTask {
 	tenantId: string;
 	userId: string;