c8y-nitro 0.7.1 → 0.8.0

package/dist/options-CmLpZ3Qf.mjs

@@ -0,0 +1,179 @@
+import { c as getTenantOptionsByCategory, f as upsertTenantOption, i as deleteTenantOption, n as createBasicAuthHeader, p as createC8yManifest, s as getCurrentApplicationSettings } from "./c8y-api-DscUs-Kd.mjs";
+import { n as readBootstrapCredentialsFromEnv, r as syncBootstrappedMicroservice } from "./autoBootstrap-Drk7ltXK.mjs";
+import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
+import process from "node:process";
+import { defineCommand } from "citty";
+import { consola } from "consola";
+import { createInterface } from "node:readline/promises";
+//#region src/cli/commands/options.ts
+var options_default = defineCommand({
+	meta: {
+		name: "options",
+		description: "Manage tenant options on the development tenant"
+	},
+	args: {},
+	async run() {
+		consola.info("Loading configuration...");
+		const { env, nitroConfig, configDir } = await loadC8yConfig();
+		consola.info("Validating environment variables...");
+		const envVars = validateBootstrapEnv(env);
+		consola.info("Loading manifest...");
+		const manifest = await createC8yManifest(configDir, nitroConfig);
+		const category = manifest.settingsCategory || manifest.contextPath || manifest.name;
+		if (!manifest.settings || manifest.settings.length === 0) throw new Error("No settings defined in manifest. Add settings to your c8y.manifest configuration.");
+		consola.success(`Using category: ${category}`);
+		const devAuthHeader = createBasicAuthHeader(envVars.C8Y_DEVELOPMENT_TENANT, envVars.C8Y_DEVELOPMENT_USER, envVars.C8Y_DEVELOPMENT_PASSWORD);
+		let bootstrapCredentials;
+		try {
+			consola.info("Checking microservice on development tenant...");
+			bootstrapCredentials = await syncBootstrappedMicroservice({
+				rootDir: configDir,
+				baseUrl: envVars.C8Y_BASEURL,
+				developmentTenant: envVars.C8Y_DEVELOPMENT_TENANT,
+				authHeader: devAuthHeader,
+				manifest,
+				logger: consola,
+				env
+			});
+		} catch (error) {
+			consola.warn(`Could not sync microservice with the development tenant: ${error instanceof Error ? error.message : String(error)}`);
+			bootstrapCredentials = readBootstrapCredentialsFromEnv(env);
+		}
+		const bootstrapAuthHeader = bootstrapCredentials ? createBasicAuthHeader(bootstrapCredentials.tenant, bootstrapCredentials.name, bootstrapCredentials.password) : void 0;
+		if (!bootstrapAuthHeader) consola.warn("No bootstrap credentials available - reading with the development user. Encrypted credentials.* options cannot be decrypted.");
+		consola.info("Fetching current tenant options...");
+		const currentOptions = await getTenantOptionsByCategory(envVars.C8Y_BASEURL, category, devAuthHeader);
+		if (bootstrapAuthHeader) try {
+			const decryptedSettings = await getCurrentApplicationSettings(envVars.C8Y_BASEURL, bootstrapAuthHeader);
+			for (const [key, value] of Object.entries(decryptedSettings)) if (currentOptions[key] !== void 0 || key.startsWith("credentials.")) currentOptions[key] = value;
+		} catch (error) {
+			consola.warn(`Could not read decrypted settings with the bootstrap user: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const availableKeys = manifest.settings.map((s) => s.key);
+		const setManifestKeys = availableKeys.filter((k) => currentOptions[k] !== void 0);
+		consola.success(`Found ${Object.keys(currentOptions).length} options set on tenant (${setManifestKeys.length} of ${availableKeys.length} manifest settings)`);
+		const ctx = {
+			baseUrl: envVars.C8Y_BASEURL,
+			category,
+			devAuthHeader,
+			bootstrapAuthHeader,
+			availableKeys,
+			currentOptions
+		};
+		const action = await consola.prompt("What do you want to do?", {
+			type: "select",
+			options: [
+				{
+					label: "Read option value",
+					value: "read"
+				},
+				{
+					label: "Update/Create option",
+					value: "update"
+				},
+				{
+					label: "Delete option(s)",
+					value: "delete"
+				}
+			]
+		});
+		if (action === "read") await handleRead(ctx);
+		else if (action === "update") await handleUpdate(ctx);
+		else if (action === "delete") await handleDelete(ctx);
+	}
+});
+/**
+* Handle reading options: prints all options at once (decrypted where
+* possible), then - after the user confirms with Enter - rewrites the output
+* in place with `credentials.*` values masked, so secrets don't linger in the
+* terminal scrollback.
+* @param ctx - The shared options context
+*/
+async function handleRead(ctx) {
+	const { bootstrapAuthHeader, availableKeys, currentOptions } = ctx;
+	if (!bootstrapAuthHeader && availableKeys.some((k) => k.startsWith("credentials."))) consola.warn("Encrypted credentials.* options cannot be read in decrypted form without bootstrap credentials. Run `npx c8y-nitro bootstrap` first.");
+	const keys = [.../* @__PURE__ */ new Set([...availableKeys, ...Object.keys(currentOptions)])];
+	const padWidth = Math.max(...keys.map((k) => k.length));
+	const renderLine = (key, maskCredentials) => {
+		const value = currentOptions[key];
+		const shownValue = value === void 0 ? "(not set)" : maskCredentials && key.startsWith("credentials.") ? "****" : value;
+		const suffix = availableKeys.includes(key) ? "" : " (not in manifest)";
+		return `  ${key.padEnd(padWidth)} = ${shownValue}${suffix}`;
+	};
+	const revealedLines = keys.map((key) => renderLine(key, false));
+	process.stdout.write(`${revealedLines.join("\n")}\n`);
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	await rl.question("Press <Enter> to hide credential values...");
+	rl.close();
+	if (process.stdout.isTTY) {
+		const columns = process.stdout.columns || 80;
+		const rowsFor = (line) => Math.max(1, Math.ceil(line.length / columns));
+		const rowsToErase = revealedLines.reduce((rows, line) => rows + rowsFor(line), 1);
+		process.stdout.write(`\x1B[${rowsToErase}A\x1B[0J`);
+		process.stdout.write(`${keys.map((key) => renderLine(key, true)).join("\n")}\n`);
+	}
+}
+/**
+* Handle updating options (with loop for multiple updates)
+* @param ctx - The shared options context
+*/
+async function handleUpdate(ctx) {
+	const { baseUrl, category, devAuthHeader, bootstrapAuthHeader, availableKeys, currentOptions } = ctx;
+	let continueUpdating = true;
+	while (continueUpdating) {
+		const key = await consola.prompt("Select option to update:", {
+			type: "select",
+			options: availableKeys.map((k) => ({
+				label: currentOptions[k] !== void 0 ? `${k} (current: ${currentOptions[k]})` : k.startsWith("credentials.") && !bootstrapAuthHeader ? `${k} (current: unknown)` : `${k} (not set)`,
+				value: k
+			})),
+			cancel: "reject"
+		});
+		const currentValue = currentOptions[key];
+		const newValue = await consola.prompt("Enter new value:", {
+			type: "text",
+			default: currentValue,
+			cancel: "reject"
+		});
+		consola.info(`Updating option: ${key}`);
+		await upsertTenantOption(baseUrl, category, key, newValue, devAuthHeader);
+		currentOptions[key] = newValue;
+		consola.success(`Option '${key}' updated successfully`);
+		if (!await consola.prompt("Update another option?", {
+			type: "confirm",
+			initial: false,
+			cancel: "reject"
+		})) continueUpdating = false;
+	}
+}
+/**
+* Handle deleting multiple options
+* @param ctx - The shared options context
+*/
+async function handleDelete(ctx) {
+	const { baseUrl, category, devAuthHeader, bootstrapAuthHeader, availableKeys, currentOptions } = ctx;
+	const allKeys = bootstrapAuthHeader ? availableKeys.filter((k) => currentOptions[k] !== void 0) : [...availableKeys.filter((k) => !k.startsWith("credentials.") && currentOptions[k] !== void 0), ...availableKeys.filter((k) => k.startsWith("credentials."))];
+	if (allKeys.length === 0) {
+		consola.warn("No options are currently set");
+		return;
+	}
+	const keysToDelete = await consola.prompt("Select option(s) to delete:", {
+		type: "multiselect",
+		options: allKeys,
+		required: true,
+		cancel: "reject"
+	});
+	consola.info(`Deleting ${keysToDelete.length} option(s)...`);
+	for (const key of keysToDelete) {
+		consola.info(`Deleting option: ${key}`);
+		await deleteTenantOption(baseUrl, category, key, devAuthHeader);
+		delete currentOptions[key];
+		consola.success(`✓ Deleted: ${key}`);
+	}
+	consola.success("Delete operation completed");
+}
+//#endregion
+export { options_default as default };

package/dist/{package-D5xRshsx.mjs → package-CNWz76PV.mjs}

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "c8y-nitro";
-var version = "0.7.1";
+var version = "0.8.0";
 var description = "Lightning fast Cumulocity IoT microservice development powered by Nitro";
 //#endregion
 export { name as n, version as r, description as t };

package/dist/{roles-B58Fguop.mjs → roles-B-DNuScZ.mjs}

@@ -1,4 +1,4 @@
-import { n as createBasicAuthHeader, p as createC8yManifest, t as assignUserRole, u as unassignUserRole } from "./c8y-api-BFjK6AYb.mjs";
+import { n as createBasicAuthHeader, p as createC8yManifest, t as assignUserRole, u as unassignUserRole } from "./c8y-api-DscUs-Kd.mjs";
 import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
 import { defineCommand } from "citty";
 import { consola } from "consola";

package/dist/runtime/handlers/invalidateTenantOptions.mjs

@@ -1,5 +1,5 @@
 import { t as createError } from "../../logging-BUYT8Z2V.mjs";
-import { t as useDeployedTenantClient } from "../../client-DxmbyZju.mjs";
+import { t as useDeployedTenantClient } from "../../client-D0Tdq7H1.mjs";
 import { c8yTenantOptionKeys } from "c8y-nitro/runtime";
 import { defineCachedFunction } from "nitro/cache";
 import { useRuntimeConfig } from "nitro/runtime-config";

package/dist/runtime/handlers/openapi.mjs

@@ -1,4 +1,4 @@
-import { n as getUserTenantDomain } from "../../client-DxmbyZju.mjs";
+import { r as tryGetUserTenantDomainFast } from "../../client-D0Tdq7H1.mjs";
 import { c8yManifest } from "c8y-nitro/runtime";
 import { useRuntimeConfig } from "nitro/runtime-config";
 import { getRequestURL } from "nitro/h3";
@@ -14,13 +14,13 @@ function joinURLSegments(origin, ...segments) {
 async function resolveServer(event) {
 	const baseURL = useRuntimeConfig().app?.baseURL;
 	const contextPath = c8yManifest.contextPath ?? c8yManifest.name;
-	if (!import.meta.dev) try {
-		const domain = await getUserTenantDomain(event);
+	if (!import.meta.dev) {
+		const domain = await tryGetUserTenantDomainFast(event);
 		if (domain) return {
 			url: joinURLSegments(`https://${domain}`, "service", contextPath, baseURL),
 			description: "Cumulocity microservice endpoint"
 		};
-	} catch {}
+	}
 	const requestUrl = getRequestURL(event, {
 		xForwardedHost: true,
 		xForwardedProto: true
@@ -43,8 +43,9 @@ async function resolveServer(event) {
 var openapi_default = defineMiddleware(async (event, next) => {
 	const runtimeConfig = useRuntimeConfig();
 	const specRoute = runtimeConfig.nitro?.openAPI?.route || "/_openapi.json";
-	const baseURL = (runtimeConfig.app?.baseURL ?? "/").replace(/\/+$/, "");
-	if (event.url.pathname !== `${baseURL}${specRoute}`) return next();
+	const specPath = `${(runtimeConfig.app?.baseURL ?? "/").replace(/\/+$/, "")}${specRoute}`;
+	const rewrittenSpecPath = `/service/${c8yManifest.contextPath ?? c8yManifest.name}${specPath}`;
+	if (event.url.pathname !== specPath && event.url.pathname !== rewrittenSpecPath) return next();
 	const body = await next();
 	if (!isOpenAPIDocument(body)) return body;
 	const excludedPrefixes = runtimeConfig.c8yOpenApiExcludeRoutes ?? [];

package/dist/runtime/handlers/rewriteRequestUrl.mjs

@@ -0,0 +1,38 @@
+import { n as buildPublicRequestUrl, r as tryGetUserTenantDomainFast } from "../../client-D0Tdq7H1.mjs";
+import { c8yManifest } from "c8y-nitro/runtime";
+import { defineMiddleware } from "nitro";
+//#region src/module/runtime/handlers/rewriteRequestUrl.ts
+/**
+* Rewrites the incoming request URL to the public tenant endpoint.
+*
+* When deployed, the platform proxy forwards requests with the internal
+* cluster host (e.g. `service-scope-t123.<cluster>.svc.cluster.local`) and the
+* `/service/<contextPath>` prefix stripped. Any handler that derives absolute
+* URLs from the request (`event.url`, `getRequestURL(event)`) therefore leaks
+* internal cluster URLs into responses. This middleware swaps `event.url` for
+* the public one (`https://<tenant domain>/service/<contextPath>/...`) before
+* route handlers run, so request-derived URLs come out publicly reachable.
+*
+* The tenant domain is resolved from the requesting user's credentials and
+* memoized in-process, so the per-request overhead after the first resolution
+* is a hash and a Map lookup. Unauthenticated requests (probes, preflights)
+* are passed through untouched.
+*
+* Registered after the scanned runtime middlewares (see registerRuntime) so
+* they still observe the original URL, and before the OpenAPI transform,
+* which reuses the tenant domain resolved here from its cache.
+*/
+var rewriteRequestUrl_default = defineMiddleware(async (event, next) => {
+	if (import.meta.dev) return next();
+	const domain = await tryGetUserTenantDomainFast(event);
+	if (domain && event.url.host !== domain) {
+		event.url = buildPublicRequestUrl(domain, c8yManifest.contextPath ?? c8yManifest.name, event.url);
+		try {
+			event.req.headers.set("x-forwarded-host", domain);
+			event.req.headers.set("x-forwarded-proto", "https");
+		} catch {}
+	}
+	return next();
+});
+//#endregion
+export { rewriteRequestUrl_default as default };

package/dist/utils.d.mts

@@ -502,110 +502,264 @@ declare function useLogger<T extends object = Record<string, unknown>>(eventOrRe
  */
 declare const createError: typeof createError$1;
 //#endregion
-//#region src/utils/schedule.d.ts
-type ScheduledTaskPayload = TaskPayload;
-type ScheduledTaskContext = TaskContext;
+//#region src/utils/tasks.d.ts
 /**
- * A one-shot schedule definition for `scheduleTask()`.\
- * Numbers are treated as seconds from now, strings are parsed as human-readable durations
- * such as `"10 minutes"`, and dates are used as exact run times.
+ * Concurrency policy for a single job.
+ * - `'single'`: at most one run of the job is in flight at a time. A tick that
+ *   fires while the previous run is still going is skipped, and a manual
+ *   {@link TaskRegistry.triggerJob} while a run is active joins the in-flight run.
+ * - `'parallel'`: every tick (or trigger) starts a fresh run, even if a previous
+ *   run has not finished. Runs of the same job may overlap.
  */
-type ScheduledTaskInput = Date | number | string;
+type JobConcurrency = 'single' | 'parallel';
+type TaskRegistryPayload = TaskPayload;
+type TaskRegistryContext = TaskContext;
 /**
- * Options for scheduling a Nitro task to run once in the future.\
- * `payload` and `context` are forwarded to the task handler's `run()` method.
+ * The event passed to a task handler on every execution.
  */
-interface ScheduleTaskOptions {
+interface TaskEvent<TPayload = TaskRegistryPayload> {
   /**
-   * Payload forwarded to the task handler's `TaskEvent.payload`.
+   * Name of the task (function) being executed.
    */
-  payload?: ScheduledTaskPayload;
+  task: string;
+  /**
+   * Name of the job that triggered this run, when the run originates from a scheduled or triggered job.
+   */
+  job?: string;
+  /**
+   * Data bound when the job was scheduled (or passed to `run()`/`triggerJob()`).
+   */
+  payload: TPayload;
+  /**
+   * Arbitrary context bound alongside the payload.
+   */
+  context: TaskRegistryContext;
+}
+/**
+ * A task handler function registered via {@link TaskRegistry.createTask}.
+ */
+type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: TaskEvent<TPayload>) => TResult | Promise<TResult>;
+/**
+ * When a job should run.
+ * - `{ cron }`: recurring on a cron expression. 5- or 6-field (with seconds) is
+ *   supported. Evaluated in UTC by default, or in the job's `timezone` if set.
+ * - `{ in }`: one-shot, `in` seconds from now.
+ * - `{ at }`: one-shot, at an exact instant given as a `Date` or ISO 8601 string,
+ *   taken literally (never re-projected to another timezone). Times in the past
+ *   fire almost immediately.
+ */
+type JobSchedule = {
+  cron: string;
+} | {
+  in: number;
+} | {
+  at: Date | string;
+};
+/**
+ * Options for scheduling a job via {@link TaskRegistry.scheduleJob}.
+ */
+interface ScheduleJobOptions<TTask extends string = string, TPayload = TaskRegistryPayload, TSchedule extends JobSchedule = JobSchedule> {
+  /**
+   * Unique, caller-chosen job name. This is the handle used by `cancelJob()`, `getJob()` and `triggerJob()`.
+   */
+  name: string;
+  /**
+   * Name of a task registered via `createTask()` that this job runs.
+   */
+  task: TTask;
+  /**
+   * When the job should run.
+   */
+  schedule: TSchedule;
+  /**
+   * Data forwarded to the handler's `event.payload`.\
+   * Prefer stable identifiers (e.g. a config id) over live object references so the
+   * handler can resolve current values at run time and the schedule stays serializable.
+   */
+  payload?: TPayload;
   /**
-   * Context forwarded to the task handler's `TaskEvent.context`.
+   * Data forwarded to the handler's `event.context`.
    */
-  context?: ScheduledTaskContext;
+  context?: TaskRegistryContext;
   /**
-   * When the task should run. Numbers are seconds from now.
+   * Concurrency policy for this job. Defaults to `'single'`.
    */
-  schedule: ScheduledTaskInput;
+  concurrency?: JobConcurrency;
+  /**
+   * Recurring only: the IANA timezone the cron expression is evaluated in
+   * (e.g. `'Europe/Berlin'`). Defaults to `'UTC'` so the schedule is deterministic
+   * regardless of the container's local time. croner performs the alignment — no
+   * conversion is done by `c8y-nitro`. Ignored for one-shot schedules.
+   */
+  timezone?: string;
+  /**
+   * Recurring only: also run once immediately on registration, in addition to the cron. Defaults to `false`.
+   */
+  immediate?: boolean;
+  /**
+   * Recurring only: stop after this many scheduled runs.
+   */
+  maxRuns?: number;
+  /**
+   * Overwrite an existing job with the same name instead of throwing. Defaults to `false`.
+   */
+  replace?: boolean;
 }
 /**
- * Public information about a pending scheduled task.\
- * Returned by `scheduleTask()` and by `listScheduledTasks()`.
+ * Fields common to every job, regardless of kind.
  */
-interface ScheduledTaskInfo {
+interface BaseJobInfo {
   /**
-   * Stable UUID used to list or cancel the scheduled task.
+   * The job's unique name.
    */
-  id: string;
+  name: string;
   /**
-   * Nitro task name that will be passed to `runTask()`.
+   * The task (function) the job runs.
    */
   task: string;
   /**
-   * Exact execution time as an ISO date string.
+   * The job's concurrency policy.
+   */
+  concurrency: JobConcurrency;
+  /**
+   * Next scheduled execution as an ISO datetime string, or `null` if nothing is pending.
+   */
+  nextRun: string | null;
+  /**
+   * Whether a run of this job is currently in flight.
    */
-  runAt: string;
+  running: boolean;
 }
 /**
- * Schedules a Nitro task to run once in the future.\
- * Resolves and calls the task handler directly from Nitro's virtual task registry\
- * Numbers are treated as seconds, strings are parsed as human-readable durations, and dates are used as exact run times.
- *
- * @param taskName - The Nitro task name to run (from `tasks/*.ts`)
- * @param options - Task payload, context, and the schedule time
- * @returns Information about the scheduled task
- *
- * @example
- * // Run a task in 30 seconds:
- * const scheduled = await scheduleTask('emails:send', {
- *   payload: { messageId: 'abc123' },
- *   schedule: 30,
- * })
- *
- * @example
- * // Run a task using a human-readable duration:
- * await scheduleTask('reports:generate', {
- *   payload: { reportId: 'report-1' },
- *   schedule: '1 hour',
- * })
- *
- * @example
- * // Run a task at an exact time:
- * await scheduleTask('cleanup:tenant', {
- *   payload: { tenant: 't12345' },
- *   schedule: new Date('2026-05-01T12:00:00Z'),
- * })
+ * Information about a one-shot job (scheduled with `{ in }` or `{ at }`).
+ */
+interface OnceJobInfo extends BaseJobInfo {
+  kind: 'once';
+  /**
+   * Always `null` for one-shot jobs.
+   */
+  cron: null;
+}
+/**
+ * Information about a recurring job (scheduled with `{ cron }`).
  */
-declare function scheduleTask(taskName: string, options: ScheduleTaskOptions): Promise<ScheduledTaskInfo>;
+interface RecurringJobInfo extends BaseJobInfo {
+  kind: 'recurring';
+  /**
+   * The cron expression the job runs on.
+   */
+  cron: string;
+  /**
+   * The IANA timezone the cron expression is evaluated in.
+   */
+  timezone: string;
+  /**
+   * A few upcoming executions as ISO datetime strings.
+   */
+  nextRuns: string[];
+}
 /**
- * Lists all tasks that are currently scheduled and have not started yet.\
- * The returned object is keyed by the scheduled task UUID for easy lookup and cancellation.
- *
- * @returns Object mapping scheduled task IDs to their public task information
- *
- * @example
- * const tasks = await listScheduledTasks()
- * for (const [id, task] of Object.entries(tasks)) {
- *   console.log(id, task.task, task.runAt)
- * }
+ * Public information about a registered job. A discriminated union on `kind` —
+ * returned by `scheduleJob()`, `getJob()` and `listJobs()`.
  */
-declare function listScheduledTasks(): Promise<Record<string, ScheduledTaskInfo>>;
+type JobInfo = OnceJobInfo | RecurringJobInfo;
 /**
- * Cancels a scheduled task before it starts running.\
- * Once the underlying Nitro task has started, it cannot be cancelled with this utility.
+ * Maps a {@link JobSchedule} to the {@link JobInfo} variant it produces.
+ */
+type JobInfoFor<TSchedule extends JobSchedule> = TSchedule extends {
+  cron: string;
+} ? RecurringJobInfo : OnceJobInfo;
+/**
+ * Describes the payload and result type of a single registered task.
+ */
+interface TaskShape<TPayload = TaskRegistryPayload, TResult = unknown> {
+  payload: TPayload;
+  result: TResult;
+}
+/**
+ * A map of task name to its {@link TaskShape}, accumulated by the builder.
+ */
+type TaskMap = Record<string, TaskShape>;
+/**
+ * A type-charged registry of tasks (functions) and the jobs that schedule them.
  *
- * @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
- * @returns `true` when a pending task was cancelled, otherwise `false`
+ * Each `createTask()` call widens the registry's type with the new task name, so
+ * `run()`, `scheduleJob()` and `triggerJob()` autocomplete known task names and
+ * reject typos at compile time.
+ */
+interface TaskRegistry<TTasks extends TaskMap = {}> {
+  /**
+   * Registers a task (function) under a compile-time-known name.\
+   * Passing a name that is already registered is a type error (and throws at runtime).
+   *
+   * @param name - Unique task name
+   * @param handler - The function to run. Annotate its event to type the payload,
+   * e.g. `(e: TaskEvent<{ configId: string }>) => ...`.
+   */
+  createTask: <TName extends string, TPayload extends TaskRegistryPayload = TaskRegistryPayload, TResult = unknown>(name: TName extends keyof TTasks ? never : TName, handler: TaskHandler<TPayload, TResult>) => TaskRegistry<TTasks & Record<TName, TaskShape<TPayload, TResult>>>;
+  /**
+   * Runs a task immediately and ad-hoc, without registering a job. Always runs
+   * fresh (no deduplication). Use a job with `'single'` concurrency when you need
+   * overlap protection.
+   */
+  run: <TName extends keyof TTasks & string>(task: TName, options?: {
+    payload?: TTasks[TName]['payload'];
+    context?: TaskRegistryContext;
+  }) => Promise<TTasks[TName]['result']>;
+  /**
+   * Schedules a named job that runs a task once or repeatedly. The return type is
+   * inferred from the schedule: `{ cron }` yields a {@link RecurringJobInfo},
+   * `{ in }`/`{ at }` yield a {@link OnceJobInfo}.
+   */
+  scheduleJob: <TName extends keyof TTasks & string, TSchedule extends JobSchedule>(options: ScheduleJobOptions<TName, TTasks[TName]['payload'], TSchedule>) => JobInfoFor<TSchedule>;
+  /**
+   * Runs an already-registered job immediately, respecting its concurrency policy.
+   * For a `'single'` job with a run in flight this returns the in-flight promise.
+   */
+  triggerJob: <TResult = unknown>(name: string, options?: {
+    payload?: TaskRegistryPayload;
+    context?: TaskRegistryContext;
+  }) => Promise<TResult>;
+  /**
+   * Cancels a scheduled job by name.
+   * @returns `true` when a job was found and cancelled, otherwise `false`.
+   */
+  cancelJob: (name: string) => boolean;
+  /**
+   * Lists all currently registered jobs.
+   */
+  listJobs: () => JobInfo[];
+  /**
+   * Returns information about a single job, or `undefined` if it does not exist.
+   */
+  getJob: (name: string) => JobInfo | undefined;
+  /**
+   * Returns `true` when a task with the given name is registered.
+   */
+  hasTask: (name: string) => boolean;
+}
+/**
+ * Creates a new, empty task registry.
  *
  * @example
- * const scheduled = await scheduleTask('emails:send', {
- *   payload: { messageId: 'abc123' },
- *   schedule: '10 minutes',
- * })
+ * import { c8yTasks } from 'c8y-nitro/utils'
+ *
+ * export const tasks = c8yTasks()
+ *   .createTask('sync', async ({ payload }) => {
+ *     const config = await loadConfig(payload.configId) // resolve live state here
+ *     await sync(config)
+ *   })
+ *
+ * // one per config, each an independent job
+ * tasks.scheduleJob({ name: 'sync-abc', task: 'sync', payload: { configId: 'abc' }, schedule: { cron: '*\/5 * * * *' } })
+ * tasks.scheduleJob({ name: 'sync-def', task: 'sync', payload: { configId: 'def' }, schedule: { cron: '*\/5 * * * *' }, concurrency: 'parallel' })
  *
- * const cancelled = await cancelScheduledTask(scheduled.id)
+ * @remarks
+ * The registry is a plain runtime singleton — export it from one module and import
+ * it wherever you schedule or cancel jobs. Recurring jobs only arm when the module
+ * that schedules them executes, so register them from a Nitro plugin (or another
+ * startup path) if they must run from boot.
  */
-declare function cancelScheduledTask(id: string): Promise<boolean>;
+declare function c8yTasks(): TaskRegistry;
 //#endregion
-export { ForeignTenantOptionCategory, ForeignTenantOptionKeyInput, ScheduleTaskOptions, ScheduledTaskContext, ScheduledTaskInfo, ScheduledTaskInput, ScheduledTaskPayload, SetEditableOptions, TenantOption, TenantOptionCategory, TenantOptionKeyInput, cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+export { BaseJobInfo, ForeignTenantOptionCategory, ForeignTenantOptionKeyInput, JobConcurrency, JobInfo, JobInfoFor, JobSchedule, OnceJobInfo, RecurringJobInfo, ScheduleJobOptions, SetEditableOptions, TaskEvent, TaskHandler, TaskMap, TaskRegistry, TaskRegistryContext, TaskRegistryPayload, TaskShape, TenantOption, TenantOptionCategory, TenantOptionKeyInput, c8yTasks, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };