c8y-nitro 0.7.2 → 0.9.0

package/dist/utils.mjs

@@ -1,5 +1,6 @@
+import { createRealtimeClient } from "c8y-realtime";
+import { createHash, randomBytes } from "node:crypto";
 import { Buffer } from "node:buffer";
-import { createHash, randomBytes, randomUUID } from "node:crypto";
 import process from "node:process";
 import { useLogger as useLogger$1 } from "evlog/nitro/v3";
 import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
@@ -9,10 +10,22 @@ import { useRuntimeConfig } from "nitro/runtime-config";
 import { useNitroHooks } from "nitro/app";
 import { defineHandler } from "nitro/h3";
 import { c8yManifest } from "c8y-nitro/runtime";
+import { Cron } from "croner";
 import { ms } from "itty-time";
-import { tasks } from "#nitro/virtual/tasks";
 //#region src/utils/internal/common.ts
 /**
+* Whether two sets of tenant credentials are equivalent for the purposes of
+* change detection: same tenant, user, and password. Used to detect a
+* service-user password rotation (which keeps the tenant id but changes the
+* secret), not just tenants entering/leaving the subscription set.
+* @param a - First credentials, or `undefined` when the tenant is absent
+* @param b - Second credentials, or `undefined` when the tenant is absent
+*/
+function credsEqual(a, b) {
+	if (!a || !b) return a === b;
+	return a.tenant === b.tenant && a.user === b.user && a.password === b.password;
+}
+/**
 * Converts undici Request headers to the format expected by MicroserviceClientRequestAuth.\
 * Extracts the following headers from the request:
 * - `authorization`: Used for Basic Auth or Bearer token authentication
@@ -177,10 +190,9 @@ const createError = createError$1;
 let prevCredentials = null;
 function shouldEmitTenantCredentialsUpdated(prev, next) {
 	if (!prev) return true;
-	const prevTenantIds = Object.keys(prev);
-	const nextTenantIds = Object.keys(next);
-	if (prevTenantIds.length !== nextTenantIds.length) return true;
-	return new Set(nextTenantIds).symmetricDifference(new Set(prevTenantIds)).size > 0;
+	const tenantIds = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
+	for (const tenantId of tenantIds) if (!credsEqual(prev[tenantId], next[tenantId])) return true;
+	return false;
 }
 /**
 * Fetches credentials for all tenants subscribed to this microservice.\
@@ -384,6 +396,97 @@ async function useDeployedTenantClient() {
 	return client;
 }
 //#endregion
+//#region src/utils/paging.ts
+async function resolvePageSource(source) {
+	return await (typeof source === "function" ? source() : source);
+}
+/**
+* Lazily walks a Cumulocity list result page by page, yielding each page's data
+* array. This is the engine behind {@link paginate} and {@link fetchAllPages}.
+*
+* Pages are fetched on demand: the next request is only issued when the consumer
+* asks for the next value. Iteration stops when a page comes back shorter than
+* the requested page size (Cumulocity's signal that there is no more data),
+* when the result carries no paging information, or when a {@link PagingOptions}
+* guard is hit.
+*
+* @param source - The first page (result, promise, or thunk). See {@link PageSource}.
+* @param options - Optional {@link PagingOptions} safety guards.
+* @yields Each page as an array of items.
+* @example
+* // Process one page at a time (e.g. bulk insert per page):
+* for await (const page of paginatePages(client.event.list({ pageSize: 2000 }))) {
+*   await bulkInsert(page)
+* }
+*/
+async function* paginatePages(source, options = {}) {
+	const { maxPages, maxItems } = options;
+	let result = await resolvePageSource(source);
+	let pagesSeen = 0;
+	let itemsSeen = 0;
+	while (true) {
+		pagesSeen++;
+		let page = result.data ?? [];
+		if (maxItems != null && page.length > maxItems - itemsSeen) page = page.slice(0, Math.max(0, maxItems - itemsSeen));
+		if (page.length > 0) {
+			yield page;
+			itemsSeen += page.length;
+		}
+		if (maxItems != null && itemsSeen >= maxItems) break;
+		if (maxPages != null && pagesSeen >= maxPages) break;
+		const paging = result.paging;
+		if (!paging) break;
+		const fullPage = paging.pageSize ? (result.data?.length ?? 0) >= paging.pageSize : true;
+		const hasNextPage = paging.nextPage != null && paging.nextPage > paging.currentPage;
+		if (!fullPage || !hasNextPage) break;
+		result = await paging.next();
+	}
+}
+/**
+* Lazily iterates every item across all pages of a Cumulocity list result,
+* yielding one entry at a time — ideal for streaming large collections with a
+* low memory footprint.
+*
+* Pages are fetched on demand as iteration advances, walking via the result's
+* own `paging.next()` (same client and filter as the first page). Iteration
+* stops when a page comes back shorter than the requested page size.
+*
+* @param source - The first page (result, promise, or thunk). See {@link PageSource}.
+* @param options - Optional {@link PagingOptions} safety guards.
+* @yields Each item, in order, across all pages.
+* @example
+* // Stream every active alarm, one at a time:
+* for await (const alarm of paginate(() => client.alarm.list({ pageSize: 2000, status: 'ACTIVE' }))) {
+*   await handleAlarm(alarm)
+* }
+*/
+async function* paginate(source, options) {
+	for await (const page of paginatePages(source, options)) yield* page;
+}
+/**
+* Collects every item across all pages of a Cumulocity list result into a single
+* array, awaiting until all pages have been fetched.
+*
+* Walks via the result's own `paging.next()` (same client and filter as the
+* first page), stopping when a page comes back shorter than the requested page
+* size. For very large collections prefer {@link paginate} to avoid holding
+* every item in memory at once, or cap the result with
+* {@link PagingOptions.maxItems}.
+*
+* @param source - The first page (result, promise, or thunk). See {@link PageSource}.
+* @param options - Optional {@link PagingOptions} safety guards.
+* @returns All items across all pages, in order.
+* @example
+* // Fetch every managed object matching a fragment:
+* const client = useUserClient(event)
+* const all = await fetchAllPages(client.inventory.list({ pageSize: 2000, fragmentType: 'c8y_Sensor' }))
+*/
+async function fetchAllPages(source, options) {
+	const all = [];
+	for await (const page of paginatePages(source, options)) all.push(...page);
+	return all;
+}
+//#endregion
 //#region src/utils/resources.ts
 /**
 * Fetches the current user from Cumulocity using credentials extracted from the current request's headers.
@@ -884,168 +987,335 @@ const useTenantOptions = Object.assign(useTenantOptionsBase, {
 	refreshAll: () => refreshFetchers(() => true)
 });
 //#endregion
-//#region src/utils/schedule.ts
-const MAX_TIMEOUT_MS = 2147483647;
-const SCHEDULE_LOOKAHEAD_MS = 3600 * 1e3;
-const SCHEDULER_TICK_MS = 100;
-const scheduledTasks = /* @__PURE__ */ new Map();
-const scheduledTaskTimers = /* @__PURE__ */ new Map();
-const schedulerReady = Promise.resolve();
-let schedulerInterval;
-function createScheduledTaskId() {
-	return randomUUID();
+//#region src/utils/tasks.ts
+function resolveOnceDate(schedule) {
+	if ("in" in schedule) {
+		if (typeof schedule.in === "string") {
+			const delay = ms(schedule.in);
+			if (!Number.isFinite(delay) || delay < 0) throw new TypeError(`schedule.in must be a valid duration string (e.g. "5 minutes"), got "${schedule.in}"`);
+			return new Date(Date.now() + delay);
+		}
+		if (!Number.isFinite(schedule.in) || schedule.in < 0) throw new TypeError("schedule.in must be a non-negative number of seconds");
+		return new Date(Date.now() + schedule.in * 1e3);
+	}
+	const date = schedule.at instanceof Date ? schedule.at : new Date(schedule.at);
+	if (Number.isNaN(date.getTime())) throw new TypeError("schedule.at must be a valid Date or ISO 8601 string");
+	return date;
 }
-function resolveScheduleTime(schedule) {
-	if (schedule instanceof Date) {
-		const timestamp = schedule.getTime();
-		if (Number.isNaN(timestamp)) throw new TypeError("schedule date must be valid");
-		return timestamp;
+/**
+* Creates a new, empty task registry.
+*
+* @example
+* 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' })
+*
+* @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.
+*/
+function c8yTasks() {
+	const tasks = /* @__PURE__ */ new Map();
+	const jobs = /* @__PURE__ */ new Map();
+	function execute(record, override) {
+		const definition = tasks.get(record.task);
+		if (!definition) return Promise.reject(/* @__PURE__ */ new Error(`Task "${record.task}" is not registered`));
+		if (record.concurrency === "single" && record.inFlight) return record.inFlight;
+		const event = {
+			task: record.task,
+			job: record.name,
+			payload: override?.payload ?? record.payload,
+			context: override?.context ?? record.context
+		};
+		const promise = (async () => definition.handler(event))();
+		if (record.concurrency === "single") {
+			record.inFlight = promise;
+			promise.finally(() => {
+				if (record.inFlight === promise) record.inFlight = void 0;
+			});
+		}
+		return promise;
+	}
+	function toJobInfo(record) {
+		const next = record.cron.nextRun();
+		const base = {
+			name: record.name,
+			task: record.task,
+			concurrency: record.concurrency,
+			nextRun: next ? next.toISOString() : null,
+			running: record.inFlight !== void 0
+		};
+		if (record.kind === "recurring") return {
+			...base,
+			kind: "recurring",
+			cron: record.cronExpr,
+			timezone: record.timezone,
+			nextRuns: record.cron.nextRuns(3).map((date) => date.toISOString())
+		};
+		return {
+			...base,
+			kind: "once",
+			cron: null
+		};
 	}
-	if (typeof schedule === "number") {
-		if (!Number.isFinite(schedule) || schedule < 0) throw new TypeError("schedule number must be a non-negative number of seconds");
-		return Date.now() + schedule * 1e3;
+	function cancelJob(name) {
+		const record = jobs.get(name);
+		if (!record) return false;
+		record.cron.stop();
+		return jobs.delete(name);
 	}
-	const delay = ms(schedule);
-	if (!Number.isFinite(delay) || delay < 0) throw new TypeError("schedule string must be a valid non-negative duration");
-	return Date.now() + delay;
+	const api = {
+		createTask(name, handler) {
+			if (typeof name !== "string" || !name) throw new TypeError("task name is required");
+			if (tasks.has(name)) throw new Error(`Task "${name}" is already registered`);
+			tasks.set(name, {
+				name,
+				handler
+			});
+			return api;
+		},
+		async run(task, options) {
+			const definition = tasks.get(task);
+			if (!definition) throw new Error(`Task "${task}" is not registered`);
+			return definition.handler({
+				task,
+				payload: options?.payload ?? {},
+				context: options?.context ?? {}
+			});
+		},
+		scheduleJob(options) {
+			const { name, task, schedule, concurrency = "single", replace = false } = options;
+			if (!name) throw new TypeError("job name is required");
+			if (!tasks.has(task)) throw new Error(`Task "${task}" is not registered. Register it with createTask() first.`);
+			if (jobs.has(name)) {
+				if (!replace) throw new Error(`Job "${name}" already exists. Pass { replace: true } to overwrite it.`);
+				cancelJob(name);
+			}
+			const isRecurring = "cron" in schedule;
+			const timezone = options.timezone ?? "UTC";
+			const record = {
+				name,
+				task,
+				kind: isRecurring ? "recurring" : "once",
+				concurrency,
+				cronExpr: isRecurring ? schedule.cron : null,
+				timezone,
+				payload: options.payload ?? {},
+				context: options.context ?? {},
+				cron: void 0
+			};
+			const callback = () => {
+				Promise.resolve(execute(record)).catch((error) => {
+					console.error(`c8y-nitro: job "${name}" (task "${task}") failed`, error);
+				}).finally(() => {
+					if (!record.cron.nextRun()) jobs.delete(name);
+				});
+			};
+			if (isRecurring) {
+				const cronOptions = { timezone };
+				if (typeof options.maxRuns === "number") cronOptions.maxRuns = options.maxRuns;
+				record.cron = new Cron(schedule.cron, cronOptions, callback);
+			} else {
+				const fireAt = Math.max(resolveOnceDate(schedule).getTime(), Date.now() + 50);
+				record.cron = new Cron(new Date(fireAt), { maxRuns: 1 }, callback);
+			}
+			jobs.set(name, record);
+			if (isRecurring && options.immediate) Promise.resolve(execute(record)).catch((error) => {
+				console.error(`c8y-nitro: job "${name}" immediate run failed`, error);
+			});
+			return toJobInfo(record);
+		},
+		triggerJob(name, options) {
+			const record = jobs.get(name);
+			if (!record) throw new Error(`Job "${name}" is not registered`);
+			return execute(record, options);
+		},
+		cancelJob,
+		listJobs() {
+			return [...jobs.values()].map(toJobInfo);
+		},
+		getJob(name) {
+			const record = jobs.get(name);
+			return record ? toJobInfo(record) : void 0;
+		},
+		hasTask(name) {
+			return tasks.has(name);
+		}
+	};
+	return api;
 }
-async function executeScheduledTask(id) {
-	const record = scheduledTasks.get(id);
-	if (!record) return;
-	if (record.timeoutId !== void 0) scheduledTaskTimers.delete(record.timeoutId);
-	scheduledTasks.delete(id);
-	stopSchedulerIntervalIfIdle();
-	const taskDef = tasks[record.taskName];
-	if (!taskDef) throw new Error(`Task "${record.taskName}" is not available!`);
-	if (!taskDef.resolve) throw new Error(`Task "${record.taskName}" is not implemented!`);
-	await (await taskDef.resolve()).run({
-		name: record.taskName,
-		payload: record.payload,
-		context: record.context
-	});
+//#endregion
+//#region src/utils/realtime.ts
+const REPAIR_SWEEP_INTERVAL_MS = 3e4;
+const pool = /* @__PURE__ */ new Map();
+let lifecycleWired = false;
+let sweepTimer;
+let sweeping = false;
+function realtimeConfig() {
+	return useRuntimeConfig().c8yRealtime;
 }
-function armScheduledTaskTimeout(id) {
-	const record = scheduledTasks.get(id);
-	if (!record || record.timeoutId !== void 0) return;
-	const remainingMs = Math.max(record.runAt - Date.now(), 0);
-	if (remainingMs > SCHEDULE_LOOKAHEAD_MS) return;
-	const timeout = setTimeout(() => {
-		executeScheduledTask(id);
-	}, Math.min(remainingMs, MAX_TIMEOUT_MS));
-	record.timeoutId = Number(timeout);
-	scheduledTaskTimers.set(record.timeoutId, timeout);
+/**
+* Distinguish tenant credentials from a request. Every field on `ICredentials`
+* is optional, so a bare `'password' in x` doesn't narrow the union — this
+* predicate does. A request never carries `user`/`password`/`tenant`.
+* @param input - A value already narrowed to credentials or a request.
+*/
+function isCredentials(input) {
+	return "user" in input || "password" in input || "tenant" in input;
 }
-function runSchedulerTick() {
-	for (const record of scheduledTasks.values()) armScheduledTaskTimeout(record.id);
+/**
+* Shape c8y-nitro's `ICredentials` into the single-tenant credentials
+* `c8y-realtime` expects (it needs the `baseUrl`, which lives in the env).
+* @param tenantId - The tenant the credentials belong to.
+* @param creds - The tenant's service credentials.
+*/
+function toLibCredentials(tenantId, creds) {
+	return {
+		baseUrl: process.env.C8Y_BASEURL,
+		tenant: creds.tenant ?? tenantId,
+		user: creds.user,
+		password: creds.password
+	};
 }
-function ensureSchedulerInterval() {
-	if (schedulerInterval) return;
-	schedulerInterval = setInterval(runSchedulerTick, SCHEDULER_TICK_MS);
+function createRealtimeClientForTenant(tenantId, creds) {
+	return createRealtimeClient({
+		...realtimeConfig(),
+		...toLibCredentials(tenantId, creds),
+		logger: console
+	});
 }
-function stopSchedulerIntervalIfIdle() {
-	if (!schedulerInterval || scheduledTasks.size > 0) return;
-	clearInterval(schedulerInterval);
-	schedulerInterval = void 0;
+async function subscribedCredsFor(tenantId) {
+	const creds = (await useSubscribedTenantCredentials())[tenantId];
+	if (!creds) throw createError({
+		status: 500,
+		message: `No subscribed tenant credentials found for tenant '${tenantId}'`
+	});
+	return creds;
 }
-/**
-* 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'),
-* })
-*/
-async function scheduleTask(taskName, options) {
-	if (!import.meta._tasks) throw new Error("scheduleTask() requires tasks to be enabled. Set `experimental: { tasks: true }` in your nitro.config.ts.");
-	if (!taskName) throw new TypeError("taskName is required");
-	const runAt = resolveScheduleTime(options.schedule);
-	const record = {
-		id: createScheduledTaskId(),
-		taskName,
-		payload: options.payload ?? {},
-		context: options.context ?? {},
-		runAt
+async function resolveTenant(input) {
+	if (typeof input === "string") return {
+		tenantId: input,
+		creds: await subscribedCredsFor(input)
 	};
-	scheduledTasks.set(record.id, record);
-	armScheduledTaskTimeout(record.id);
-	ensureSchedulerInterval();
+	if (input instanceof Client) {
+		const tenantId = input.core.tenant ?? (await input.tenant.current()).data.name;
+		if (!tenantId) throw createError({
+			status: 500,
+			message: "Could not resolve a tenant id from the provided client"
+		});
+		return {
+			tenantId,
+			creds: await subscribedCredsFor(tenantId)
+		};
+	}
+	if (isCredentials(input)) {
+		const tenantId = input.tenant;
+		if (!tenantId) throw createError({
+			status: 500,
+			message: "The provided credentials have no tenant"
+		});
+		return {
+			tenantId,
+			creds: input
+		};
+	}
+	const tenantId = await getCurrentUserTenantId(input);
 	return {
-		id: record.id,
-		task: record.taskName,
-		runAt: new Date(record.runAt).toISOString()
+		tenantId,
+		creds: await subscribedCredsFor(tenantId)
 	};
 }
 /**
-* 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.
+* Repair pooled clients that have gone unhealthy — a consumer stopped because
+* its credentials ran out (rotation) or were revoked and later reissued
+* (unsubscribe → resubscribe). `RealtimeClient.updateCredentials` may only be
+* called while a client is unhealthy and validates the new creds with a probe,
+* so this is the trigger that actually performs the repair.
 *
-* @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)
-* }
+* Cheap when nothing is wrong: it only forces a credential refresh when there is
+* an unhealthy client whose tenant is still subscribed (so its stored creds may
+* be stale). A client whose tenant is gone is left idle — its handlers are kept
+* for a possible return, and no platform call is made on its behalf.
 */
-async function listScheduledTasks() {
-	await schedulerReady;
-	return Object.fromEntries([...scheduledTasks.values()].map((record) => [record.id, {
-		id: record.id,
-		task: record.taskName,
-		runAt: new Date(record.runAt).toISOString()
-	}]));
+async function repairUnhealthyClients() {
+	if (sweeping) return;
+	sweeping = true;
+	try {
+		const cached = await useSubscribedTenantCredentials();
+		const repairable = [...pool].filter(([tenantId, client]) => !client.healthy && cached[tenantId]);
+		if (repairable.length === 0) return;
+		const fresh = await useSubscribedTenantCredentials.refresh();
+		for (const [tenantId, client] of repairable) {
+			const creds = fresh[tenantId];
+			if (!creds) continue;
+			try {
+				await client.updateCredentials(toLibCredentials(tenantId, creds));
+			} catch (error) {
+				console.error(`c8y-nitro realtime: could not repair client for tenant '${tenantId}'`, error);
+			}
+		}
+	} finally {
+		sweeping = false;
+	}
 }
 /**
-* Cancels a scheduled task before it starts running.\
-* Once the underlying Nitro task has started, it cannot be cancelled with this utility.
-*
-* @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
-* @returns `true` when a pending task was cancelled, otherwise `false`
+* Wire the realtime lifecycle exactly once, on first client creation. There is
+* nothing to manage until a client exists, so lazy wiring loses nothing and
+* keeps the pool a single module instance (no separately-bundled plugin, so no
+* duplicated pool). The `close` handler registers after any user handlers, which
+* is the order we want: user code does its final work while clients are alive,
+* then we tear the sockets down.
+*/
+function ensureLifecycleWired() {
+	if (lifecycleWired) return;
+	lifecycleWired = true;
+	sweepTimer = setInterval(() => {
+		repairUnhealthyClients().catch((error) => {
+			console.error("c8y-nitro realtime: repair sweep failed", error);
+		});
+	}, REPAIR_SWEEP_INTERVAL_MS);
+	sweepTimer.unref?.();
+	useNitroHooks().hook("close", async () => {
+		if (sweepTimer) {
+			clearInterval(sweepTimer);
+			sweepTimer = void 0;
+		}
+		await Promise.all([...pool.values()].map((client) => client.close().catch(() => {})));
+		pool.clear();
+	});
+}
+/**
+* Get the pooled Notification 2.0 realtime client for a tenant, creating it on
+* first use and reusing it after. Accepts whatever identifies the tenant — a
+* tenant id, that tenant's credentials, a `@c8y/client`, or the current request
+* — and always connects with the tenant's **service** credentials.
 *
+* Register handlers directly on the returned client (see `c8y-realtime`):
 * @example
-* const scheduled = await scheduleTask('emails:send', {
-*   payload: { messageId: 'abc123' },
-*   schedule: '10 minutes',
-* })
-*
-* const cancelled = await cancelScheduledTask(scheduled.id)
+* const rt = await useTenantRealtimeClient(event)
+* rt.alarms.onCreate('*', alarm => log.info(alarm.severity, alarm.text))
+* rt.measurements.onCreate('device42', m => log.info(m.type, m.time))
+* @param input - A tenant id, `ICredentials`, a `Client`, or an `H3Event`/`ServerRequest`.
 */
-async function cancelScheduledTask(id) {
-	await schedulerReady;
-	const record = scheduledTasks.get(id);
-	if (!record) return false;
-	if (record.timeoutId !== void 0) {
-		const timeout = scheduledTaskTimers.get(record.timeoutId);
-		if (timeout) {
-			clearTimeout(timeout);
-			scheduledTaskTimers.delete(record.timeoutId);
-		}
+async function useTenantRealtimeClient(input) {
+	const { tenantId, creds } = await resolveTenant(input);
+	ensureLifecycleWired();
+	let client = pool.get(tenantId);
+	if (!client) {
+		client = createRealtimeClientForTenant(tenantId, creds);
+		pool.set(tenantId, client);
 	}
-	const cancelled = scheduledTasks.delete(id);
-	stopSchedulerIntervalIfIdle();
-	return cancelled;
+	return client;
 }
 //#endregion
-export { cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+export { c8yTasks, createError, createLogger, fetchAllPages, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, paginate, paginatePages, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useTenantRealtimeClient, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8y-nitro",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -39,8 +39,10 @@
   ],
   "dependencies": {
     "c12": "^4.0.0-beta.5",
+    "c8y-realtime": "^0.2.2",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
+    "croner": "^10.0.1",
     "evlog": "^2.21.0",
     "itty-time": "^2.0.2",
     "jszip": "^3.10.1",
@@ -74,6 +76,7 @@
   },
   "scripts": {
     "dev": "tsdown --watch",
+    "gen:roles": "node scripts/generate-roles.ts",
     "build": "tsdown",
     "build:update": "tsdown --update-snapshot",
     "lint": "eslint",