@authhero/cloudflare-adapter 2.21.19 → 2.22.0

package/dist/cloudflare-adapter.d.ts

@@ -683,6 +683,43 @@ export interface StatsAdapter {
 	 */
 	getActiveUsers(tenantId: string): Promise<number>;
 }
+export interface CodeExecutionResult {
+	success: boolean;
+	error?: string;
+	durationMs: number;
+	apiCalls: Array<{
+		method: string;
+		args: unknown[];
+	}>;
+}
+export interface CodeExecutor {
+	execute(params: {
+		code: string;
+		hookCodeId?: string;
+		triggerId: string;
+		event: Record<string, unknown>;
+		/** Wall-clock timeout for the entire execution (ms). */
+		timeoutMs?: number;
+		/**
+		 * CPU-time limit (ms) for runtimes that distinguish CPU time from
+		 * wall-clock time (e.g. Cloudflare Workers for Platforms).
+		 * Ignored by executors that do not support CPU-time limits.
+		 */
+		cpuLimitMs?: number;
+	}): Promise<CodeExecutionResult>;
+	/**
+	 * Deploy user code to the execution environment.
+	 * Called when hook code is created or updated.
+	 * Optional — LocalCodeExecutor does not need this.
+	 */
+	deploy?(hookCodeId: string, code: string): Promise<void>;
+	/**
+	 * Remove user code from the execution environment.
+	 * Called when hook code is deleted.
+	 * Optional — LocalCodeExecutor does not need this.
+	 */
+	remove?(hookCodeId: string): Promise<void>;
+}
 export interface R2SQLLogsAdapterConfig {
 	/**
 	 * Cloudflare Pipeline HTTP endpoint URL for ingesting logs
@@ -910,6 +947,107 @@ export interface CloudflareConfig {
 	 */
 	analyticsEngineLogs?: AnalyticsEngineLogsAdapterConfig;
 }
+/**
+ * Cloudflare Workers for Platforms dispatch namespace binding type.
+ * This is the type of `env.DISPATCHER` when configured in wrangler.toml:
+ *
+ * ```toml
+ * [[dispatch_namespaces]]
+ * binding = "DISPATCHER"
+ * namespace = "authhero-hooks"
+ * ```
+ */
+export interface DispatchNamespace {
+	get(name: string, options?: Record<string, unknown>, init?: {
+		limits?: {
+			cpuMs?: number;
+			subrequests?: number;
+		};
+	}): {
+		fetch(request: Request | string, init?: RequestInit): Promise<Response>;
+	};
+}
+export interface CloudflareCodeExecutorConfig {
+	/** Cloudflare account ID */
+	accountId: string;
+	/** API token with Workers Scripts write permission */
+	apiToken: string;
+	/** Dispatch namespace name (e.g., "authhero-hooks") */
+	dispatchNamespace: string;
+	/**
+	 * Dispatch namespace binding from the worker environment.
+	 * When running inside a Cloudflare Worker, pass `env.DISPATCHER`.
+	 * Enables low-latency same-origin invocation.
+	 */
+	dispatcher?: DispatchNamespace;
+	/**
+	 * Fallback URL for invoking user workers when no dispatcher binding is available.
+	 * The executor appends `/{scriptName}` to this URL.
+	 * Only used when `dispatcher` is not provided.
+	 */
+	dispatchUrl?: string;
+	/**
+	 * Cloudflare Workers compatibility date used when deploying scripts.
+	 * Defaults to "2024-11-20" if not provided.
+	 */
+	compatibilityDate?: string;
+}
+/**
+ * Code executor that uses Cloudflare Workers for Platforms.
+ *
+ * User code is deployed as individual worker scripts in a dispatch namespace.
+ * At execution time, the pre-deployed worker is invoked via the dispatch
+ * namespace binding (in-worker) or via HTTP (external fallback).
+ *
+ * Usage:
+ * ```typescript
+ * const codeExecutor = new CloudflareCodeExecutor({
+ *   accountId: env.CF_ACCOUNT_ID,
+ *   apiToken: env.CF_API_TOKEN,
+ *   dispatchNamespace: "authhero-hooks",
+ *   dispatcher: env.DISPATCHER,
+ * });
+ *
+ * const { app } = init({ dataAdapter, codeExecutor });
+ * ```
+ */
+export declare class CloudflareCodeExecutor implements CodeExecutor {
+	private config;
+	constructor(config: CloudflareCodeExecutorConfig);
+	execute(params: {
+		code: string;
+		hookCodeId?: string;
+		triggerId: string;
+		event: Record<string, unknown>;
+		/** Wall-clock timeout (ms). Used for HTTP-based fallback invocation. */
+		timeoutMs?: number;
+		/**
+		 * CPU-time limit (ms) passed to the Cloudflare dispatcher binding.
+		 * Unlike timeoutMs (wall-clock), this caps only actual CPU cycles;
+		 * I/O wait does not count against it. Defaults to 5 000 ms.
+		 */
+		cpuLimitMs?: number;
+	}): Promise<CodeExecutionResult>;
+	/**
+	 * Deploy user code as a worker to the dispatch namespace.
+	 * Wraps the code in a worker template and uploads via Cloudflare API.
+	 */
+	deploy(hookCodeId: string, code: string): Promise<void>;
+	/**
+	 * Remove a user worker from the dispatch namespace.
+	 */
+	remove(hookCodeId: string): Promise<void>;
+}
+/**
+ * Generates a Cloudflare Worker script that wraps user-authored code.
+ *
+ * The generated worker:
+ * 1. Accepts POST requests with { triggerId, event }
+ * 2. Creates a recording API proxy that captures method calls
+ * 3. Runs the user's exported function (e.g., exports.onExecutePostLogin)
+ * 4. Returns { success, apiCalls, error, durationMs } as JSON
+ */
+export declare function generateWorkerScript(userCode: string): string;
 export interface CloudflareAdapters {
 	customDomains: CustomDomainsAdapter;
 	cache: CacheAdapter;