c8y-nitro 0.7.0 → 0.7.1

package/dist/cli/index.mjs

@@ -1,4 +1,4 @@
-import { n as name, r as version, t as description } from "../package-BhFLRPOb.mjs";
+import { n as name, r as version, t as description } from "../package-D5xRshsx.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/cli/index.ts
 runMain(defineCommand({

package/dist/client-DxmbyZju.mjs

@@ -0,0 +1,236 @@
+import { t as createError } from "./logging-BUYT8Z2V.mjs";
+import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
+import { defineCachedFunction } from "nitro/cache";
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import process from "node:process";
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { useNitroHooks } from "nitro/app";
+//#region src/utils/internal/common.ts
+/**
+* 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
+* - `cookie`: Used to extract XSRF-TOKEN and authorization token from cookies
+*
+* The MicroserviceClientRequestAuth class will automatically:
+* - Extract XSRF-TOKEN from cookies for CSRF protection
+* - Extract authorization token from cookies (prioritized over header auth)
+* - Fall back to Authorization header if no cookie-based auth is present
+*
+* @param request - The HTTP request containing headers
+* @returns Headers object compatible with \@c8y/client's MicroserviceClientRequestAuth
+*/
+function convertRequestHeadersToC8yFormat(request) {
+	const headers = {};
+	const authorization = request.headers.get("authorization");
+	if (authorization) headers.authorization = authorization;
+	const cookie = request.headers.get("cookie");
+	if (cookie) headers.cookie = cookie;
+	return headers;
+}
+//#endregion
+//#region src/utils/internal/tenant.ts
+const USER_TENANT_CACHE_SALT = randomBytes(32).toString("hex");
+function getCookieValue(cookieHeader, name) {
+	try {
+		const value = cookieHeader?.match(`(^|;)\\s*${name}\\s*=\\s*([^;]+)`);
+		return value ? value.pop() : void 0;
+	} catch {
+		return;
+	}
+}
+function getCurrentUserTenantCacheKeyMaterial(requestOrEvent) {
+	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
+	const cookieAuth = getCookieValue(request.headers.get("cookie"), "authorization");
+	if (cookieAuth) return `cookie:${cookieAuth}`;
+	const authorization = request.headers.get("authorization");
+	if (authorization) return `header:${authorization}`;
+}
+function createCurrentUserTenantCacheKey(requestOrEvent) {
+	const material = getCurrentUserTenantCacheKeyMaterial(requestOrEvent);
+	if (!material) throw new Error("Cannot create current user tenant cache key without auth material");
+	return createHash("sha256").update(USER_TENANT_CACHE_SALT).update(":").update(material).digest("hex");
+}
+function tryGetTenantFromBasicAuth(requestOrEvent) {
+	const authorization = ("req" in requestOrEvent ? requestOrEvent.req : requestOrEvent).headers.get("authorization");
+	if (!authorization?.startsWith("Basic ")) return;
+	try {
+		const decoded = Buffer.from(authorization.slice(6), "base64").toString("utf8");
+		const separatorIndex = decoded.indexOf(":");
+		const userPart = separatorIndex === -1 ? decoded : decoded.slice(0, separatorIndex);
+		const slashIndex = userPart.indexOf("/");
+		if (slashIndex <= 0) return;
+		return userPart.slice(0, slashIndex);
+	} catch {
+		return;
+	}
+}
+const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
+	const basicTenant = tryGetTenantFromBasicAuth(requestOrEvent);
+	if (basicTenant) return basicTenant;
+	return (await useUserClient(requestOrEvent).tenant.current()).data.name;
+}, {
+	maxAge: 60,
+	name: "_c8y_nitro_get_current_user_tenant_id",
+	group: "c8y_nitro",
+	swr: false,
+	getKey: (requestOrEvent) => createCurrentUserTenantCacheKey(requestOrEvent),
+	shouldBypassCache: (requestOrEvent) => !getCurrentUserTenantCacheKeyMaterial(requestOrEvent)
+});
+const cachedTenantDomain = defineCachedFunction(async (requestOrEvent, _tenantId) => {
+	return (await useUserClient(requestOrEvent).tenant.current()).data.domainName;
+}, {
+	maxAge: 86400,
+	name: "_c8y_nitro_get_user_tenant_domain",
+	group: "c8y_nitro",
+	swr: false,
+	getKey: (_requestOrEvent, tenantId) => tenantId
+});
+/**
+* Resolves the public domain of the current user's tenant (e.g. `tenant.cumulocity.com`)
+* via `/tenant/currentTenant` with the user's credentials from the current request.
+* @param requestOrEvent - The H3Event or ServerRequest from the current request
+*/
+async function getUserTenantDomain(requestOrEvent) {
+	const tenantId = await getCurrentUserTenantId(requestOrEvent);
+	return cachedTenantDomain(requestOrEvent, tenantId);
+}
+//#endregion
+//#region src/utils/credentials.ts
+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;
+}
+/**
+* Fetches credentials for all tenants subscribed to this microservice.\
+* Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
+* Results are cached based on the configured TTL (default: 10 minutes).\
+* @returns Object mapping tenant IDs to their respective credentials
+* @config Cache TTL can be configured via:
+* - `c8y.cache.credentialsTTL` in the Nitro config (value in seconds)
+* - `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable
+* @example
+* // Get all subscribed tenant credentials:
+* const credentials = await useSubscribedTenantCredentials()
+* console.log(Object.keys(credentials)) // ['t12345', 't67890']
+*
+* // Access specific tenant:
+* const tenant1Creds = credentials['t12345']
+*
+* // Invalidate cache:
+* await useSubscribedTenantCredentials.invalidate()
+*
+* // Force refresh:
+* const freshCreds = await useSubscribedTenantCredentials.refresh()
+*/
+const cachedSubscribedTenantCredentials = defineCachedFunction(async () => {
+	const newCredentials = (await Client.getMicroserviceSubscriptions({
+		tenant: process.env.C8Y_BOOTSTRAP_TENANT,
+		user: process.env.C8Y_BOOTSTRAP_USER,
+		password: process.env.C8Y_BOOTSTRAP_PASSWORD
+	}, process.env.C8Y_BASEURL)).reduce((acc, cred) => {
+		if (cred.tenant) acc[cred.tenant] = cred;
+		return acc;
+	}, {});
+	if (shouldEmitTenantCredentialsUpdated(prevCredentials, newCredentials)) useNitroHooks().callHook("c8y:tenantCredentialsUpdated", prevCredentials, newCredentials);
+	prevCredentials = newCredentials;
+	return newCredentials;
+}, {
+	maxAge: useRuntimeConfig().c8yCredentialsCacheTTL ?? 600,
+	name: "_c8y_nitro_get_subscribed_tenant_credentials",
+	group: "c8y_nitro",
+	swr: false
+});
+const useSubscribedTenantCredentials = Object.assign(async () => {
+	const credentials = await cachedSubscribedTenantCredentials();
+	prevCredentials = credentials;
+	return credentials;
+}, {
+	invalidate: cachedSubscribedTenantCredentials.invalidate,
+	refresh: async () => {
+		await cachedSubscribedTenantCredentials.invalidate();
+		const credentials = await cachedSubscribedTenantCredentials();
+		prevCredentials = credentials;
+		return credentials;
+	}
+});
+/**
+* Fetches credentials for the tenant where this microservice is deployed.\
+* Uses the C8Y_BOOTSTRAP_TENANT environment variable to identify the deployed tenant.\
+* Returns credentials from the subscribed tenant credentials cache (cached based on configured TTL, default: 10 minutes).
+* @returns Credentials for the deployed tenant
+* @throws {EvlogError} If no credentials found for the deployed tenant
+* @example
+* // Get deployed tenant credentials:
+* const creds = await useDeployedTenantCredentials()
+* console.log(creds.tenant, creds.user)
+*
+* // Invalidate cache:
+* await useDeployedTenantCredentials.invalidate()
+*
+* // Force refresh:
+* 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.
+*/
+const useDeployedTenantCredentials = Object.assign(async () => {
+	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
+	const allCredsPromise = await useSubscribedTenantCredentials();
+	if (!allCredsPromise[tenant]) throw createError({
+		message: `No credentials found for tenant deployed tenant '${tenant}'`,
+		status: 500
+	});
+	return allCredsPromise[tenant];
+}, {
+	invalidate: useSubscribedTenantCredentials.invalidate,
+	refresh: async () => {
+		await useSubscribedTenantCredentials.refresh();
+		return await useDeployedTenantCredentials();
+	}
+});
+//#endregion
+//#region 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.
+* @param requestOrEvent - The H3Event or ServerRequest from the current request
+* @returns A configured Cumulocity Client instance
+* @example
+* // In a request handler:
+* const client = useUserClient(event)
+* const { data } = await client.inventory.list()
+*/
+function useUserClient(requestOrEvent) {
+	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
+	if (request.context?.["c8y_user_client"]) return request.context["c8y_user_client"];
+	const client = new Client(new MicroserviceClientRequestAuth(convertRequestHeadersToC8yFormat(request)), process.env.C8Y_BASEURL);
+	request.context ??= {};
+	request.context["c8y_user_client"] = client;
+	return 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.\
+* @returns A configured Cumulocity Client instance for the deployed tenant
+* @example
+* // Get client for the tenant hosting this microservice:
+* const client = await useDeployedTenantClient()
+* const { data } = await client.application.list()
+*/
+async function useDeployedTenantClient() {
+	const creds = await useSubscribedTenantCredentials();
+	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
+	if (!creds[tenant]) throw createError({
+		message: `No subscribed tenant credentials found for tenant '${tenant}'`,
+		status: 500
+	});
+	const client = new Client(new BasicAuth(creds[tenant]), process.env.C8Y_BASEURL);
+	client.core.tenant = tenant;
+	return client;
+}
+//#endregion
+export { getUserTenantDomain as n, useDeployedTenantClient as t };

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

@@ -383,6 +383,30 @@ interface C8yCacheOptions {
   tenantOptions?: C8YTenantOptionKeysCacheConfig;
 }
 //#endregion
+//#region src/types/docker.d.ts
+interface C8yDockerOptions {
+  /**
+   * Base image for the generated Dockerfile.
+   *
+   * Use this when the default slim image is missing something the service
+   * needs at runtime (e.g. CA certificates, native runtime libraries).
+   * @default 'node:24-slim'
+   */
+  baseImage?: string;
+  /**
+   * Raw Dockerfile instructions inserted after `WORKDIR` and before the build
+   * output is copied, one instruction per entry.
+   *
+   * Placing them before the `COPY` keeps their layers cached across rebuilds.
+   * `ENV`, `EXPOSE 80` and the `CMD` entrypoint stay under module control and
+   * cannot be overridden — they are the Cumulocity microservice contract.
+   *
+   * @example ['RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*']
+   * @default []
+   */
+  extraInstructions?: string[];
+}
+//#endregion
 //#region src/types/roles.d.ts
 interface C8YRoles$1 {}
 //#endregion
@@ -415,12 +439,38 @@ interface C8yDevOptions {
    */
   injectUser?: boolean;
 }
+interface C8yOpenAPIOptions {
+  /**
+   * Strip internal routes from the served OpenAPI document.
+   * Removes every route starting with `/_` (generated probes, `/_c8y_nitro/**`
+   * and the OpenAPI/Scalar/Swagger routes themselves) as well as user-defined
+   * probe `httpGet` paths.
+   * @default true
+   */
+  excludeInternalRoutes?: boolean;
+  /**
+   * Additional route prefixes to strip from the served OpenAPI document.
+   * Entries are matched as path prefixes (e.g. `/internal` also removes `/internal/status`).
+   * @default []
+   */
+  excludeRoutes?: string[];
+}
 interface C8yNitroModuleOptions {
   dev?: C8yDevOptions;
   manifest?: C8YManifestOptions;
   apiClient?: C8YAPIClientOptions;
   zip?: C8YZipOptions;
+  /**
+   * Controls the Dockerfile generated for the microservice image
+   * (base image, extra instructions).
+   */
+  docker?: C8yDockerOptions;
   cache?: C8yCacheOptions;
+  /**
+   * Controls how the OpenAPI document served by Nitro (`experimental.openAPI`)
+   * is transformed for Cumulocity microservices.
+   */
+  openapi?: C8yOpenAPIOptions;
   /**
    * Adds a debug route for invalidating already-created tenant option caches.
    * Exposes `GET /_c8y_nitro/invalidate-tenant-options`.
@@ -444,4 +494,4 @@ interface C8yNitroModuleOptions {
   skipBootstrap?: boolean;
 }
 //#endregion
-export { C8YTenantOptionKeysCacheConfig$1 as a, C8YZipOptions as c, C8YAPIClientOptions as d, C8YTenantOptionKey$1 as i, C8YManifest as l, C8yNitroModuleOptions as n, C8YRoles$1 as o, C8YSettingsCategory$1 as r, C8yCacheOptions as s, C8yDevOptions as t, C8YManifestOptions as u };
+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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { n as C8yNitroModuleOptions } from "./index-ByDSMEvU.mjs";
+import { n as C8yNitroModuleOptions } from "./index-vu4xaFkz.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, a as findMicroserviceByName, d as updateMicroservice, g as GENERATED_LIVENESS_ROUTE, h as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, l as subscribeToApplication, m as createC8yManifestFromNitro, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BFjK6AYb.mjs";
 import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
-import { n as name } from "./package-BhFLRPOb.mjs";
+import { n as name } from "./package-D5xRshsx.mjs";
 import { basename, dirname, join, relative } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { x } from "tinyexec";
@@ -220,14 +220,15 @@ async function writeAPIClient(nitro, options) {
 /**
 * Generate the Dockerfile content for a Nitro build
 * @param outputDirName - Name of the output directory (e.g., '.output')
+* @param options - Dockerfile customization (base image, extra instructions)
 * @returns Dockerfile content as a string
 */
-function getDockerfileContent(outputDirName) {
-	return `FROM node:24-slim AS runtime
+function getDockerfileContent(outputDirName, options = {}) {
+	return `FROM ${options.baseImage ?? "node:24-slim"} AS runtime
 
 WORKDIR /app
 
-# Copy the Nitro build output
+${options.extraInstructions?.length ? `${options.extraInstructions.join("\n")}\n\n` : ""}# Copy the Nitro build output
 COPY ${outputDirName}/ ${outputDirName}/
 
 ENV NODE_ENV=production
@@ -248,12 +249,12 @@ async function checkDockerInstalled() {
 		return false;
 	}
 }
-async function writeDockerfile(outputDir) {
+async function writeDockerfile(outputDir, options) {
 	const outputDirName = basename(outputDir);
 	const c8yDir = join(outputDir, "../.c8y");
 	const dockerfilePath = join(c8yDir, "Dockerfile");
 	await mkdir(c8yDir, { recursive: true });
-	await writeFile(dockerfilePath, getDockerfileContent(outputDirName), "utf-8");
+	await writeFile(dockerfilePath, getDockerfileContent(outputDirName, options), "utf-8");
 	return c8yDir;
 }
 async function buildDockerImage(nitro, c8yDir) {
@@ -302,12 +303,13 @@ async function saveDockerImageToTar(nitro, c8yDir, imageName) {
 /**
 * Create a Docker image from the Nitro build output
 * @param nitro Nitro instance
+* @param options Dockerfile customization (base image, extra instructions)
 * @returns Path to the saved Docker image tar file
 */
-async function createDockerImage(nitro) {
+async function createDockerImage(nitro, options = {}) {
 	if (!await checkDockerInstalled()) throw new Error("Docker is not installed or not available in PATH. Please install Docker to build images.");
 	nitro.logger.debug("Creating Docker image...");
-	const c8yDir = await writeDockerfile(nitro.options.output.dir);
+	const c8yDir = await writeDockerfile(nitro.options.output.dir, options);
 	const imageTarPath = await saveDockerImageToTar(nitro, c8yDir, await buildDockerImage(nitro, c8yDir));
 	nitro.logger.debug("Docker image creation complete.");
 	return imageTarPath;
@@ -337,12 +339,12 @@ function formatBytes(bytes) {
 function resolveZipOutputPath(rootDir, options, manifest) {
 	return join$1(join$1(rootDir, options.outputDir ?? "./"), typeof options.name === "function" ? options.name(manifest.name, manifest.version) : options.name ?? `${manifest.name}-${manifest.version}.zip`);
 }
-async function createC8yZip(nitro, options = {}) {
+async function createC8yZip(nitro, options = {}, dockerOptions = {}) {
 	const startTime = Date.now();
 	const spinnerName = "c8y-zip";
 	spinnies.add(spinnerName, { text: "Creating Dockerfile..." });
 	spinnies.update(spinnerName, { text: "Building Docker image..." });
-	const imageTarPath = await createDockerImage(nitro);
+	const imageTarPath = await createDockerImage(nitro, dockerOptions);
 	spinnies.update(spinnerName, { text: "Creating manifest..." });
 	const manifest = await createC8yManifestFromNitro(nitro);
 	spinnies.update(spinnerName, { text: "Reading image.tar..." });
@@ -421,6 +423,9 @@ 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 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 ?? []];
 }
 //#endregion
 //#region src/module/registerRuntime.ts
@@ -460,6 +465,15 @@ function registerRuntime(nitro, options = {}) {
 		handler,
 		middleware: true
 	})));
+	if (Boolean(nitro.options.experimental?.openAPI && (isNitroDev || nitro.options.openAPI?.production))) if (!isNitroDev && nitro.options.openAPI?.production === "prerender") nitro.logger.warn("c8y-nitro cannot transform a prerendered OpenAPI document (internal routes stay listed and the server URL is baked in at build time). Use `openAPI: { production: true }` to serve the document at runtime instead.");
+	else {
+		nitro.options.handlers.push({
+			route: "/**",
+			handler: join$1(thisFilePath, "./runtime/handlers/openapi"),
+			middleware: true
+		});
+		nitro.logger.debug(`Registered OpenAPI transform middleware for ${nitro.options.openAPI?.route || "/_openapi.json"}`);
+	}
 	/**
 	* Handlers (can't be auto scanned as they need methods etc)
 	*/
@@ -747,7 +761,7 @@ function c8y() {
 				}
 			});
 			nitro.hooks.hook("close", async () => {
-				if (nitro.options.preset !== "nitro-dev") await createC8yZip(nitro, options.zip);
+				if (nitro.options.preset !== "nitro-dev") await createC8yZip(nitro, options.zip, options.docker);
 			});
 		}
 	};

package/dist/logging-BUYT8Z2V.mjs

@@ -0,0 +1,57 @@
+import { createError } from "evlog";
+import "evlog/nitro/v3";
+//#region src/utils/logging.ts
+/**
+* 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
+* wide log event **and** serialized into the JSON response under a `data` key.
+*
+* ## What the caller sees vs what stays on the server
+*
+* Every field **except `internal`** is sent to the client in the HTTP response.
+* `internal` is stripped from the response and only ever appears in your logs.
+*
+* | Field      | Sent to client? | Purpose                                                       |
+* | ---------- | :-------------: | ------------------------------------------------------------- |
+* | `message`  |       yes       | Short, safe summary of what went wrong.                       |
+* | `status`   |       yes       | HTTP status code (default `500`).                             |
+* | `code`     |       yes       | Stable machine-readable id (e.g. `'PAYMENT_DECLINED'`).       |
+* | `why`      |       yes       | Human-readable cause — safe to expose, no secrets.            |
+* | `fix`      |       yes       | What the caller can do about it.                              |
+* | `link`     |       yes       | Docs URL with more detail.                                    |
+* | `cause`    |  no (logged)    | The original `Error` you caught.                              |
+* | `internal` |  no (logged)    | Backend-only diagnostics — never reaches the client.          |
+*
+* ## Do NOT leak internal system errors
+*
+* Put anything sensitive or diagnostic (raw Cumulocity core responses, DB
+* errors, tokens, tenant internals) in `internal`, **not** in `message`/`why`.
+* `internal` is logged for debugging but never serialized to the response.
+*
+* @example
+* // User-facing error — every field here is visible to the caller:
+* throw createError({
+*   code: 'PAYMENT_DECLINED',
+*   message: 'Payment failed',
+*   status: 402,
+*   why: 'Card declined by issuer',
+*   fix: 'Try a different payment method',
+*   link: 'https://docs.example.com/payments/declined',
+* })
+*
+* @example
+* // Wrapping an upstream failure — keep the raw payload server-side only:
+* catch (cause) {
+*   throw createError({
+*     status: 502,
+*     message: 'Upstream request failed', // safe, generic — what the caller sees
+*     cause: cause as Error,
+*     internal: { upstreamStatus: cause?.res?.status, upstreamBody: cause?.data },
+*   })
+* }
+*
+* @see https://www.evlog.dev
+*/
+const createError$1 = createError;
+//#endregion
+export { createError$1 as t };

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

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

package/dist/runtime/handlers/invalidateTenantOptions.mjs

@@ -1,222 +1,9 @@
-import { t as createError } from "../../logging-DYnYICoX.mjs";
+import { t as createError } from "../../logging-BUYT8Z2V.mjs";
+import { t as useDeployedTenantClient } from "../../client-DxmbyZju.mjs";
 import { c8yTenantOptionKeys } from "c8y-nitro/runtime";
-import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
 import { defineCachedFunction } from "nitro/cache";
-import { Buffer } from "node:buffer";
-import { createHash, randomBytes } from "node:crypto";
-import process from "node:process";
 import { useRuntimeConfig } from "nitro/runtime-config";
-import { useNitroHooks } from "nitro/app";
 import { defineEventHandler, getQuery } from "nitro/h3";
-//#region src/utils/internal/common.ts
-/**
-* 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
-* - `cookie`: Used to extract XSRF-TOKEN and authorization token from cookies
-*
-* The MicroserviceClientRequestAuth class will automatically:
-* - Extract XSRF-TOKEN from cookies for CSRF protection
-* - Extract authorization token from cookies (prioritized over header auth)
-* - Fall back to Authorization header if no cookie-based auth is present
-*
-* @param request - The HTTP request containing headers
-* @returns Headers object compatible with \@c8y/client's MicroserviceClientRequestAuth
-*/
-function convertRequestHeadersToC8yFormat(request) {
-	const headers = {};
-	const authorization = request.headers.get("authorization");
-	if (authorization) headers.authorization = authorization;
-	const cookie = request.headers.get("cookie");
-	if (cookie) headers.cookie = cookie;
-	return headers;
-}
-//#endregion
-//#region src/utils/internal/tenant.ts
-const USER_TENANT_CACHE_SALT = randomBytes(32).toString("hex");
-function getCookieValue(cookieHeader, name) {
-	try {
-		const value = cookieHeader?.match(`(^|;)\\s*${name}\\s*=\\s*([^;]+)`);
-		return value ? value.pop() : void 0;
-	} catch {
-		return;
-	}
-}
-function getCurrentUserTenantCacheKeyMaterial(requestOrEvent) {
-	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
-	const cookieAuth = getCookieValue(request.headers.get("cookie"), "authorization");
-	if (cookieAuth) return `cookie:${cookieAuth}`;
-	const authorization = request.headers.get("authorization");
-	if (authorization) return `header:${authorization}`;
-}
-function createCurrentUserTenantCacheKey(requestOrEvent) {
-	const material = getCurrentUserTenantCacheKeyMaterial(requestOrEvent);
-	if (!material) throw new Error("Cannot create current user tenant cache key without auth material");
-	return createHash("sha256").update(USER_TENANT_CACHE_SALT).update(":").update(material).digest("hex");
-}
-function tryGetTenantFromBasicAuth(requestOrEvent) {
-	const authorization = ("req" in requestOrEvent ? requestOrEvent.req : requestOrEvent).headers.get("authorization");
-	if (!authorization?.startsWith("Basic ")) return;
-	try {
-		const decoded = Buffer.from(authorization.slice(6), "base64").toString("utf8");
-		const separatorIndex = decoded.indexOf(":");
-		const userPart = separatorIndex === -1 ? decoded : decoded.slice(0, separatorIndex);
-		const slashIndex = userPart.indexOf("/");
-		if (slashIndex <= 0) return;
-		return userPart.slice(0, slashIndex);
-	} catch {
-		return;
-	}
-}
-defineCachedFunction(async (requestOrEvent) => {
-	const basicTenant = tryGetTenantFromBasicAuth(requestOrEvent);
-	if (basicTenant) return basicTenant;
-	return (await useUserClient(requestOrEvent).tenant.current()).data.name;
-}, {
-	maxAge: 60,
-	name: "_c8y_nitro_get_current_user_tenant_id",
-	group: "c8y_nitro",
-	swr: false,
-	getKey: (requestOrEvent) => createCurrentUserTenantCacheKey(requestOrEvent),
-	shouldBypassCache: (requestOrEvent) => !getCurrentUserTenantCacheKeyMaterial(requestOrEvent)
-});
-//#endregion
-//#region src/utils/credentials.ts
-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;
-}
-/**
-* Fetches credentials for all tenants subscribed to this microservice.\
-* Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
-* Results are cached based on the configured TTL (default: 10 minutes).\
-* @returns Object mapping tenant IDs to their respective credentials
-* @config Cache TTL can be configured via:
-* - `c8y.cache.credentialsTTL` in the Nitro config (value in seconds)
-* - `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable
-* @example
-* // Get all subscribed tenant credentials:
-* const credentials = await useSubscribedTenantCredentials()
-* console.log(Object.keys(credentials)) // ['t12345', 't67890']
-*
-* // Access specific tenant:
-* const tenant1Creds = credentials['t12345']
-*
-* // Invalidate cache:
-* await useSubscribedTenantCredentials.invalidate()
-*
-* // Force refresh:
-* const freshCreds = await useSubscribedTenantCredentials.refresh()
-*/
-const cachedSubscribedTenantCredentials = defineCachedFunction(async () => {
-	const newCredentials = (await Client.getMicroserviceSubscriptions({
-		tenant: process.env.C8Y_BOOTSTRAP_TENANT,
-		user: process.env.C8Y_BOOTSTRAP_USER,
-		password: process.env.C8Y_BOOTSTRAP_PASSWORD
-	}, process.env.C8Y_BASEURL)).reduce((acc, cred) => {
-		if (cred.tenant) acc[cred.tenant] = cred;
-		return acc;
-	}, {});
-	if (shouldEmitTenantCredentialsUpdated(prevCredentials, newCredentials)) useNitroHooks().callHook("c8y:tenantCredentialsUpdated", prevCredentials, newCredentials);
-	prevCredentials = newCredentials;
-	return newCredentials;
-}, {
-	maxAge: useRuntimeConfig().c8yCredentialsCacheTTL ?? 600,
-	name: "_c8y_nitro_get_subscribed_tenant_credentials",
-	group: "c8y_nitro",
-	swr: false
-});
-const useSubscribedTenantCredentials = Object.assign(async () => {
-	const credentials = await cachedSubscribedTenantCredentials();
-	prevCredentials = credentials;
-	return credentials;
-}, {
-	invalidate: cachedSubscribedTenantCredentials.invalidate,
-	refresh: async () => {
-		await cachedSubscribedTenantCredentials.invalidate();
-		const credentials = await cachedSubscribedTenantCredentials();
-		prevCredentials = credentials;
-		return credentials;
-	}
-});
-/**
-* Fetches credentials for the tenant where this microservice is deployed.\
-* Uses the C8Y_BOOTSTRAP_TENANT environment variable to identify the deployed tenant.\
-* Returns credentials from the subscribed tenant credentials cache (cached based on configured TTL, default: 10 minutes).
-* @returns Credentials for the deployed tenant
-* @throws {EvlogError} If no credentials found for the deployed tenant
-* @example
-* // Get deployed tenant credentials:
-* const creds = await useDeployedTenantCredentials()
-* console.log(creds.tenant, creds.user)
-*
-* // Invalidate cache:
-* await useDeployedTenantCredentials.invalidate()
-*
-* // Force refresh:
-* 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.
-*/
-const useDeployedTenantCredentials = Object.assign(async () => {
-	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
-	const allCredsPromise = await useSubscribedTenantCredentials();
-	if (!allCredsPromise[tenant]) throw createError({
-		message: `No credentials found for tenant deployed tenant '${tenant}'`,
-		status: 500
-	});
-	return allCredsPromise[tenant];
-}, {
-	invalidate: useSubscribedTenantCredentials.invalidate,
-	refresh: async () => {
-		await useSubscribedTenantCredentials.refresh();
-		return await useDeployedTenantCredentials();
-	}
-});
-//#endregion
-//#region 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.
-* @param requestOrEvent - The H3Event or ServerRequest from the current request
-* @returns A configured Cumulocity Client instance
-* @example
-* // In a request handler:
-* const client = useUserClient(event)
-* const { data } = await client.inventory.list()
-*/
-function useUserClient(requestOrEvent) {
-	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
-	if (request.context?.["c8y_user_client"]) return request.context["c8y_user_client"];
-	const client = new Client(new MicroserviceClientRequestAuth(convertRequestHeadersToC8yFormat(request)), process.env.C8Y_BASEURL);
-	request.context ??= {};
-	request.context["c8y_user_client"] = client;
-	return 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.\
-* @returns A configured Cumulocity Client instance for the deployed tenant
-* @example
-* // Get client for the tenant hosting this microservice:
-* const client = await useDeployedTenantClient()
-* const { data } = await client.application.list()
-*/
-async function useDeployedTenantClient() {
-	const creds = await useSubscribedTenantCredentials();
-	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
-	if (!creds[tenant]) throw createError({
-		message: `No subscribed tenant credentials found for tenant '${tenant}'`,
-		status: 500
-	});
-	const client = new Client(new BasicAuth(creds[tenant]), process.env.C8Y_BASEURL);
-	client.core.tenant = tenant;
-	return client;
-}
-//#endregion
 //#region src/utils/internal/tenantOptionFetchers.ts
 /**
 * Internal storage for cached option fetchers, keyed by

package/dist/runtime/handlers/openapi.mjs

@@ -0,0 +1,56 @@
+import { n as getUserTenantDomain } from "../../client-DxmbyZju.mjs";
+import { c8yManifest } from "c8y-nitro/runtime";
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { getRequestURL } from "nitro/h3";
+import { defineMiddleware } from "nitro";
+//#region src/module/runtime/handlers/openapi.ts
+function isOpenAPIDocument(value) {
+	return Boolean(value) && typeof value === "object" && "openapi" in value;
+}
+function joinURLSegments(origin, ...segments) {
+	const path = segments.map((segment) => segment?.replace(/^\/+|\/+$/g, "") ?? "").filter((segment) => segment.length > 0).join("/");
+	return path ? `${origin}/${path}` : origin;
+}
+async function resolveServer(event) {
+	const baseURL = useRuntimeConfig().app?.baseURL;
+	const contextPath = c8yManifest.contextPath ?? c8yManifest.name;
+	if (!import.meta.dev) try {
+		const domain = await getUserTenantDomain(event);
+		if (domain) return {
+			url: joinURLSegments(`https://${domain}`, "service", contextPath, baseURL),
+			description: "Cumulocity microservice endpoint"
+		};
+	} catch {}
+	const requestUrl = getRequestURL(event, {
+		xForwardedHost: true,
+		xForwardedProto: true
+	});
+	if (event.req.headers.has("x-forwarded-host")) return {
+		url: joinURLSegments(requestUrl.origin, "service", contextPath, baseURL),
+		description: "Cumulocity microservice endpoint"
+	};
+	return {
+		url: joinURLSegments(requestUrl.origin, baseURL),
+		description: "Direct server endpoint"
+	};
+}
+/**
+* Transforms the OpenAPI document generated by Nitro for Cumulocity microservices:
+* strips internal routes (probes, `/_c8y_nitro/**`, the spec/UI routes themselves)
+* and rewrites the advertised server URL to the public tenant endpoint instead of
+* the internal (e.g. cluster-local) host the service listens on.
+*/
+var openapi_default = defineMiddleware(async (event, next) => {
+	const runtimeConfig = useRuntimeConfig();
+	const specRoute = runtimeConfig.nitro?.openAPI?.route || "/_openapi.json";
+	const baseURL = (runtimeConfig.app?.baseURL ?? "/").replace(/\/+$/, "");
+	if (event.url.pathname !== `${baseURL}${specRoute}`) return next();
+	const body = await next();
+	if (!isOpenAPIDocument(body)) return body;
+	const excludedPrefixes = runtimeConfig.c8yOpenApiExcludeRoutes ?? [];
+	if (body.paths && excludedPrefixes.length > 0) body.paths = Object.fromEntries(Object.entries(body.paths).filter(([path]) => !excludedPrefixes.some((prefix) => path.startsWith(prefix))));
+	body.servers = [await resolveServer(event)];
+	return body;
+});
+//#endregion
+export { openapi_default as default };

package/dist/runtime/middlewares/c8y-client.mjs

@@ -1,4 +1,4 @@
-import { t as createError } from "../../logging-DYnYICoX.mjs";
+import { t as createError } from "../../logging-BUYT8Z2V.mjs";
 import process from "node:process";
 import { defineMiddleware } from "nitro";
 //#region src/module/runtime/middlewares/c8y-client.ts

package/dist/types.d.mts

@@ -1,3 +1,3 @@
-import { a as C8YTenantOptionKeysCacheConfig, c as C8YZipOptions, d as C8YAPIClientOptions, i as C8YTenantOptionKey, l as C8YManifest, n as C8yNitroModuleOptions, o as C8YRoles, r as C8YSettingsCategory, s as C8yCacheOptions, t as C8yDevOptions, u as C8YManifestOptions } from "./index-ByDSMEvU.mjs";
+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 { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
-export { C8YAPIClientOptions, type C8YManifest, type C8YManifestOptions, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, type C8YZipOptions, type C8yCacheOptions, C8yDevOptions, C8yNitroModuleOptions, type TenantCredentials };
+export { C8YAPIClientOptions, type C8YManifest, type C8YManifestOptions, C8YRoles, C8YSettingsCategory, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, type C8YZipOptions, type C8yCacheOptions, C8yDevOptions, type C8yDockerOptions, C8yNitroModuleOptions, C8yOpenAPIOptions, type TenantCredentials };

package/dist/utils.d.mts

@@ -1,8 +1,7 @@
 import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
-import { useLogger } from "evlog/nitro/v3";
 import { Client, ICredentials, ICurrentUser } from "@c8y/client";
-import { createError, createLogger } from "evlog";
-import { EventHandler, H3Event } from "nitro/h3";
+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";
 //#region src/utils/client.d.ts
@@ -425,6 +424,84 @@ interface UseTenantOptions {
  */
 declare const useTenantOptions: UseTenantOptions;
 //#endregion
+//#region src/utils/logging.d.ts
+/**
+ * Returns the request-scoped wide-event logger for the current request.
+ *
+ * Accepts **either** an `H3Event` (as received by a route handler) **or** the
+ * `ServerRequest` returned by Nitro's `useRequest()` — both carry the same
+ * request context, so `useLogger(event)` and `useLogger(useRequest())` are
+ * equivalent.
+ *
+ * evlog's own `useLogger` only accepts an `H3Event` and reads the logger from
+ * `event.req.context.log`; `useRequest()` returns that `ServerRequest` directly
+ * (no `.req`), which would throw. This wrapper normalizes both shapes to the
+ * `{ req }` event evlog expects, restoring the accept-both behavior.
+ *
+ * @param eventOrRequest - The current `H3Event` or `ServerRequest` (`useRequest()`).
+ * @param service - Optional service name to override the default.
+ * @example
+ * // In a route handler:
+ * const log = useLogger(event)
+ *
+ * // Deeper in the call stack with experimental.asyncContext enabled:
+ * 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>;
+/**
+ * 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
+ * wide log event **and** serialized into the JSON response under a `data` key.
+ *
+ * ## What the caller sees vs what stays on the server
+ *
+ * Every field **except `internal`** is sent to the client in the HTTP response.
+ * `internal` is stripped from the response and only ever appears in your logs.
+ *
+ * | Field      | Sent to client? | Purpose                                                       |
+ * | ---------- | :-------------: | ------------------------------------------------------------- |
+ * | `message`  |       yes       | Short, safe summary of what went wrong.                       |
+ * | `status`   |       yes       | HTTP status code (default `500`).                             |
+ * | `code`     |       yes       | Stable machine-readable id (e.g. `'PAYMENT_DECLINED'`).       |
+ * | `why`      |       yes       | Human-readable cause — safe to expose, no secrets.            |
+ * | `fix`      |       yes       | What the caller can do about it.                              |
+ * | `link`     |       yes       | Docs URL with more detail.                                    |
+ * | `cause`    |  no (logged)    | The original `Error` you caught.                              |
+ * | `internal` |  no (logged)    | Backend-only diagnostics — never reaches the client.          |
+ *
+ * ## Do NOT leak internal system errors
+ *
+ * Put anything sensitive or diagnostic (raw Cumulocity core responses, DB
+ * errors, tokens, tenant internals) in `internal`, **not** in `message`/`why`.
+ * `internal` is logged for debugging but never serialized to the response.
+ *
+ * @example
+ * // User-facing error — every field here is visible to the caller:
+ * throw createError({
+ *   code: 'PAYMENT_DECLINED',
+ *   message: 'Payment failed',
+ *   status: 402,
+ *   why: 'Card declined by issuer',
+ *   fix: 'Try a different payment method',
+ *   link: 'https://docs.example.com/payments/declined',
+ * })
+ *
+ * @example
+ * // Wrapping an upstream failure — keep the raw payload server-side only:
+ * catch (cause) {
+ *   throw createError({
+ *     status: 502,
+ *     message: 'Upstream request failed', // safe, generic — what the caller sees
+ *     cause: cause as Error,
+ *     internal: { upstreamStatus: cause?.res?.status, upstreamBody: cause?.data },
+ *   })
+ * }
+ *
+ * @see https://www.evlog.dev
+ */
+declare const createError: typeof createError$1;
+//#endregion
 //#region src/utils/schedule.d.ts
 type ScheduledTaskPayload = TaskPayload;
 type ScheduledTaskContext = TaskContext;

package/dist/utils.mjs

@@ -1,10 +1,10 @@
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import process from "node:process";
-import { useLogger } from "evlog/nitro/v3";
+import { useLogger as useLogger$1 } from "evlog/nitro/v3";
 import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
 import { defineCachedFunction } from "nitro/cache";
-import { createError, createLogger } from "evlog";
+import { createError as createError$1, createLogger } from "evlog";
 import { useRuntimeConfig } from "nitro/runtime-config";
 import { useNitroHooks } from "nitro/app";
 import { defineHandler } from "nitro/h3";
@@ -83,6 +83,95 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 	getKey: (requestOrEvent) => createCurrentUserTenantCacheKey(requestOrEvent),
 	shouldBypassCache: (requestOrEvent) => !getCurrentUserTenantCacheKeyMaterial(requestOrEvent)
 });
+defineCachedFunction(async (requestOrEvent, _tenantId) => {
+	return (await useUserClient(requestOrEvent).tenant.current()).data.domainName;
+}, {
+	maxAge: 86400,
+	name: "_c8y_nitro_get_user_tenant_domain",
+	group: "c8y_nitro",
+	swr: false,
+	getKey: (_requestOrEvent, tenantId) => tenantId
+});
+//#endregion
+//#region src/utils/logging.ts
+/**
+* Returns the request-scoped wide-event logger for the current request.
+*
+* Accepts **either** an `H3Event` (as received by a route handler) **or** the
+* `ServerRequest` returned by Nitro's `useRequest()` — both carry the same
+* request context, so `useLogger(event)` and `useLogger(useRequest())` are
+* equivalent.
+*
+* evlog's own `useLogger` only accepts an `H3Event` and reads the logger from
+* `event.req.context.log`; `useRequest()` returns that `ServerRequest` directly
+* (no `.req`), which would throw. This wrapper normalizes both shapes to the
+* `{ req }` event evlog expects, restoring the accept-both behavior.
+*
+* @param eventOrRequest - The current `H3Event` or `ServerRequest` (`useRequest()`).
+* @param service - Optional service name to override the default.
+* @example
+* // In a route handler:
+* const log = useLogger(event)
+*
+* // Deeper in the call stack with experimental.asyncContext enabled:
+* import { useRequest } from 'nitro/context'
+* const log = useLogger(useRequest())
+*/
+function useLogger(eventOrRequest, service) {
+	return useLogger$1("req" in eventOrRequest ? eventOrRequest : { req: eventOrRequest }, service);
+}
+/**
+* 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
+* wide log event **and** serialized into the JSON response under a `data` key.
+*
+* ## What the caller sees vs what stays on the server
+*
+* Every field **except `internal`** is sent to the client in the HTTP response.
+* `internal` is stripped from the response and only ever appears in your logs.
+*
+* | Field      | Sent to client? | Purpose                                                       |
+* | ---------- | :-------------: | ------------------------------------------------------------- |
+* | `message`  |       yes       | Short, safe summary of what went wrong.                       |
+* | `status`   |       yes       | HTTP status code (default `500`).                             |
+* | `code`     |       yes       | Stable machine-readable id (e.g. `'PAYMENT_DECLINED'`).       |
+* | `why`      |       yes       | Human-readable cause — safe to expose, no secrets.            |
+* | `fix`      |       yes       | What the caller can do about it.                              |
+* | `link`     |       yes       | Docs URL with more detail.                                    |
+* | `cause`    |  no (logged)    | The original `Error` you caught.                              |
+* | `internal` |  no (logged)    | Backend-only diagnostics — never reaches the client.          |
+*
+* ## Do NOT leak internal system errors
+*
+* Put anything sensitive or diagnostic (raw Cumulocity core responses, DB
+* errors, tokens, tenant internals) in `internal`, **not** in `message`/`why`.
+* `internal` is logged for debugging but never serialized to the response.
+*
+* @example
+* // User-facing error — every field here is visible to the caller:
+* throw createError({
+*   code: 'PAYMENT_DECLINED',
+*   message: 'Payment failed',
+*   status: 402,
+*   why: 'Card declined by issuer',
+*   fix: 'Try a different payment method',
+*   link: 'https://docs.example.com/payments/declined',
+* })
+*
+* @example
+* // Wrapping an upstream failure — keep the raw payload server-side only:
+* catch (cause) {
+*   throw createError({
+*     status: 502,
+*     message: 'Upstream request failed', // safe, generic — what the caller sees
+*     cause: cause as Error,
+*     internal: { upstreamStatus: cause?.res?.status, upstreamBody: cause?.data },
+*   })
+* }
+*
+* @see https://www.evlog.dev
+*/
+const createError = createError$1;
 //#endregion
 //#region src/utils/credentials.ts
 let prevCredentials = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8y-nitro",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [

package/dist/logging-DYnYICoX.mjs

@@ -1,3 +0,0 @@
-import "evlog/nitro/v3";
-import { createError } from "evlog";
-export { createError as t };