c8y-nitro 0.10.3 → 0.11.0

package/dist/utils.d.mts

@@ -1,11 +1,10 @@
-import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
+import { t as TenantCredentials } from "./credentials-C_3m4LVX.mjs";
 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 { 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.\
  * Extracts credentials from the Authorization header of the current request.
@@ -16,7 +15,7 @@ import { C8YRole, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey } from "c8y-
  * const client = useUserClient(event)
  * const { data } = await client.inventory.list()
  */
-declare function useUserClient(requestOrEvent: ServerRequest | H3Event): Client;
+export declare function useUserClient(requestOrEvent: ServerRequest | H3Event): Client;
 /**
  * Creates a Cumulocity client for the tenant of the current user.\
  * Uses the tenant's service user credentials rather than the user's own credentials.
@@ -27,7 +26,7 @@ declare function useUserClient(requestOrEvent: ServerRequest | H3Event): Client;
  * const tenantClient = await useUserTenantClient(event)
  * const { data } = await tenantClient.inventory.list()
  */
-declare function useUserTenantClient(requestOrEvent: ServerRequest | H3Event): Promise<Client>;
+export declare function useUserTenantClient(requestOrEvent: ServerRequest | H3Event): Promise<Client>;
 /**
  * Creates Cumulocity clients for all tenants subscribed to this microservice.\
  * Each client is authenticated with that tenant's service user credentials.\
@@ -40,7 +39,7 @@ declare function useUserTenantClient(requestOrEvent: ServerRequest | H3Event): P
  *   console.log(`Tenant ${tenant} has ${data.length} inventory items`)
  * }
  */
-declare function useSubscribedTenantClients(): Promise<Record<string, Client>>;
+export declare function useSubscribedTenantClients(): Promise<Record<string, Client>>;
 /**
  * Creates a Cumulocity client for the tenant where this microservice is deployed.\
  * Uses the bootstrap tenant ID from runtime config to identify the deployed tenant.\
@@ -50,9 +49,7 @@ declare function useSubscribedTenantClients(): Promise<Record<string, Client>>;
  * const client = await useDeployedTenantClient()
  * const { data } = await client.application.list()
  */
-declare function useDeployedTenantClient(): Promise<Client>;
-//#endregion
-//#region src/utils/paging.d.ts
+export declare function useDeployedTenantClient(): Promise<Client>;
 /**
  * The first page of a Cumulocity list result, in any of the shapes a caller
  * naturally has on hand:
@@ -66,11 +63,11 @@ declare function useDeployedTenantClient(): Promise<Client>;
  * 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>>);
+export 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 {
+export interface PagingOptions {
   /**
    * Stop after fetching this many pages. Guards against runaway iteration over
    * unexpectedly large collections. Unlimited when omitted.
@@ -102,7 +99,7 @@ interface PagingOptions {
  *   await bulkInsert(page)
  * }
  */
-declare function paginatePages<T>(source: PageSource<T>, options?: PagingOptions): AsyncGenerator<T[]>;
+export 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
@@ -121,7 +118,7 @@ declare function paginatePages<T>(source: PageSource<T>, options?: PagingOptions
  *   await handleAlarm(alarm)
  * }
  */
-declare function paginate<T>(source: PageSource<T>, options?: PagingOptions): AsyncGenerator<T>;
+export 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.
@@ -140,9 +137,7 @@ declare function paginate<T>(source: PageSource<T>, options?: PagingOptions): As
  * 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
+export declare function fetchAllPages<T>(source: PageSource<T>, options?: PagingOptions): Promise<T[]>;
 type UserRole = keyof C8YRoles | C8YRole;
 /**
  * Middleware to check if the current user has the required role.\
@@ -160,7 +155,7 @@ type UserRole = keyof C8YRoles | C8YRole;
  * })
  *
  */
-declare function hasUserRequiredRole(role: UserRole): EventHandler;
+export declare function hasUserRequiredRole(role: UserRole): EventHandler;
 /**
  * Middleware to check if the current user has at least one of the required roles.\
  * If the user doesn't have any of the required roles, throws a 403 Forbidden error.\
@@ -176,7 +171,7 @@ declare function hasUserRequiredRole(role: UserRole): EventHandler;
  *  }
  * })
  */
-declare function hasUserRequiredRole(roles: UserRole[]): EventHandler;
+export declare function hasUserRequiredRole(roles: UserRole[]): EventHandler;
 /**
  * Middleware to check if the current user belongs to a specific allowed tenant.\
  * If the user's tenant doesn't match, throws a 403 Forbidden error.\
@@ -193,7 +188,7 @@ declare function hasUserRequiredRole(roles: UserRole[]): EventHandler;
  * })
  *
  */
-declare function isUserFromAllowedTenant(tenantId: string): EventHandler;
+export declare function isUserFromAllowedTenant(tenantId: string): EventHandler;
 /**
  * Middleware to check if the current user belongs to one of the allowed tenants.\
  * If the user's tenant doesn't match any of the allowed tenants, throws a 403 Forbidden error.\
@@ -209,7 +204,7 @@ declare function isUserFromAllowedTenant(tenantId: string): EventHandler;
  *  }
  * })
  */
-declare function isUserFromAllowedTenant(tenantIds: string[]): EventHandler;
+export declare function isUserFromAllowedTenant(tenantIds: string[]): EventHandler;
 /**
  * Middleware to check if the current user belongs to the deployed tenant.\
  * The deployed tenant is where this microservice is hosted (C8Y_BOOTSTRAP_TENANT).\
@@ -225,9 +220,7 @@ declare function isUserFromAllowedTenant(tenantIds: string[]): EventHandler;
  *  }
  * })
  */
-declare function isUserFromDeployedTenant(): EventHandler;
-//#endregion
-//#region src/utils/resources.d.ts
+export declare function isUserFromDeployedTenant(): EventHandler;
 /**
  * Fetches the current user from Cumulocity using credentials extracted from the current request's headers.
  * This is a non-cached version - fetches fresh data on every call.
@@ -238,7 +231,7 @@ declare function isUserFromDeployedTenant(): EventHandler;
  * const user = await useUser(event)
  * console.log(user.userName, user.email)
  */
-declare function useUser(requestOrEvent: ServerRequest | H3Event): Promise<ICurrentUser>;
+export declare function useUser(requestOrEvent: ServerRequest | H3Event): Promise<ICurrentUser>;
 /**
  * Fetches the roles of the current user from Cumulocity.
  * Internally calls `useUser()` and extracts role IDs from the user object.
@@ -250,10 +243,8 @@ declare function useUser(requestOrEvent: ServerRequest | H3Event): Promise<ICurr
  * const roles = await useUserRoles(event)
  * console.log(roles) // ['ROLE_INVENTORY_READ', 'ROLE_INVENTORY_ADMIN']
  */
-declare function useUserRoles(requestOrEvent: ServerRequest | H3Event): Promise<string[]>;
-//#endregion
-//#region src/utils/credentials.d.ts
-declare const useSubscribedTenantCredentials: (() => Promise<TenantCredentials>) & {
+export declare function useUserRoles(requestOrEvent: ServerRequest | H3Event): Promise<string[]>;
+export declare const useSubscribedTenantCredentials: (() => Promise<TenantCredentials>) & {
   invalidate: () => Promise<void>;
   refresh: () => Promise<TenantCredentials>;
 };
@@ -275,7 +266,7 @@ declare const useSubscribedTenantCredentials: (() => Promise<TenantCredentials>)
  * const freshCreds = await useDeployedTenantCredentials.refresh()
  * @note This function is not cached separately. It uses the cache of `useSubscribedTenantCredentials()`. Invalidating or refreshing one will refresh `useDeployedTenantCredentials()`s cache.
  */
-declare const useDeployedTenantCredentials: (() => Promise<ICredentials>) & {
+export declare const useDeployedTenantCredentials: (() => Promise<ICredentials>) & {
   invalidate: () => Promise<void>;
   refresh: () => Promise<ICredentials>;
 };
@@ -294,9 +285,7 @@ declare const useDeployedTenantCredentials: (() => Promise<ICredentials>) & {
  * // Credentials are automatically cached for the request duration
  * const sameCreds = await useUserTenantCredentials(event) // Uses cached value
  */
-declare function useUserTenantCredentials(requestOrEvent: ServerRequest | H3Event): Promise<ICredentials>;
-//#endregion
-//#region src/utils/tenantOptions.d.ts
+export declare function useUserTenantCredentials(requestOrEvent: ServerRequest | H3Event): Promise<ICredentials>;
 /**
  * A tenant option key for the microservice's own settings category.
  *
@@ -304,7 +293,7 @@ declare function useUserTenantCredentials(requestOrEvent: ServerRequest | H3Even
  * {@link C8YTenantOptionKey} union) while any other string is still accepted, so
  * runtime-computed keys such as `encrypted.password.${hash}` work too.
  */
-type TenantOptionKeyInput = C8YTenantOptionKey | (string & {});
+export type TenantOptionKeyInput = C8YTenantOptionKey | (string & {});
 /**
  * Guards a key used against a *foreign* settings category.
  *
@@ -312,11 +301,11 @@ type TenantOptionKeyInput = C8YTenantOptionKey | (string & {});
  * the owning microservice's category, so they can never be read from a different
  * category. Such keys collapse to `never`, turning the misuse into a compile error.
  */
-type ForeignTenantOptionKeyInput<K extends string> = K & (K extends `credentials.${string}` ? never : unknown);
+export type ForeignTenantOptionKeyInput<K extends string> = K & (K extends `credentials.${string}` ? never : unknown);
 /**
  * Options for {@link TenantOption.setEditable}.
  */
-interface SetEditableOptions {
+export interface SetEditableOptions {
   /**
    * The tenant whose option `editable` flag is updated.
    *
@@ -331,7 +320,7 @@ interface SetEditableOptions {
  * Obtained via {@link useTenantOption} (own category) or
  * `useTenantOptions(category).option(key)`.
  */
-interface TenantOption {
+export interface TenantOption {
   /**
    * Read the current value. Returns `undefined` when the option is not set
    * (Cumulocity responds `404`). The value is cached per the configured TTL.
@@ -370,7 +359,7 @@ interface TenantOption {
 /**
  * Handle for all options within the microservice's own settings category.
  */
-interface TenantOptionCategory {
+export interface TenantOptionCategory {
   /**
    * Get a handle for a single option in this category.
    */
@@ -402,7 +391,7 @@ interface TenantOptionCategory {
  *   (`useTenantOptions<'a' | 'b'>(client, 'other')`). It defaults to `string`,
  *   which accepts any key (still minus `credentials.*`).
  */
-interface ForeignTenantOptionCategory<K extends string = string> {
+export interface ForeignTenantOptionCategory<K extends string = string> {
   /**
    * Get a handle for a single non-`credentials.*` option in this category.
    * Completes to `K` when a key set was provided.
@@ -457,7 +446,7 @@ interface ForeignTenantOptionCategory<K extends string = string> {
  * await useTenantOption(client, 'featureMode').set('advanced')
  * const token = await useTenantOption(client, `encrypted.password.${hash}`).getOrInsert('')
  */
-declare function useTenantOption(client: Client, key: TenantOptionKeyInput): TenantOption;
+export declare function useTenantOption(client: Client, key: TenantOptionKeyInput): TenantOption;
 /**
  * @internal
  */
@@ -513,9 +502,7 @@ interface UseTenantOptions {
  * // Invalidate everything, across all tenants and categories:
  * await useTenantOptions.invalidateAll()
  */
-declare const useTenantOptions: UseTenantOptions;
-//#endregion
-//#region src/utils/logging.d.ts
+export declare const useTenantOptions: UseTenantOptions;
 /**
  * Returns the request-scoped wide-event logger for the current request.
  *
@@ -539,7 +526,7 @@ declare const useTenantOptions: UseTenantOptions;
  * import { useRequest } from 'nitro/context'
  * const log = useLogger(useRequest())
  */
-declare function useLogger<T extends object = Record<string, unknown>>(eventOrRequest: HTTPEvent | ServerRequest, service?: string): import("evlog").AuditableLogger<T>;
+export declare function useLogger<T extends object = Record<string, unknown>>(eventOrRequest: HTTPEvent | ServerRequest, service?: string): import("evlog").AuditableLogger<T>;
 /**
  * Create a structured error for a Cumulocity microservice. Always prefer this
  * over Nitro/h3's built-in `createError`: the returned error is captured in the
@@ -591,9 +578,7 @@ declare function useLogger<T extends object = Record<string, unknown>>(eventOrRe
  *
  * @see https://www.evlog.dev
  */
-declare const createError: typeof createError$1;
-//#endregion
-//#region src/utils/tasks.d.ts
+export declare const createError: typeof createError$1;
 /**
  * Concurrency policy for a single job.
  * - `'single'`: at most one run of the job is in flight at a time. A tick that
@@ -602,13 +587,13 @@ declare const createError: typeof createError$1;
  * - `'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 JobConcurrency = 'single' | 'parallel';
-type TaskRegistryPayload = TaskPayload;
-type TaskRegistryContext = TaskContext;
+export type JobConcurrency = 'single' | 'parallel';
+export type TaskRegistryPayload = TaskPayload;
+export type TaskRegistryContext = TaskContext;
 /**
  * The event passed to a task handler on every execution.
  */
-interface TaskEvent<TPayload = TaskRegistryPayload> {
+export interface TaskEvent<TPayload = TaskRegistryPayload> {
   /**
    * Name of the task (function) being executed.
    */
@@ -629,7 +614,7 @@ interface TaskEvent<TPayload = TaskRegistryPayload> {
 /**
  * A task handler function registered via {@link TaskRegistry.createTask}.
  */
-type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: TaskEvent<TPayload>) => TResult | Promise<TResult>;
+export 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
@@ -640,7 +625,7 @@ type TaskHandler<TPayload = TaskRegistryPayload, TResult = unknown> = (event: Ta
  *   taken literally (never re-projected to another timezone). Times in the past
  *   fire almost immediately.
  */
-type JobSchedule = {
+export type JobSchedule = {
   cron: string;
 } | {
   in: number | string;
@@ -650,7 +635,7 @@ type JobSchedule = {
 /**
  * Options for scheduling a job via {@link TaskRegistry.scheduleJob}.
  */
-interface ScheduleJobOptions<TTask extends string = string, TPayload = TaskRegistryPayload, TSchedule extends JobSchedule = JobSchedule> {
+export 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()`.
    */
@@ -700,7 +685,7 @@ interface ScheduleJobOptions<TTask extends string = string, TPayload = TaskRegis
 /**
  * Fields common to every job, regardless of kind.
  */
-interface BaseJobInfo {
+export interface BaseJobInfo {
   /**
    * The job's unique name.
    */
@@ -725,7 +710,7 @@ interface BaseJobInfo {
 /**
  * Information about a one-shot job (scheduled with `{ in }` or `{ at }`).
  */
-interface OnceJobInfo extends BaseJobInfo {
+export interface OnceJobInfo extends BaseJobInfo {
   kind: 'once';
   /**
    * Always `null` for one-shot jobs.
@@ -735,7 +720,7 @@ interface OnceJobInfo extends BaseJobInfo {
 /**
  * Information about a recurring job (scheduled with `{ cron }`).
  */
-interface RecurringJobInfo extends BaseJobInfo {
+export interface RecurringJobInfo extends BaseJobInfo {
   kind: 'recurring';
   /**
    * The cron expression the job runs on.
@@ -754,24 +739,24 @@ interface RecurringJobInfo extends BaseJobInfo {
  * Public information about a registered job. A discriminated union on `kind` —
  * returned by `scheduleJob()`, `getJob()` and `listJobs()`.
  */
-type JobInfo = OnceJobInfo | RecurringJobInfo;
+export type JobInfo = OnceJobInfo | RecurringJobInfo;
 /**
  * Maps a {@link JobSchedule} to the {@link JobInfo} variant it produces.
  */
-type JobInfoFor<TSchedule extends JobSchedule> = TSchedule extends {
+export 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> {
+export 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>;
+export type TaskMap = Record<string, TaskShape>;
 /**
  * A type-charged registry of tasks (functions) and the jobs that schedule them.
  *
@@ -779,7 +764,7 @@ type TaskMap = Record<string, TaskShape>;
  * `run()`, `scheduleJob()` and `triggerJob()` autocomplete known task names and
  * reject typos at compile time.
  */
-interface TaskRegistry<TTasks extends TaskMap = {}> {
+export 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).
@@ -852,9 +837,7 @@ interface TaskRegistry<TTasks extends TaskMap = {}> {
  * that schedules them executes, so register them from a Nitro plugin (or another
  * startup path) if they must run from boot.
  */
-declare function c8yTasks(): TaskRegistry;
-//#endregion
-//#region src/utils/realtime.d.ts
+export declare function c8yTasks(): TaskRegistry;
 /**
  * Anything a caller might already have on hand that identifies a tenant, from
  * which {@link useTenantRealtimeClient} resolves the tenant's service
@@ -875,6 +858,5 @@ type TenantRealtimeInput = string | ICredentials | Client | H3Event | ServerRequ
  * 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 };
+export declare function useTenantRealtimeClient(input: TenantRealtimeInput): Promise<RealtimeClient>;
+export { type TenantRealtimeInput, createLogger };

package/dist/utils.mjs

@@ -1,7 +1,8 @@
+import { n as useTestingHooks } from "./testing-D5VjeD-F.mjs";
+import process from "node:process";
 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";
 import { defineCachedFunction } from "nitro/cache";
@@ -13,7 +14,7 @@ import { c8yManifest } from "c8y-nitro/runtime";
 import { Cron } from "croner";
 import { ms } from "itty-time";
 import { WebSocket } from "ws";
-//#region src/utils/internal/common.ts
+// 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
@@ -48,8 +49,7 @@ function convertRequestHeadersToC8yFormat(request) {
 	if (cookie) headers.cookie = cookie;
 	return headers;
 }
-//#endregion
-//#region src/utils/internal/tenant.ts
+// src/utils/internal/tenant.ts
 const USER_TENANT_CACHE_SALT = randomBytes(32).toString("hex");
 function getCookieValue(cookieHeader, name) {
 	try {
@@ -106,8 +106,7 @@ defineCachedFunction(async (requestOrEvent, _tenantId) => {
 	swr: false,
 	getKey: (_requestOrEvent, tenantId) => tenantId
 });
-//#endregion
-//#region src/utils/logging.ts
+// src/utils/logging.ts
 /**
 * Returns the request-scoped wide-event logger for the current request.
 *
@@ -187,8 +186,7 @@ function useLogger(eventOrRequest, service) {
 * @see https://www.evlog.dev
 */
 const createError = createError$1;
-//#endregion
-//#region src/utils/credentials.ts
+// src/utils/credentials.ts
 let prevCredentials = null;
 function shouldEmitTenantCredentialsUpdated(prev, next) {
 	if (!prev) return true;
@@ -310,8 +308,7 @@ async function useUserTenantCredentials(requestOrEvent) {
 	request.context["c8y_user_tenant_credentials"] = userTenantCreds;
 	return userTenantCreds;
 }
-//#endregion
-//#region src/utils/client.ts
+// src/utils/client.ts
 /**
 * Creates a Cumulocity client authenticated with the current user's credentials.\
 * Extracts credentials from the Authorization header of the current request.
@@ -329,7 +326,7 @@ function useUserClient(requestOrEvent) {
 	const auth = new MicroserviceClientRequestAuth(headers);
 	const client = new Client(auth, process.env.C8Y_BASEURL);
 	const forwardedHost = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim();
-	client.core.defaultHeaders["X-Forwarded-Host"] = forwardedHost || process.env.C8Y_BASEURL;
+	if (forwardedHost) client.core.defaultHeaders["X-Forwarded-Host"] = forwardedHost;
 	request.context ??= {};
 	request.context["c8y_user_client"] = client;
 	return client;
@@ -401,8 +398,7 @@ async function useDeployedTenantClient() {
 	client.core.tenant = tenant;
 	return client;
 }
-//#endregion
-//#region src/utils/paging.ts
+// src/utils/paging.ts
 async function resolvePageSource(source) {
 	return await (typeof source === "function" ? source() : source);
 }
@@ -492,8 +488,7 @@ async function fetchAllPages(source, options) {
 	for await (const page of paginatePages(source, options)) all.push(...page);
 	return all;
 }
-//#endregion
-//#region src/utils/resources.ts
+// src/utils/resources.ts
 /**
 * Fetches the current user from Cumulocity using credentials extracted from the current request's headers.
 * This is a non-cached version - fetches fresh data on every call.
@@ -535,8 +530,7 @@ async function useUserRoles(requestOrEvent) {
 	request.context["c8y_user_roles"] = userRoles;
 	return userRoles;
 }
-//#endregion
-//#region src/utils/middleware.ts
+// src/utils/middleware.ts
 const probePaths = [c8yManifest.livenessProbe?.httpGet?.path, c8yManifest.readinessProbe?.httpGet?.path].filter((path) => Boolean(path));
 function isProbeRequest(pathname) {
 	return probePaths.some((probePath) => pathname.startsWith(probePath));
@@ -590,8 +584,7 @@ function isUserFromDeployedTenant() {
 		});
 	});
 }
-//#endregion
-//#region src/utils/internal/tenantOptionFetchers.ts
+// src/utils/internal/tenantOptionFetchers.ts
 /**
 * Internal storage for cached option fetchers, keyed by
 * `${tenant}::${category}::${key}`.
@@ -610,8 +603,7 @@ const tenantOptionFetchers = {};
 function fetcherStoreKey(tenant, category, key) {
 	return `${tenant}::${category}::${key}`;
 }
-//#endregion
-//#region src/utils/tenantOptions.ts
+// src/utils/tenantOptions.ts
 /**
 * The microservice's own settings category, resolved once from runtime config
 * (`manifest.settingsCategory` → `contextPath` → `name`). This is independent of
@@ -992,8 +984,7 @@ const useTenantOptions = Object.assign(useTenantOptionsBase, {
 	invalidateAll: () => invalidateFetchers(() => true),
 	refreshAll: () => refreshFetchers(() => true)
 });
-//#endregion
-//#region src/utils/tasks.ts
+// src/utils/tasks.ts
 function resolveOnceDate(schedule) {
 	if ("in" in schedule) {
 		if (typeof schedule.in === "string") {
@@ -1160,8 +1151,7 @@ function c8yTasks() {
 	};
 	return api;
 }
-//#endregion
-//#region src/utils/realtime.ts
+// src/utils/realtime.ts
 /**
 * `ws` as the factory type c8y-realtime asks for.
 *
@@ -1212,7 +1202,7 @@ function createRealtimeClientForTenant(tenantId, creds) {
 	return createRealtimeClient({
 		...realtimeConfig(),
 		...toLibCredentials(tenantId, creds),
-		webSocketImpl: wsWebSocketImpl,
+		webSocketImpl: useTestingHooks()?.WebSocket ?? wsWebSocketImpl,
 		logger: console
 	});
 }
@@ -1339,5 +1329,4 @@ async function useTenantRealtimeClient(input) {
 	}
 	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.10.3",
+  "version": "0.11.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -25,6 +25,9 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./cli": "./dist/cli/index.mjs",
+    "./testing": "./dist/testing.mjs",
+    "./testing/setup": "./dist/testing/setup.mjs",
+    "./testing/vite": "./dist/testing/vite.mjs",
     "./types": "./dist/types.mjs",
     "./utils": "./dist/utils.mjs",
     "./package.json": "./package.json"
@@ -38,40 +41,52 @@
     "dist"
   ],
   "dependencies": {
-    "c12": "^4.0.0-rc.1",
+    "c12": "^4.0.0-rc.4",
     "c8y-realtime": "^0.2.2",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
-    "croner": "^10.0.1",
-    "evlog": "^2.28.1",
+    "croner": "^11.0.0",
+    "evlog": "^2.34.0",
     "itty-time": "^2.0.2",
-    "jszip": "^3.10.1",
+    "jszip": "^3.10.2",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.2",
+    "pkg-types": "^2.4.0",
     "spinnies": "^0.5.1",
     "tinyexec": "^1.3.1",
-    "ws": "^8.21.3"
+    "ws": "^8.22.1"
   },
   "devDependencies": {
-    "@c8y/client": "^1023.97.0",
-    "@schplitt/eslint-config": "^1.5.2",
-    "@types/node": "^24.12.3",
+    "@c8y/client": "^1023.97.8",
+    "@schplitt/eslint-config": "^1.5.4",
+    "@types/node": "^24.19.2",
     "@types/spinnies": "^0.5.3",
-    "@types/ws": "^8.18.1",
+    "@types/ws": "^8.18.2",
     "bumpp": "^12.3.0",
     "changelogithub": "^15.0.5",
-    "eslint": "^10.9.1",
-    "memfs": "^4.69.1",
-    "tsdown": "^0.22.14",
-    "tsnapi": "^1.4.2",
+    "eslint": "^10.14.0",
+    "memfs": "^4.80.0",
+    "rolldown": "^1.2.16",
+    "tsdown": "^0.23.4",
+    "tsnapi": "^1.6.0",
     "typescript": "^6.0.3",
-    "vitepress": "2.0.0-alpha.17",
-    "vitepress-plugin-llms": "1.13.3",
-    "vitest": "^4.1.11"
+    "vite": "^8.3.5",
+    "vitepress": "2.0.0-alpha.21",
+    "vitepress-plugin-llms": "1.14.0",
+    "vitest": "^5.0.5"
   },
   "peerDependencies": {
     "@c8y/client": ">=1021",
-    "nitro": "3.0.260903-beta"
+    "nitro": "3.0.261102-rc",
+    "vite": "^7.0.0 || ^8.0.0",
+    "vitest": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=24.0.0"
@@ -79,6 +94,7 @@
   "scripts": {
     "dev": "tsdown --watch",
     "gen:roles": "node scripts/generate-roles.ts",
+    "gen:testing-capabilities": "node scripts/generate-testing-capabilities.ts",
     "build": "tsdown",
     "build:update": "tsdown --update-snapshot",
     "lint": "eslint",
@@ -88,6 +104,7 @@
     "release": "bumpp",
     "test": "vitest",
     "test:run": "vitest run",
+    "test:contract": "vitest run --config vitest.contract.config.ts",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"