@databricks/appkit 0.26.0 → 0.27.0

package/dist/plugins/jobs/manifest.js

@@ -0,0 +1,40 @@
+//#region src/plugins/jobs/manifest.json
+var manifest_default = {
+	$schema: "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+	name: "jobs",
+	displayName: "Jobs Plugin",
+	description: "Manage Databricks Lakeflow Jobs.",
+	resources: {
+		"required": [{
+			"type": "job",
+			"alias": "Job",
+			"resourceKey": "job",
+			"description": "A Databricks job to trigger and monitor",
+			"permission": "CAN_MANAGE_RUN",
+			"fields": { "id": {
+				"env": "DATABRICKS_JOB_ID",
+				"description": "Numeric Databricks job ID. Find it in the Jobs UI or via `databricks jobs list`."
+			} }
+		}],
+		"optional": []
+	},
+	config: { "schema": {
+		"type": "object",
+		"properties": {
+			"timeout": {
+				"type": "number",
+				"default": 6e4,
+				"description": "Default timeout for Jobs API calls in milliseconds"
+			},
+			"pollIntervalMs": {
+				"type": "number",
+				"default": 5e3,
+				"description": "Poll interval for waiting on run completion in milliseconds"
+			}
+		}
+	} }
+};
+
+//#endregion
+export { manifest_default as default };
+//# sourceMappingURL=manifest.js.map

package/dist/plugins/jobs/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","names":[],"sources":["../../../src/plugins/jobs/manifest.json"],"sourcesContent":[""],"mappings":""}

package/dist/plugins/jobs/params.js

@@ -0,0 +1,35 @@
+//#region src/plugins/jobs/params.ts
+/** Throw if any value is not a string, number, or boolean. */
+function assertPrimitiveValues(params) {
+	for (const [k, v] of Object.entries(params)) if (v !== null && v !== void 0 && typeof v === "object") throw new Error(`Parameter "${k}" must be a primitive value, got ${Array.isArray(v) ? "array" : "object"}`);
+}
+/**
+* Maps validated parameters to SDK request fields based on the task type.
+* This is a pure function — stateless and testable in isolation.
+*/
+function mapParams(taskType, params) {
+	switch (taskType) {
+		case "notebook":
+			assertPrimitiveValues(params);
+			return { notebook_params: Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)])) };
+		case "python_wheel":
+			assertPrimitiveValues(params);
+			return { python_named_params: Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)])) };
+		case "python_script": return { python_params: Array.isArray(params.args) ? params.args.map(String) : [] };
+		case "spark_jar": return { jar_params: Array.isArray(params.args) ? params.args.map(String) : [] };
+		case "sql":
+			assertPrimitiveValues(params);
+			return { sql_params: Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)])) };
+		case "dbt":
+			if (Object.keys(params).length > 0) throw new Error("dbt tasks do not accept parameters");
+			return {};
+		default: {
+			const _exhaustive = taskType;
+			throw new Error(`Unknown task type: ${_exhaustive}`);
+		}
+	}
+}
+
+//#endregion
+export { mapParams };
+//# sourceMappingURL=params.js.map

package/dist/plugins/jobs/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","names":[],"sources":["../../../src/plugins/jobs/params.ts"],"sourcesContent":["import type { TaskType } from \"./types\";\n\n/** Throw if any value is not a string, number, or boolean. */\nfunction assertPrimitiveValues(params: Record<string, unknown>): void {\n  for (const [k, v] of Object.entries(params)) {\n    if (v !== null && v !== undefined && typeof v === \"object\") {\n      throw new Error(\n        `Parameter \"${k}\" must be a primitive value, got ${Array.isArray(v) ? \"array\" : \"object\"}`,\n      );\n    }\n  }\n}\n\n/**\n * Maps validated parameters to SDK request fields based on the task type.\n * This is a pure function — stateless and testable in isolation.\n */\nexport function mapParams(\n  taskType: TaskType,\n  params: Record<string, unknown>,\n): Record<string, unknown> {\n  switch (taskType) {\n    case \"notebook\":\n      // notebook_params expects Record<string, string>, values coerced to string\n      assertPrimitiveValues(params);\n      return {\n        notebook_params: Object.fromEntries(\n          Object.entries(params).map(([k, v]) => [k, String(v)]),\n        ),\n      };\n    case \"python_wheel\":\n      assertPrimitiveValues(params);\n      return {\n        python_named_params: Object.fromEntries(\n          Object.entries(params).map(([k, v]) => [k, String(v)]),\n        ),\n      };\n    case \"python_script\":\n      // python_params expects string[] (positional args)\n      return {\n        python_params: Array.isArray(params.args)\n          ? params.args.map(String)\n          : [],\n      };\n    case \"spark_jar\":\n      // jar_params expects string[]\n      return {\n        jar_params: Array.isArray(params.args) ? params.args.map(String) : [],\n      };\n    case \"sql\":\n      assertPrimitiveValues(params);\n      return {\n        sql_params: Object.fromEntries(\n          Object.entries(params).map(([k, v]) => [k, String(v)]),\n        ),\n      };\n    case \"dbt\":\n      if (Object.keys(params).length > 0) {\n        throw new Error(\"dbt tasks do not accept parameters\");\n      }\n      return {};\n    default: {\n      const _exhaustive: never = taskType;\n      throw new Error(`Unknown task type: ${_exhaustive}`);\n    }\n  }\n}\n"],"mappings":";;AAGA,SAAS,sBAAsB,QAAuC;AACpE,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,OAAO,CACzC,KAAI,MAAM,QAAQ,MAAM,UAAa,OAAO,MAAM,SAChD,OAAM,IAAI,MACR,cAAc,EAAE,mCAAmC,MAAM,QAAQ,EAAE,GAAG,UAAU,WACjF;;;;;;AASP,SAAgB,UACd,UACA,QACyB;AACzB,SAAQ,UAAR;EACE,KAAK;AAEH,yBAAsB,OAAO;AAC7B,UAAO,EACL,iBAAiB,OAAO,YACtB,OAAO,QAAQ,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,CAAC,CACvD,EACF;EACH,KAAK;AACH,yBAAsB,OAAO;AAC7B,UAAO,EACL,qBAAqB,OAAO,YAC1B,OAAO,QAAQ,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,CAAC,CACvD,EACF;EACH,KAAK,gBAEH,QAAO,EACL,eAAe,MAAM,QAAQ,OAAO,KAAK,GACrC,OAAO,KAAK,IAAI,OAAO,GACvB,EAAE,EACP;EACH,KAAK,YAEH,QAAO,EACL,YAAY,MAAM,QAAQ,OAAO,KAAK,GAAG,OAAO,KAAK,IAAI,OAAO,GAAG,EAAE,EACtE;EACH,KAAK;AACH,yBAAsB,OAAO;AAC7B,UAAO,EACL,YAAY,OAAO,YACjB,OAAO,QAAQ,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,CAAC,CACvD,EACF;EACH,KAAK;AACH,OAAI,OAAO,KAAK,OAAO,CAAC,SAAS,EAC/B,OAAM,IAAI,MAAM,qCAAqC;AAEvD,UAAO,EAAE;EACX,SAAS;GACP,MAAM,cAAqB;AAC3B,SAAM,IAAI,MAAM,sBAAsB,cAAc"}

package/dist/plugins/jobs/plugin.d.ts

@@ -0,0 +1,66 @@
+import { IAppRouter, ToPlugin } from "../../shared/src/plugin.js";
+import "../../shared/src/index.js";
+import { Plugin } from "../../plugin/plugin.js";
+import "../../plugin/index.js";
+import { PluginManifest, ResourceRequirement } from "../../registry/types.js";
+import "../../registry/index.js";
+import { IJobsConfig, JobAPI, JobConfig, JobsExport } from "./types.js";
+
+//#region src/plugins/jobs/plugin.d.ts
+declare class JobsPlugin extends Plugin {
+  static manifest: PluginManifest;
+  protected config: IJobsConfig;
+  private connector;
+  private jobIds;
+  private jobConfigs;
+  private jobKeys;
+  /**
+   * Scans process.env for DATABRICKS_JOB_* keys and merges with explicit config.
+   * Explicit config wins for per-job overrides; auto-discovered jobs get default `{}` config.
+   */
+  static discoverJobs(config: IJobsConfig): Record<string, JobConfig>;
+  /**
+   * Generates resource requirements dynamically from discovered + configured jobs.
+   * Each job key maps to a `DATABRICKS_JOB_{KEY_UPPERCASE}` env var (or `DATABRICKS_JOB_ID` for "default").
+   */
+  static getResourceRequirements(config: IJobsConfig): ResourceRequirement[];
+  constructor(config: IJobsConfig);
+  setup(): Promise<void>;
+  private get client();
+  private getJobId;
+  private _readSettings;
+  private _writeSettings;
+  /**
+   * Validates params against the job's Zod schema (if any) and maps them
+   * to SDK request fields based on the task type. Shared by runNow and runAndWait.
+   */
+  private _validateAndMap;
+  /**
+   * Creates a JobAPI for a specific configured job key.
+   * Each method is scoped to the job's configured ID.
+   */
+  protected createJobAPI(jobKey: string): JobAPI;
+  /**
+   * Resolve `:jobKey` from the request. Returns the key and ID,
+   * or sends a 404 and returns `{ jobKey: undefined, jobId: undefined }`.
+   */
+  private _resolveJob;
+  private _sendStatusError;
+  /**
+   * Validate params from an HTTP request body. Eager validation lets streaming
+   * requests get a clean 400 instead of a generic SSE error event. Throws
+   * ValidationError so handlers can map to a 400 response via their catch block.
+   */
+  private _parseRunParams;
+  private _handleRun;
+  injectRoutes(router: IAppRouter): void;
+  exports(): JobsExport;
+  clientConfig(): Record<string, unknown>;
+}
+/**
+ * @internal
+ */
+declare const jobs: ToPlugin<typeof JobsPlugin, IJobsConfig, string>;
+//#endregion
+export { jobs };
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/jobs/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/jobs/plugin.ts"],"mappings":";;;;;;;;;cAsFM,UAAA,SAAmB,MAAA;EAAA,OAChB,QAAA,EAAuB,cAAA;EAAA,UAEZ,MAAA,EAAQ,WAAA;EAAA,QAClB,SAAA;EAAA,QACA,MAAA;EAAA,QACA,UAAA;EAAA,QACA,OAAA;;;;;SAMD,YAAA,CAAa,MAAA,EAAQ,WAAA,GAAc,MAAA,SAAe,SAAA;EAAf;;;;EAAA,OAgCnC,uBAAA,CAAwB,MAAA,EAAQ,WAAA,GAAc,mBAAA;cAqBzC,MAAA,EAAQ,WAAA;EA0Bd,KAAA,CAAA,GAAK,OAAA;EAAA,YAMC,MAAA,CAAA;EAAA,QAIJ,QAAA;EAAA,QAcA,aAAA;EAAA,QAYA,cAAA;EAhIqB;;;;EAAA,QA6IrB,eAAA;EA1IkB;;;;EAAA,UAoKhB,YAAA,CAAa,MAAA,WAAiB,MAAA;EA1JjC;;;;EAAA,QAgXC,WAAA;EAAA,QA0BA,gBAAA;EA1W+B;;;;;EAAA,QAsX/B,eAAA;EAAA,QAuCM,UAAA;EA4Cd,YAAA,CAAa,MAAA,EAAQ,UAAA;EA6IrB,OAAA,CAAA,GAAW,UAAA;EAsBX,YAAA,CAAA,GAAgB,MAAA;AAAA;;;;cAiBL,IAAA,EAAI,QAAA,QAAA,UAAA,EAAA,WAAA"}

package/dist/plugins/jobs/plugin.js

@@ -0,0 +1,531 @@
+import { createLogger } from "../../logging/logger.js";
+import { ExecutionError } from "../../errors/execution.js";
+import { ValidationError } from "../../errors/validation.js";
+import { init_errors } from "../../errors/index.js";
+import { getCurrentUserId, getWorkspaceClient } from "../../context/execution-context.js";
+import { init_context } from "../../context/index.js";
+import { ResourceType } from "../../registry/types.generated.js";
+import "../../registry/index.js";
+import { Plugin } from "../../plugin/plugin.js";
+import { toPlugin } from "../../plugin/to-plugin.js";
+import "../../plugin/index.js";
+import { JobsConnector } from "../../connectors/jobs/client.js";
+import "../../connectors/jobs/index.js";
+import { JOBS_READ_DEFAULTS, JOBS_STREAM_DEFAULTS, JOBS_WRITE_DEFAULTS } from "./defaults.js";
+import manifest_default from "./manifest.js";
+import { mapParams } from "./params.js";
+import { STATUS_CODES } from "node:http";
+import { toJSONSchema } from "zod";
+
+//#region src/plugins/jobs/plugin.ts
+init_context();
+init_errors();
+const logger = createLogger("jobs");
+const DEFAULT_WAIT_TIMEOUT = 6e5;
+const DEFAULT_POLL_INTERVAL = 5e3;
+/** Cap on param-key count when a job has no Zod schema. Jobs that need more keys must define a schema. */
+const MAX_UNVALIDATED_PARAM_KEYS = 50;
+/** Replace upstream error messages with generic descriptions keyed by HTTP status. */
+function errorResult(status) {
+	return {
+		ok: false,
+		status,
+		message: STATUS_CODES[status] ?? "Request failed"
+	};
+}
+function isTerminalRunState(state) {
+	return state === "TERMINATED" || state === "SKIPPED" || state === "INTERNAL_ERROR";
+}
+/** Exponential backoff (1.5x) with +/- 20% jitter, capped at `max`. */
+function nextPollDelay(current, max) {
+	const jitter = 1 + (Math.random() * .4 - .2);
+	return {
+		delay: Math.min(current * jitter, max),
+		next: Math.min(current * 1.5, max)
+	};
+}
+function abortableSleep(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(timer);
+			resolve();
+		}, { once: true });
+	});
+}
+var JobsPlugin = class JobsPlugin extends Plugin {
+	static manifest = manifest_default;
+	connector;
+	jobIds = {};
+	jobConfigs = {};
+	jobKeys = [];
+	/**
+	* Scans process.env for DATABRICKS_JOB_* keys and merges with explicit config.
+	* Explicit config wins for per-job overrides; auto-discovered jobs get default `{}` config.
+	*/
+	static discoverJobs(config) {
+		const explicit = config.jobs ?? {};
+		const discovered = {};
+		const prefix = "DATABRICKS_JOB_";
+		for (const key of Object.keys(process.env)) {
+			if (!key.startsWith(prefix)) continue;
+			if (key === "DATABRICKS_JOB_ID") continue;
+			const suffix = key.slice(15);
+			if (!suffix || !process.env[key]) continue;
+			const jobKey = suffix.toLowerCase();
+			if (!(jobKey in explicit)) discovered[jobKey] = {};
+		}
+		if (process.env.DATABRICKS_JOB_ID && Object.keys(explicit).length === 0 && Object.keys(discovered).length === 0) discovered.default = {};
+		return {
+			...discovered,
+			...explicit
+		};
+	}
+	/**
+	* Generates resource requirements dynamically from discovered + configured jobs.
+	* Each job key maps to a `DATABRICKS_JOB_{KEY_UPPERCASE}` env var (or `DATABRICKS_JOB_ID` for "default").
+	*/
+	static getResourceRequirements(config) {
+		const jobs = JobsPlugin.discoverJobs(config);
+		return Object.keys(jobs).map((key) => ({
+			type: ResourceType.JOB,
+			alias: `job-${key}`,
+			resourceKey: `job-${key}`,
+			description: `Databricks Job "${key}"`,
+			permission: "CAN_MANAGE_RUN",
+			fields: { id: {
+				env: key === "default" ? "DATABRICKS_JOB_ID" : `DATABRICKS_JOB_${key.toUpperCase()}`,
+				description: `Job ID for "${key}"`
+			} },
+			required: true
+		}));
+	}
+	constructor(config) {
+		super(config);
+		this.config = config;
+		this.connector = new JobsConnector({ telemetry: config.telemetry });
+		const jobs = JobsPlugin.discoverJobs(config);
+		this.jobKeys = Object.keys(jobs);
+		this.jobConfigs = jobs;
+		for (const key of this.jobKeys) {
+			const envVar = key === "default" ? "DATABRICKS_JOB_ID" : `DATABRICKS_JOB_${key.toUpperCase()}`;
+			const jobIdStr = process.env[envVar];
+			if (jobIdStr) {
+				const parsed = Number.parseInt(jobIdStr, 10);
+				if (!Number.isNaN(parsed)) this.jobIds[key] = parsed;
+			}
+		}
+	}
+	async setup() {
+		logger.info(`Jobs plugin initialized with ${this.jobKeys.length} job(s): ${this.jobKeys.join(", ")}`);
+	}
+	get client() {
+		return getWorkspaceClient();
+	}
+	getJobId(jobKey) {
+		const id = this.jobIds[jobKey];
+		if (!id) {
+			const envVar = jobKey === "default" ? "DATABRICKS_JOB_ID" : `DATABRICKS_JOB_${jobKey.toUpperCase()}`;
+			throw new Error(`Job "${jobKey}" has no configured job ID. Set ${envVar} env var.`);
+		}
+		return id;
+	}
+	_readSettings(cacheKey) {
+		return { default: {
+			...JOBS_READ_DEFAULTS,
+			...this.config.timeout != null && { timeout: this.config.timeout },
+			cache: {
+				...JOBS_READ_DEFAULTS.cache,
+				cacheKey
+			}
+		} };
+	}
+	_writeSettings() {
+		return { default: {
+			...JOBS_WRITE_DEFAULTS,
+			...this.config.timeout != null && { timeout: this.config.timeout }
+		} };
+	}
+	/**
+	* Validates params against the job's Zod schema (if any) and maps them
+	* to SDK request fields based on the task type. Shared by runNow and runAndWait.
+	*/
+	_validateAndMap(jobKey, params) {
+		const jobConfig = this.jobConfigs[jobKey];
+		let validated = params;
+		if (jobConfig?.params) {
+			const result = jobConfig.params.safeParse(params ?? {});
+			if (!result.success) throw new ValidationError(`Parameter validation failed for job "${jobKey}": ${result.error.message}`);
+			validated = result.data;
+		}
+		return jobConfig?.taskType && validated ? mapParams(jobConfig.taskType, validated) : validated ?? {};
+	}
+	/**
+	* Creates a JobAPI for a specific configured job key.
+	* Each method is scoped to the job's configured ID.
+	*/
+	createJobAPI(jobKey) {
+		const jobId = this.getJobId(jobKey);
+		const jobConfig = this.jobConfigs[jobKey];
+		const self = this;
+		const client = this.client;
+		const userKey = getCurrentUserId();
+		/**
+		* Verify that `runId` belongs to this job's configured `jobId`. Returns
+		* null if the run is in scope; otherwise returns a 404 `ExecutionResult`.
+		* Prevents cross-job access via the `/:jobKey/runs/:runId` HTTP surface.
+		*/
+		const verifyRunScope = async (runId) => {
+			const result = await self.execute(async (signal) => self.connector.getRun(client, { run_id: runId }, signal), self._readSettings([
+				"jobs:getRun",
+				jobKey,
+				runId
+			]), userKey);
+			if (!result.ok) return errorResult(result.status);
+			if (result.data.job_id !== jobId) return errorResult(404);
+			return null;
+		};
+		return {
+			runNow: async (params) => {
+				const sdkFields = self._validateAndMap(jobKey, params);
+				const result = await self.execute(async (signal) => self.connector.runNow(client, {
+					...sdkFields,
+					job_id: jobId
+				}, signal), self._writeSettings(), userKey);
+				return result.ok ? result : errorResult(result.status);
+			},
+			async *runAndWait(params, signal) {
+				const sdkFields = self._validateAndMap(jobKey, params);
+				const runResult = await self.execute(async (signal) => self.connector.runNow(client, {
+					...sdkFields,
+					job_id: jobId
+				}, signal), self._writeSettings(), userKey);
+				if (!runResult.ok) throw new ExecutionError("Failed to trigger job run");
+				const runId = runResult.data.run_id;
+				if (!runId) throw new Error("runNow did not return a run_id");
+				const basePollInterval = self.config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL;
+				const maxPollInterval = basePollInterval * 6;
+				const timeout = jobConfig?.waitTimeout ?? DEFAULT_WAIT_TIMEOUT;
+				const startTime = Date.now();
+				let currentInterval = basePollInterval;
+				while (!signal?.aborted) {
+					if (Date.now() - startTime > timeout) throw new Error(`Job run ${runId} polling timeout after ${timeout}ms`);
+					const runStatusResult = await self.execute(async (signal) => self.connector.getRun(client, { run_id: runId }, signal), { default: {
+						...JOBS_READ_DEFAULTS,
+						cache: { enabled: false }
+					} }, userKey);
+					if (!runStatusResult.ok) throw new ExecutionError(`Failed to poll run status for run ${runId}`);
+					const run = runStatusResult.data;
+					const state = run.state?.life_cycle_state;
+					yield {
+						status: state,
+						timestamp: Date.now(),
+						run
+					};
+					if (isTerminalRunState(state)) return;
+					const { delay, next } = nextPollDelay(currentInterval, maxPollInterval);
+					currentInterval = next;
+					await abortableSleep(delay, signal);
+				}
+			},
+			lastRun: async () => {
+				const result = await self.execute(async (signal) => self.connector.listRuns(client, {
+					job_id: jobId,
+					limit: 1
+				}, signal), self._readSettings(["jobs:lastRun", jobKey]), userKey);
+				if (!result.ok) return errorResult(result.status);
+				return {
+					ok: true,
+					data: result.data[0]
+				};
+			},
+			listRuns: async (options) => {
+				const result = await self.execute(async (signal) => self.connector.listRuns(client, {
+					job_id: jobId,
+					limit: options?.limit
+				}, signal), self._readSettings([
+					"jobs:listRuns",
+					jobKey,
+					options?.limit ?? "default"
+				]), userKey);
+				return result.ok ? result : errorResult(result.status);
+			},
+			getRun: async (runId) => {
+				const result = await self.execute(async (signal) => self.connector.getRun(client, { run_id: runId }, signal), self._readSettings([
+					"jobs:getRun",
+					jobKey,
+					runId
+				]), userKey);
+				if (!result.ok) return errorResult(result.status);
+				if (result.data.job_id !== jobId) return errorResult(404);
+				return result;
+			},
+			getRunOutput: async (runId) => {
+				const scopeError = await verifyRunScope(runId);
+				if (scopeError) return scopeError;
+				const result = await self.execute(async (signal) => self.connector.getRunOutput(client, { run_id: runId }, signal), self._readSettings([
+					"jobs:getRunOutput",
+					jobKey,
+					runId
+				]), userKey);
+				return result.ok ? result : errorResult(result.status);
+			},
+			cancelRun: async (runId) => {
+				const scopeError = await verifyRunScope(runId);
+				if (scopeError) return scopeError;
+				const result = await self.execute(async (signal) => self.connector.cancelRun(client, { run_id: runId }, signal), self._writeSettings(), userKey);
+				return result.ok ? result : errorResult(result.status);
+			},
+			getJob: async () => {
+				const result = await self.execute(async (signal) => self.connector.getJob(client, { job_id: jobId }, signal), self._readSettings(["jobs:getJob", jobKey]), userKey);
+				return result.ok ? result : errorResult(result.status);
+			}
+		};
+	}
+	/**
+	* Resolve `:jobKey` from the request. Returns the key and ID,
+	* or sends a 404 and returns `{ jobKey: undefined, jobId: undefined }`.
+	*/
+	_resolveJob(req, res) {
+		const jobKey = req.params.jobKey;
+		if (!this.jobKeys.includes(jobKey)) {
+			const safeKey = jobKey.replace(/[^a-zA-Z0-9_-]/g, "");
+			res.status(404).json({
+				error: `Unknown job "${safeKey}"`,
+				plugin: this.name
+			});
+			return {
+				jobKey: void 0,
+				jobId: void 0
+			};
+		}
+		const jobId = this.jobIds[jobKey];
+		if (!jobId) {
+			res.status(404).json({
+				error: `Job "${jobKey}" has no configured job ID`,
+				plugin: this.name
+			});
+			return {
+				jobKey: void 0,
+				jobId: void 0
+			};
+		}
+		return {
+			jobKey,
+			jobId
+		};
+	}
+	_sendStatusError(res, status) {
+		res.status(status).json({
+			error: STATUS_CODES[status] ?? "Unknown Error",
+			plugin: this.name
+		});
+	}
+	/**
+	* Validate params from an HTTP request body. Eager validation lets streaming
+	* requests get a clean 400 instead of a generic SSE error event. Throws
+	* ValidationError so handlers can map to a 400 response via their catch block.
+	*/
+	_parseRunParams(jobKey, rawParams) {
+		if (rawParams !== void 0 && (typeof rawParams !== "object" || rawParams === null || Array.isArray(rawParams))) throw new ValidationError("params must be a plain object");
+		const jobConfig = this.jobConfigs[jobKey];
+		if (jobConfig?.params) {
+			if (!jobConfig.params.safeParse(rawParams ?? {}).success) throw new ValidationError("Invalid job parameters");
+			return rawParams;
+		}
+		if (rawParams !== void 0) {
+			if (!jobConfig?.taskType) throw new ValidationError("This job does not accept parameters");
+			const keyCount = Object.keys(rawParams).length;
+			if (keyCount > MAX_UNVALIDATED_PARAM_KEYS) throw new ValidationError(`Too many parameters (${keyCount}). Define a Zod schema to accept more than ${MAX_UNVALIDATED_PARAM_KEYS}.`);
+		}
+		return rawParams;
+	}
+	async _handleRun(req, res) {
+		const { jobKey } = this._resolveJob(req, res);
+		if (!jobKey) return;
+		const stream = req.query.stream === "true";
+		try {
+			const params = this._parseRunParams(jobKey, req.body?.params);
+			const api = this.createJobAPI(jobKey);
+			if (stream) {
+				const streamSettings = { default: JOBS_STREAM_DEFAULTS };
+				await this.executeStream(res, (signal) => api.runAndWait(params, signal), streamSettings);
+			} else {
+				const result = await api.runNow(params);
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json({ runId: result.data.run_id });
+			}
+		} catch (error) {
+			if (error instanceof ValidationError) {
+				if (!res.headersSent) res.status(400).json({
+					error: error.message,
+					plugin: this.name
+				});
+				return;
+			}
+			logger.error("Run failed for job %s: %O", jobKey, error);
+			if (!res.headersSent) res.status(500).json({
+				error: "Run failed",
+				plugin: this.name
+			});
+		}
+	}
+	injectRoutes(router) {
+		this.route(router, {
+			name: "run",
+			method: "post",
+			path: "/:jobKey/run",
+			handler: (req, res) => this._handleRun(req, res)
+		});
+		this.route(router, {
+			name: "runs",
+			method: "get",
+			path: "/:jobKey/runs",
+			handler: async (req, res) => {
+				const { jobKey } = this._resolveJob(req, res);
+				if (!jobKey) return;
+				const limit = Math.max(1, Math.min(Number.parseInt(req.query.limit, 10) || 20, 100));
+				try {
+					const result = await this.createJobAPI(jobKey).listRuns({ limit });
+					if (!result.ok) {
+						this._sendStatusError(res, result.status);
+						return;
+					}
+					res.json({ runs: result.data });
+				} catch (error) {
+					logger.error("List runs failed for job %s: %O", jobKey, error);
+					res.status(500).json({
+						error: "List runs failed",
+						plugin: this.name
+					});
+				}
+			}
+		});
+		this.route(router, {
+			name: "run-detail",
+			method: "get",
+			path: "/:jobKey/runs/:runId",
+			handler: async (req, res) => {
+				const { jobKey } = this._resolveJob(req, res);
+				if (!jobKey) return;
+				const runId = Number.parseInt(req.params.runId, 10);
+				if (Number.isNaN(runId) || runId <= 0) {
+					res.status(400).json({
+						error: "Invalid runId",
+						plugin: this.name
+					});
+					return;
+				}
+				try {
+					const result = await this.createJobAPI(jobKey).getRun(runId);
+					if (!result.ok) {
+						this._sendStatusError(res, result.status);
+						return;
+					}
+					res.json(result.data);
+				} catch (error) {
+					logger.error("Get run failed for job %s run %d: %O", jobKey, runId, error);
+					res.status(500).json({
+						error: "Get run failed",
+						plugin: this.name
+					});
+				}
+			}
+		});
+		this.route(router, {
+			name: "status",
+			method: "get",
+			path: "/:jobKey/status",
+			handler: async (req, res) => {
+				const { jobKey } = this._resolveJob(req, res);
+				if (!jobKey) return;
+				try {
+					const result = await this.createJobAPI(jobKey).lastRun();
+					if (!result.ok) {
+						this._sendStatusError(res, result.status);
+						return;
+					}
+					res.json({
+						status: result.data?.state?.life_cycle_state ?? null,
+						run: result.data ?? null
+					});
+				} catch (error) {
+					logger.error("Status check failed for job %s: %O", jobKey, error);
+					res.status(500).json({
+						error: "Status check failed",
+						plugin: this.name
+					});
+				}
+			}
+		});
+		this.route(router, {
+			name: "cancel-run",
+			method: "delete",
+			path: "/:jobKey/runs/:runId",
+			handler: async (req, res) => {
+				const { jobKey } = this._resolveJob(req, res);
+				if (!jobKey) return;
+				const runId = Number.parseInt(req.params.runId, 10);
+				if (Number.isNaN(runId) || runId <= 0) {
+					res.status(400).json({
+						error: "Invalid runId",
+						plugin: this.name
+					});
+					return;
+				}
+				try {
+					const result = await this.createJobAPI(jobKey).cancelRun(runId);
+					if (!result.ok) {
+						this._sendStatusError(res, result.status);
+						return;
+					}
+					res.status(204).end();
+				} catch (error) {
+					logger.error("Cancel run failed for job %s run %d: %O", jobKey, runId, error);
+					res.status(500).json({
+						error: "Cancel run failed",
+						plugin: this.name
+					});
+				}
+			}
+		});
+	}
+	exports() {
+		const resolveJob = (jobKey) => {
+			if (!this.jobKeys.includes(jobKey)) throw new Error(`Unknown job "${jobKey}". Available jobs: ${this.jobKeys.join(", ")}`);
+			return {
+				...this.createJobAPI(jobKey),
+				asUser: (req) => {
+					return this.asUser(req).createJobAPI(jobKey);
+				}
+			};
+		};
+		return resolveJob;
+	}
+	clientConfig() {
+		const jobs = {};
+		for (const key of this.jobKeys) {
+			const config = this.jobConfigs[key];
+			jobs[key] = {
+				params: config?.params ? toJSONSchema(config.params) : null,
+				taskType: config?.taskType ?? null
+			};
+		}
+		return { jobs };
+	}
+};
+/**
+* @internal
+*/
+const jobs = toPlugin(JobsPlugin);
+
+//#endregion
+export { jobs };
+//# sourceMappingURL=plugin.js.map