c8y-nitro 0.8.0 → 0.9.0

package/dist/{autoBootstrap-Drk7ltXK.mjs → autoBootstrap-qCcCgset.mjs}

@@ -1,4 +1,4 @@
-import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-DscUs-Kd.mjs";
+import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-DpCWhaJU.mjs";
 import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
 import { join } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";

package/dist/{bootstrap-C1Qly0J_.mjs → bootstrap-BcTCUiqG.mjs}

@@ -1,4 +1,4 @@
-import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-DscUs-Kd.mjs";
+import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-DpCWhaJU.mjs";
 import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
 import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
 import { defineCommand, runCommand } from "citty";
@@ -52,7 +52,7 @@ var bootstrap_default = defineCommand({
 		});
 		consola.success(`Bootstrap credentials written to ${envFileName}`);
 		if (manifest.roles && manifest.roles.length > 0) {
-			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-B-DNuScZ.mjs").then((r) => r.default), { rawArgs: [] });
+			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-CkUvL64s.mjs").then((r) => r.default), { rawArgs: [] });
 		}
 		consola.success("Bootstrap complete!");
 	}

package/dist/{c8y-api-DscUs-Kd.mjs → c8y-api-DpCWhaJU.mjs}

@@ -9,6 +9,13 @@ const GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE = "/_c8y_nitro/invalidate-tenant
 const DEFAULT_OPENAPI_ROUTE = "/_openapi.json";
 const ROLE_OPTION_MANAGEMENT_READ = "ROLE_OPTION_MANAGEMENT_READ";
 /**
+* Cumulocity microservice name constraints: lowercase letters, digits and
+* hyphens only, 1-23 characters. Enforced by the platform on upload, so we
+* fail early with a clear message instead of a cryptic API rejection.
+* @see https://github.com/schplitt/c8y-nitro/issues/75
+*/
+const MICROSERVICE_NAME_REGEX = /^[a-z0-9-]{1,23}$/;
+/**
 * Decide whether Nitro will expose an OpenAPI spec in the deployed build,
 * and if so return the configured route (with leading slash).
 * Returns null when OpenAPI is not enabled for production.
@@ -45,6 +52,7 @@ async function readPackageJsonFieldsForManifest(rootDir, logger) {
 	const authorEmail = typeof author === "string" ? void 0 : author?.email;
 	const authorUrl = typeof author === "string" ? void 0 : author?.url;
 	if (!name || !version || !authorName) throw new Error("package.json must contain name, version, and author name fields");
+	if (!MICROSERVICE_NAME_REGEX.test(name)) throw new Error(`Invalid microservice name "${name}". Cumulocity requires the name to match ${MICROSERVICE_NAME_REGEX.source} (lowercase letters, digits and hyphens only, 1-23 characters). Adjust the "name" field in package.json accordingly (scope like "@org/" is stripped and does not count).`);
 	const support = typeof pkg.bugs === "string" ? pkg.bugs : pkg.bugs?.url ?? pkg.bugs?.email;
 	const provider = {
 		name: authorName ?? name,

package/dist/cli/index.mjs

@@ -1,4 +1,4 @@
-import { n as name, r as version, t as description } from "../package-CNWz76PV.mjs";
+import { n as name, r as version, t as description } from "../package-gK1cGX1w.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/cli/index.ts
 runMain(defineCommand({
@@ -8,9 +8,9 @@ runMain(defineCommand({
 		description
 	},
 	subCommands: {
-		bootstrap: () => import("../bootstrap-C1Qly0J_.mjs").then((r) => r.default),
-		roles: () => import("../roles-B-DNuScZ.mjs").then((r) => r.default),
-		options: () => import("../options-CmLpZ3Qf.mjs").then((r) => r.default)
+		bootstrap: () => import("../bootstrap-BcTCUiqG.mjs").then((r) => r.default),
+		roles: () => import("../roles-CkUvL64s.mjs").then((r) => r.default),
+		options: () => import("../options-BBnR-y_W.mjs").then((r) => r.default)
 	}
 }));
 //#endregion

package/dist/{client-D0Tdq7H1.mjs → client-DCov9jV6.mjs}

@@ -8,6 +8,18 @@ import { useRuntimeConfig } from "nitro/runtime-config";
 import { useNitroHooks } from "nitro/app";
 //#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
@@ -145,10 +157,9 @@ function buildPublicRequestUrl(tenantDomain, contextPath, url) {
 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.\

package/dist/{index-vu4xaFkz.d.mts → index-Dil1PcDr.d.mts}

@@ -1,4 +1,5 @@
 import "./credentials-eKnJ7m9Y.mjs";
+import { ConsumerResilienceOptions, SubscriptionApi } from "c8y-realtime";
 import { C8YTenantOptionKeysCacheConfig } from "c8y-nitro/types";
 //#region src/types/apiClient.d.ts
 interface C8YAPIClientOptions {
@@ -15,6 +16,34 @@ interface C8YAPIClientOptions {
   contextPath?: string;
 }
 //#endregion
+//#region src/types/roles.generated.d.ts
+/**
+ * AUTO-GENERATED by scripts/generate-roles.ts — do not edit by hand.
+ *
+ * Source: https://cumulocity.com/api/core/dist/c8y-oas.json
+ * Spec version: Latest
+ * Known roles: 46
+ *
+ * Run `pnpm gen:roles` to regenerate.
+ */
+/**
+ * Cumulocity platform roles ("required roles") known from the core OpenAPI spec.
+ */
+type C8YKnownRole = 'ROLE_ALARM_ADMIN' | 'ROLE_ALARM_READ' | 'ROLE_APPLICATION_MANAGEMENT_ADMIN' | 'ROLE_APPLICATION_MANAGEMENT_READ' | 'ROLE_AUDIT_ADMIN' | 'ROLE_AUDIT_READ' | 'ROLE_BINARY_ADMIN' | 'ROLE_BINARY_CREATE' | 'ROLE_BINARY_READ' | 'ROLE_BULK_OPERATION_ADMIN' | 'ROLE_BULK_OPERATION_READ' | 'ROLE_DEVICE' | 'ROLE_DEVICE_BOOTSTRAP' | 'ROLE_DEVICE_CONTROL_ADMIN' | 'ROLE_DEVICE_CONTROL_READ' | 'ROLE_EVENT_ADMIN' | 'ROLE_EVENT_READ' | 'ROLE_IDENTITY_ADMIN' | 'ROLE_IDENTITY_READ' | 'ROLE_INVENTORY_ADMIN' | 'ROLE_INVENTORY_CREATE' | 'ROLE_INVENTORY_READ' | 'ROLE_MANAGED_OBJECT_ADMIN' | 'ROLE_MANAGED_OBJECT_CREATE' | 'ROLE_MANAGED_OBJECT_READ' | 'ROLE_MEASUREMENT_ADMIN' | 'ROLE_MEASUREMENT_READ' | 'ROLE_NOTIFICATION_2_ADMIN' | 'ROLE_OPTION_MANAGEMENT_ADMIN' | 'ROLE_OPTION_MANAGEMENT_READ' | 'ROLE_RETENTION_RULE_ADMIN' | 'ROLE_RETENTION_RULE_READ' | 'ROLE_SMS_READ' | 'ROLE_SYSTEM' | 'ROLE_TENANT_ADMIN' | 'ROLE_TENANT_ALARM_ADMIN' | 'ROLE_TENANT_MANAGEMENT_ADMIN' | 'ROLE_TENANT_MANAGEMENT_CREATE' | 'ROLE_TENANT_MANAGEMENT_READ' | 'ROLE_TENANT_MANAGEMENT_UPDATE' | 'ROLE_TENANT_STATISTICS_READ' | 'ROLE_USER_MANAGEMENT_ADMIN' | 'ROLE_USER_MANAGEMENT_CREATE' | 'ROLE_USER_MANAGEMENT_OWN_ADMIN' | 'ROLE_USER_MANAGEMENT_OWN_READ' | 'ROLE_USER_MANAGEMENT_READ';
+//#endregion
+//#region src/types/roles.d.ts
+/**
+ * Roles your microservice provides. Populated at runtime from the manifest's
+ * `roles` field (see the module's generated `c8y-nitro.d.ts`).
+ */
+interface C8YRoles$1 {}
+/**
+ * A Cumulocity role usable in the manifest. Autocompletes the platform roles
+ * known from the OpenAPI spec ({@link C8YKnownRole}) while still accepting any
+ * other string (custom roles, or roles not yet in the generated list).
+ */
+type C8YRole$1 = C8YKnownRole | (string & {});
+//#endregion
 //#region src/types/manifest.d.ts
 type C8YManifestOptions = Omit<C8YManifest, 'name' | 'version' | 'apiVersion' | 'key' | 'type' | 'provider' | 'openApiSpec'>;
 interface C8YManifest {
@@ -105,7 +134,7 @@ interface C8YManifest {
    * Needed to access Cumulocity APIs (inventory, alarms, etc.).
    * @example ["ROLE_ALARM_READ", "ROLE_INVENTORY_ADMIN"]
    */
-  requiredRoles?: string[];
+  requiredRoles?: C8YRole$1[];
   /**
    * New permissions provided by this microservice.
    * Users can be assigned these to access your endpoints.
@@ -407,8 +436,78 @@ interface C8yDockerOptions {
   extraInstructions?: string[];
 }
 //#endregion
-//#region src/types/roles.d.ts
-interface C8YRoles$1 {}
+//#region src/types/realtime.d.ts
+/**
+ * Options for the Notification 2.0 realtime clients (backed by `c8y-realtime`).
+ *
+ * Resolved once at build time into runtime config and spread **identically**
+ * into every per-tenant `RealtimeClient` the pool creates — so all subscribed
+ * tenants behave consistently in a multi-tenant deployment. Only the
+ * credentials differ per tenant.
+ */
+interface C8yRealtimeOptions {
+  /**
+   * Base name for this app's realtime topics/consumers (must be alphanumeric).
+   *
+   * Leave unset to derive it deterministically from the microservice
+   * `contextPath` (a short hash is appended so distinct services never collide
+   * on one platform topic). The derived name is **stable** across restarts and
+   * redeploys, so a reconnecting service resumes the same persistent
+   * subscription and its backlog. Set this only if you need to pin the name
+   * explicitly; it is a permanent identity — changing it later orphans the old
+   * subscriptions.
+   */
+  name?: string;
+  /**
+   * Delete **every** remote subscription this service created when Nitro shuts
+   * down. Keep `false` so persistent backlogs survive a redeploy.
+   * @default false
+   */
+  deleteSubscriptionsOnClose?: boolean;
+  /**
+   * Delete a `(type, device)` remote subscription once its last handler is
+   * removed. This is the only path that deletes a remote subscription — tenant
+   * churn never does.
+   * @default true
+   */
+  deleteSubscriptionOnEmpty?: boolean;
+  /**
+   * Acknowledge each notification after its handlers resolve.
+   * @default true
+   */
+  autoAck?: boolean;
+  /**
+   * Drop duplicate notifications redelivered on the same stream (e.g. on
+   * reconnect).
+   * @default true
+   */
+  dedupe?: boolean;
+  /**
+   * Open the connection automatically as handlers are registered. Set `false`
+   * to connect manually via the client's `start()`.
+   * @default true
+   */
+  autoStart?: boolean;
+  /**
+   * Subscription delivery mode applied to every tenant's client.
+   */
+  subscription?: {
+    /**
+     * APIs for the `onAny` firehose topic. Typed topics always use their own
+     * type. Defaults to `['*']`.
+     */
+    apis?: SubscriptionApi[];
+    /**
+     * Target a non-persistent topic (no server-side backlog; cheaper, but a
+     * disconnect loses messages). Defaults to `false`.
+     */
+    nonPersistent?: boolean;
+  };
+  /**
+   * Reconnect/backoff behaviour, applied identically to every tenant's client.
+   */
+  resilience?: ConsumerResilienceOptions;
+}
 //#endregion
 //#region src/types/tenantOptions.d.ts
 /**
@@ -466,6 +565,11 @@ interface C8yNitroModuleOptions {
    */
   docker?: C8yDockerOptions;
   cache?: C8yCacheOptions;
+  /**
+   * Options for the Notification 2.0 realtime clients (backed by `c8y-realtime`),
+   * shared by every subscribed tenant's pooled client.
+   */
+  realtime?: C8yRealtimeOptions;
   /**
    * Controls how the OpenAPI document served by Nitro (`experimental.openAPI`)
    * is transformed for Cumulocity microservices.
@@ -494,4 +598,4 @@ interface C8yNitroModuleOptions {
   skipBootstrap?: boolean;
 }
 //#endregion
-export { C8YTenantOptionKey$1 as a, C8yDockerOptions as c, C8YManifest as d, C8YManifestOptions as f, C8YSettingsCategory$1 as i, C8yCacheOptions as l, C8yNitroModuleOptions as n, C8YTenantOptionKeysCacheConfig$1 as o, C8YAPIClientOptions as p, C8yOpenAPIOptions as r, C8YRoles$1 as s, C8yDevOptions as t, C8YZipOptions as u };
+export { C8YTenantOptionKey$1 as a, C8yDockerOptions as c, C8YManifest as d, C8YManifestOptions as f, C8YAPIClientOptions as g, C8YKnownRole as h, C8YSettingsCategory$1 as i, C8yCacheOptions as l, C8YRoles$1 as m, C8yNitroModuleOptions as n, C8YTenantOptionKeysCacheConfig$1 as o, C8YRole$1 as p, C8yOpenAPIOptions as r, C8yRealtimeOptions as s, C8yDevOptions as t, C8YZipOptions as u };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { n as C8yNitroModuleOptions } from "./index-vu4xaFkz.mjs";
+import { n as C8yNitroModuleOptions } from "./index-Dil1PcDr.mjs";
 import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
 import { NitroModule } from "nitro/types";
 //#region src/index.d.ts

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { _ as GENERATED_READINESS_ROUTE, g as GENERATED_LIVENESS_ROUTE, h as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, m as createC8yManifestFromNitro, p as createC8yManifest } from "./c8y-api-DscUs-Kd.mjs";
-import { t as autoBootstrap } from "./autoBootstrap-Drk7ltXK.mjs";
-import { n as name } from "./package-CNWz76PV.mjs";
+import { _ as GENERATED_READINESS_ROUTE, g as GENERATED_LIVENESS_ROUTE, h as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, m as createC8yManifestFromNitro, p as createC8yManifest } from "./c8y-api-DpCWhaJU.mjs";
+import { t as autoBootstrap } from "./autoBootstrap-qCcCgset.mjs";
+import { n as name } from "./package-gK1cGX1w.mjs";
 import { basename, dirname, join, relative } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { x } from "tinyexec";
@@ -10,6 +10,8 @@ import JSZip from "jszip";
 import Spinnies from "spinnies";
 import { colors } from "consola/utils";
 import { mkdirSync, writeFileSync } from "fs";
+import { isValidRealtimeName, toRealtimeName } from "c8y-realtime";
+import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import evlog from "evlog/nitro/v3";
 //#region src/module/apiClient.ts
@@ -409,6 +411,24 @@ export const c8yTenantOptionKeys = [${settingKeys.map((key) => `'${key}'`).join(
 //#endregion
 //#region src/module/runtimeConfig.ts
 /**
+* Derive a stable, unique realtime client name from the microservice identity
+* (its `contextPath`, falling back to `name`).
+*
+* The identity is sanitized to Cumulocity's alphanumeric name rule via
+* `toRealtimeName`, then a short deterministic hash of the **raw** identity is
+* appended. Sanitizing is lossy (`my-svc` and `my_svc` both become `mysvc`), so
+* the hash restores the per-service uniqueness the `contextPath` guaranteed —
+* without it, two different services could share one platform topic and clobber
+* each other's subscriptions. Being deterministic, the name is identical across
+* restarts and redeploys, so a reconnecting service resumes the same persistent
+* subscription (and its backlog). This scheme is a permanent identity contract:
+* changing it orphans existing subscriptions.
+* @param identity - The microservice `contextPath` (or `name`)
+*/
+function deriveRealtimeName(identity) {
+	return `${toRealtimeName(identity)}${createHash("sha256").update(identity).digest("hex").slice(0, 8)}`;
+}
+/**
 * Sets up runtime configuration values from module options.
 * These can be overridden by environment variables.
 * @param nitro - The Nitro instance
@@ -421,6 +441,19 @@ async function setupRuntimeConfig(nitro, options) {
 	nitro.options.runtimeConfig.c8yTenantOptionsPerKeyTTL = options.cache?.tenantOptions ?? {};
 	const manifest = await createC8yManifest(nitro.options.rootDir, nitro.options, nitro.logger);
 	nitro.options.runtimeConfig.c8ySettingsCategory = options.manifest?.settingsCategory ?? manifest.contextPath ?? manifest.name;
+	const realtime = options.realtime ?? {};
+	const realtimeName = realtime.name ?? deriveRealtimeName(manifest.contextPath ?? manifest.name);
+	if (!isValidRealtimeName(realtimeName)) throw new Error(`c8y-nitro: invalid realtime name ${JSON.stringify(realtimeName)} — must be alphanumeric (^[a-zA-Z0-9]+\$). Set \`c8y.realtime.name\` to a valid value.`);
+	nitro.options.runtimeConfig.c8yRealtime = {
+		name: realtimeName,
+		autoAck: realtime.autoAck ?? true,
+		dedupe: realtime.dedupe ?? true,
+		autoStart: realtime.autoStart ?? true,
+		deleteSubscriptionOnEmpty: realtime.deleteSubscriptionOnEmpty ?? true,
+		deleteSubscriptionsOnClose: realtime.deleteSubscriptionsOnClose ?? false,
+		subscription: realtime.subscription,
+		resilience: realtime.resilience
+	};
 	const excludeInternalRoutes = options.openapi?.excludeInternalRoutes ?? true;
 	const probePaths = [options.manifest?.livenessProbe?.httpGet?.path, options.manifest?.readinessProbe?.httpGet?.path].filter((path) => Boolean(path));
 	nitro.options.runtimeConfig.c8yOpenApiExcludeRoutes = [...excludeInternalRoutes ? ["/_", ...probePaths] : [], ...options.openapi?.excludeRoutes ?? []];

package/dist/{options-CmLpZ3Qf.mjs → options-BBnR-y_W.mjs}

@@ -1,5 +1,5 @@
-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 { c as getTenantOptionsByCategory, f as upsertTenantOption, i as deleteTenantOption, n as createBasicAuthHeader, p as createC8yManifest, s as getCurrentApplicationSettings } from "./c8y-api-DpCWhaJU.mjs";
+import { n as readBootstrapCredentialsFromEnv, r as syncBootstrappedMicroservice } from "./autoBootstrap-qCcCgset.mjs";
 import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";

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

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "c8y-nitro";
-var version = "0.8.0";
+var version = "0.9.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-B-DNuScZ.mjs → roles-CkUvL64s.mjs}

@@ -1,4 +1,4 @@
-import { n as createBasicAuthHeader, p as createC8yManifest, t as assignUserRole, u as unassignUserRole } from "./c8y-api-DscUs-Kd.mjs";
+import { n as createBasicAuthHeader, p as createC8yManifest, t as assignUserRole, u as unassignUserRole } from "./c8y-api-DpCWhaJU.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-D0Tdq7H1.mjs";
+import { t as useDeployedTenantClient } from "../../client-DCov9jV6.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 { r as tryGetUserTenantDomainFast } from "../../client-D0Tdq7H1.mjs";
+import { r as tryGetUserTenantDomainFast } from "../../client-DCov9jV6.mjs";
 import { c8yManifest } from "c8y-nitro/runtime";
 import { useRuntimeConfig } from "nitro/runtime-config";
 import { getRequestURL } from "nitro/h3";

package/dist/runtime/handlers/rewriteRequestUrl.mjs

@@ -1,4 +1,4 @@
-import { n as buildPublicRequestUrl, r as tryGetUserTenantDomainFast } from "../../client-D0Tdq7H1.mjs";
+import { n as buildPublicRequestUrl, r as tryGetUserTenantDomainFast } from "../../client-DCov9jV6.mjs";
 import { c8yManifest } from "c8y-nitro/runtime";
 import { defineMiddleware } from "nitro";
 //#region src/module/runtime/handlers/rewriteRequestUrl.ts

package/dist/types.d.mts

@@ -1,3 +1,3 @@
-import { a as C8YTenantOptionKey, c as C8yDockerOptions, d as C8YManifest, f as C8YManifestOptions, i as C8YSettingsCategory, l as C8yCacheOptions, n as C8yNitroModuleOptions, o as C8YTenantOptionKeysCacheConfig, p as C8YAPIClientOptions, r as C8yOpenAPIOptions, s as C8YRoles, t as C8yDevOptions, u as C8YZipOptions } from "./index-vu4xaFkz.mjs";
+import { a as C8YTenantOptionKey, c as C8yDockerOptions, d as C8YManifest, f as C8YManifestOptions, g as C8YAPIClientOptions, h as C8YKnownRole, i as C8YSettingsCategory, l as C8yCacheOptions, m as C8YRoles, n as C8yNitroModuleOptions, o as C8YTenantOptionKeysCacheConfig, p as C8YRole, r as C8yOpenAPIOptions, s as C8yRealtimeOptions, t as C8yDevOptions, u as C8YZipOptions } from "./index-Dil1PcDr.mjs";
 import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
-export { C8YAPIClientOptions, type C8YManifest, type C8YManifestOptions, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, type C8YZipOptions, type C8yCacheOptions, C8yDevOptions, type C8yDockerOptions, C8yNitroModuleOptions, C8yOpenAPIOptions, type TenantCredentials };
+export { C8YAPIClientOptions, type C8YKnownRole, type C8YManifest, type C8YManifestOptions, C8YRole, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, type C8YZipOptions, type C8yCacheOptions, C8yDevOptions, type C8yDockerOptions, C8yNitroModuleOptions, C8yOpenAPIOptions, type C8yRealtimeOptions, type TenantCredentials };

package/dist/utils.d.mts

@@ -1,9 +1,10 @@
 import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
-import { Client, ICredentials, ICurrentUser } from "@c8y/client";
+import { RealtimeClient } from "c8y-realtime";
+import { Client, ICredentials, ICurrentUser, IResultList } from "@c8y/client";
 import { createError as createError$1, createLogger } from "evlog";
 import { EventHandler, H3Event, HTTPEvent } from "nitro/h3";
 import { ServerRequest, TaskContext, TaskPayload } from "nitro/types";
-import { C8YRoles, C8YSettingsCategory, C8YTenantOptionKey } from "c8y-nitro/types";
+import { C8YRole, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey } from "c8y-nitro/types";
 //#region src/utils/client.d.ts
 /**
  * Creates a Cumulocity client authenticated with the current user's credentials.\
@@ -51,8 +52,98 @@ declare function useSubscribedTenantClients(): Promise<Record<string, Client>>;
  */
 declare function useDeployedTenantClient(): Promise<Client>;
 //#endregion
+//#region src/utils/paging.d.ts
+/**
+ * The first page of a Cumulocity list result, in any of the shapes a caller
+ * naturally has on hand:
+ *
+ * - an already-awaited {@link IResultList} (`await client.inventory.list(...)`)
+ * - the pending `list()` promise itself (`client.inventory.list(...)`)
+ * - a thunk that produces it lazily (`() => client.inventory.list(...)`)
+ *
+ * Only the first page has to be supplied. Every subsequent page is fetched via
+ * the result's own `paging.next()`, which re-uses the exact client, auth, and
+ * filter that produced the first page — so there is no client to pass and no
+ * ambiguity between user, tenant, or microservice clients.
+ */
+type PageSource<T> = IResultList<T> | Promise<IResultList<T>> | (() => IResultList<T> | Promise<IResultList<T>>);
+/**
+ * Optional safety guards for walking large or unbounded Cumulocity collections.
+ */
+interface PagingOptions {
+  /**
+   * Stop after fetching this many pages. Guards against runaway iteration over
+   * unexpectedly large collections. Unlimited when omitted.
+   */
+  maxPages?: number;
+  /**
+   * Stop once this many items have been produced. The page that crosses the
+   * limit is truncated so exactly `maxItems` items are yielded. Unlimited when
+   * omitted.
+   */
+  maxItems?: number;
+}
+/**
+ * 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)
+ * }
+ */
+declare function paginatePages<T>(source: PageSource<T>, options?: PagingOptions): AsyncGenerator<T[]>;
+/**
+ * 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)
+ * }
+ */
+declare function paginate<T>(source: PageSource<T>, options?: PagingOptions): AsyncGenerator<T>;
+/**
+ * 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' }))
+ */
+declare function fetchAllPages<T>(source: PageSource<T>, options?: PagingOptions): Promise<T[]>;
+//#endregion
 //#region src/utils/middleware.d.ts
-type UserRole = keyof C8YRoles | (string & {});
+type UserRole = keyof C8YRoles | C8YRole;
 /**
  * Middleware to check if the current user has the required role.\
  * If the user doesn't have the required role, throws a 403 Forbidden error.\
@@ -543,7 +634,8 @@ type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: Ta
  * 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.
+ * - `{ in }`: one-shot, from now — either a number of seconds (`{ in: 30 }`) or a
+ *   human duration string (`{ in: '5 minutes' }`, `{ in: '1 hour' }`).
  * - `{ 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.
@@ -551,7 +643,7 @@ type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: Ta
 type JobSchedule = {
   cron: string;
 } | {
-  in: number;
+  in: number | string;
 } | {
   at: Date | string;
 };
@@ -762,4 +854,27 @@ interface TaskRegistry<TTasks extends TaskMap = {}> {
  */
 declare function c8yTasks(): TaskRegistry;
 //#endregion
-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 };
+//#region src/utils/realtime.d.ts
+/**
+ * Anything a caller might already have on hand that identifies a tenant, from
+ * which {@link useTenantRealtimeClient} resolves the tenant's service
+ * credentials: a tenant id, that tenant's credentials, a `@c8y/client` scoped to
+ * it, or the current request.
+ */
+type TenantRealtimeInput = string | ICredentials | Client | H3Event | ServerRequest;
+/**
+ * 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 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`.
+ */
+declare function useTenantRealtimeClient(input: TenantRealtimeInput): Promise<RealtimeClient>;
+//#endregion
+export { BaseJobInfo, ForeignTenantOptionCategory, ForeignTenantOptionKeyInput, JobConcurrency, JobInfo, JobInfoFor, JobSchedule, OnceJobInfo, PageSource, PagingOptions, RecurringJobInfo, ScheduleJobOptions, SetEditableOptions, TaskEvent, TaskHandler, TaskMap, TaskRegistry, TaskRegistryContext, TaskRegistryPayload, TaskShape, TenantOption, TenantOptionCategory, TenantOptionKeyInput, type TenantRealtimeInput, c8yTasks, createError, createLogger, fetchAllPages, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, paginate, paginatePages, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useTenantRealtimeClient, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/dist/utils.mjs

@@ -1,5 +1,6 @@
-import { Buffer } from "node:buffer";
+import { createRealtimeClient } from "c8y-realtime";
 import { createHash, randomBytes } from "node:crypto";
+import { Buffer } from "node:buffer";
 import process from "node:process";
 import { useLogger as useLogger$1 } from "evlog/nitro/v3";
 import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
@@ -10,8 +11,21 @@ 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";
 //#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
@@ -176,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.\
@@ -383,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.
@@ -886,6 +990,11 @@ const useTenantOptions = Object.assign(useTenantOptionsBase, {
 //#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);
 	}
@@ -1046,4 +1155,167 @@ function c8yTasks() {
 	return api;
 }
 //#endregion
-export { c8yTasks, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+//#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;
+}
+/**
+* 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;
+}
+/**
+* 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 createRealtimeClientForTenant(tenantId, creds) {
+	return createRealtimeClient({
+		...realtimeConfig(),
+		...toLibCredentials(tenantId, creds),
+		logger: console
+	});
+}
+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;
+}
+async function resolveTenant(input) {
+	if (typeof input === "string") return {
+		tenantId: input,
+		creds: await subscribedCredsFor(input)
+	};
+	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 {
+		tenantId,
+		creds: await subscribedCredsFor(tenantId)
+	};
+}
+/**
+* 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.
+*
+* 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 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;
+	}
+}
+/**
+* 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 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 useTenantRealtimeClient(input) {
+	const { tenantId, creds } = await resolveTenant(input);
+	ensureLifecycleWired();
+	let client = pool.get(tenantId);
+	if (!client) {
+		client = createRealtimeClientForTenant(tenantId, creds);
+		pool.set(tenantId, client);
+	}
+	return client;
+}
+//#endregion
+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.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -39,10 +39,12 @@
   ],
   "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",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.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",