c8y-nitro 0.6.0 → 0.7.1

package/dist/utils.mjs

@@ -1,14 +1,14 @@
 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 { createHash, randomBytes, randomUUID } from "node:crypto";
-import { HTTPError, defineHandler } from "nitro/h3";
+import { createError as createError$1, createLogger } from "evlog";
 import { useRuntimeConfig } from "nitro/runtime-config";
 import { useNitroHooks } from "nitro/app";
+import { defineHandler } from "nitro/h3";
 import { c8yManifest } from "c8y-nitro/runtime";
-import { createError, createLogger } from "evlog";
 import { ms } from "itty-time";
 import { tasks } from "#nitro/virtual/tasks";
 //#region src/utils/internal/common.ts
@@ -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;
@@ -151,7 +240,7 @@ const useSubscribedTenantCredentials = Object.assign(async () => {
 * 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 {HTTPError} If no credentials found for the deployed tenant
+* @throws {EvlogError} If no credentials found for the deployed tenant
 * @example
 * // Get deployed tenant credentials:
 * const creds = await useDeployedTenantCredentials()
@@ -167,10 +256,9 @@ const useSubscribedTenantCredentials = Object.assign(async () => {
 const useDeployedTenantCredentials = Object.assign(async () => {
 	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
 	const allCredsPromise = await useSubscribedTenantCredentials();
-	if (!allCredsPromise[tenant]) throw new HTTPError({
+	if (!allCredsPromise[tenant]) throw createError({
 		message: `No credentials found for tenant deployed tenant '${tenant}'`,
-		status: 500,
-		statusText: "Internal Server Error"
+		status: 500
 	});
 	return allCredsPromise[tenant];
 }, {
@@ -186,7 +274,7 @@ const useDeployedTenantCredentials = Object.assign(async () => {
 * Results are cached in the request context for subsequent calls within the same request.
 * @param requestOrEvent - The H3Event or ServerRequest from the current request
 * @returns Credentials for the user's tenant
-* @throws {HTTPError} If no subscribed tenant credentials found for the user's tenant
+* @throws {EvlogError} If no subscribed tenant credentials found for the user's tenant
 * @example
 * // In a request handler:
 * const userCreds = await useUserTenantCredentials(event)
@@ -200,10 +288,9 @@ async function useUserTenantCredentials(requestOrEvent) {
 	if (request.context?.["c8y_user_tenant_credentials"]) return request.context["c8y_user_tenant_credentials"];
 	const tenantId = await getCurrentUserTenantId(requestOrEvent);
 	const userTenantCreds = (await useSubscribedTenantCredentials())[tenantId];
-	if (!userTenantCreds) throw new HTTPError({
+	if (!userTenantCreds) throw createError({
 		message: `No subscribed tenant credentials found for user tenant '${tenantId}'`,
-		status: 500,
-		statusText: "Internal Server Error"
+		status: 500
 	});
 	request.context ??= {};
 	request.context["c8y_user_tenant_credentials"] = userTenantCreds;
@@ -244,12 +331,12 @@ async function useUserTenantClient(requestOrEvent) {
 	if (request.context?.["c8y_user_tenant_client"]) return request.context["c8y_user_tenant_client"];
 	const tenantId = await getCurrentUserTenantId(requestOrEvent);
 	const creds = await useSubscribedTenantCredentials();
-	if (!creds[tenantId]) throw new HTTPError({
+	if (!creds[tenantId]) throw createError({
 		message: `No subscribed tenant credentials found for user tenant '${tenantId}'`,
-		status: 500,
-		statusText: "Internal Server Error"
+		status: 500
 	});
 	const tenantClient = new Client(new BasicAuth(creds[tenantId]), process.env.C8Y_BASEURL);
+	tenantClient.core.tenant = tenantId;
 	request.context ??= {};
 	request.context["c8y_user_tenant_client"] = tenantClient;
 	return tenantClient;
@@ -269,7 +356,11 @@ async function useUserTenantClient(requestOrEvent) {
 async function useSubscribedTenantClients() {
 	const creds = await useSubscribedTenantCredentials();
 	const clients = {};
-	for (const [tenant, tenantCreds] of Object.entries(creds)) clients[tenant] = new Client(new BasicAuth(tenantCreds), process.env.C8Y_BASEURL);
+	for (const [tenant, tenantCreds] of Object.entries(creds)) {
+		const client = new Client(new BasicAuth(tenantCreds), process.env.C8Y_BASEURL);
+		client.core.tenant = tenant;
+		clients[tenant] = client;
+	}
 	return clients;
 }
 /**
@@ -284,12 +375,13 @@ async function useSubscribedTenantClients() {
 async function useDeployedTenantClient() {
 	const creds = await useSubscribedTenantCredentials();
 	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
-	if (!creds[tenant]) throw new HTTPError({
+	if (!creds[tenant]) throw createError({
 		message: `No subscribed tenant credentials found for tenant '${tenant}'`,
-		status: 500,
-		statusText: "Internal Server Error"
+		status: 500
 	});
-	return new Client(new BasicAuth(creds[tenant]), process.env.C8Y_BASEURL);
+	const client = new Client(new BasicAuth(creds[tenant]), process.env.C8Y_BASEURL);
+	client.core.tenant = tenant;
+	return client;
 }
 //#endregion
 //#region src/utils/resources.ts
@@ -307,10 +399,9 @@ async function useUser(requestOrEvent) {
 	const request = "req" in requestOrEvent ? requestOrEvent.req : requestOrEvent;
 	if (request.context?.["c8y_user"]) return request.context["c8y_user"];
 	const { res, data: user } = await useUserClient(requestOrEvent).user.currentWithEffectiveRoles();
-	if (!res.ok) throw new HTTPError({
+	if (!res.ok) throw createError({
 		message: `Failed to fetch current user`,
-		status: res.status,
-		statusText: res.statusText
+		status: res.status
 	});
 	request.context ??= {};
 	request.context["c8y_user"] = user;
@@ -346,9 +437,8 @@ function hasUserRequiredRole(roleOrRoles) {
 		if (isProbeRequest(event.url.pathname)) return;
 		const requiredRoles = Array.isArray(roleOrRoles) ? roleOrRoles : [roleOrRoles];
 		const userRoles = await useUserRoles(event);
-		if (!requiredRoles.some((role) => userRoles.includes(role))) throw new HTTPError({
+		if (!requiredRoles.some((role) => userRoles.includes(role))) throw createError({
 			status: 403,
-			statusText: "Forbidden",
 			message: `User does not have required role(s) to access this resource: ${requiredRoles.join(", ")}`
 		});
 	});
@@ -358,9 +448,8 @@ function isUserFromAllowedTenant(tenantIdOrIds) {
 		if (isProbeRequest(event.url.pathname)) return;
 		const allowedTenants = Array.isArray(tenantIdOrIds) ? tenantIdOrIds : [tenantIdOrIds];
 		const userTenantId = await getCurrentUserTenantId(event);
-		if (!allowedTenants.includes(userTenantId)) throw new HTTPError({
+		if (!allowedTenants.includes(userTenantId)) throw createError({
 			status: 403,
-			statusText: "Forbidden",
 			message: `User's tenant '${userTenantId}' is not allowed to access this resource. Allowed tenants: ${allowedTenants.join(", ")}`
 		});
 	});
@@ -385,14 +474,9 @@ function isUserFromDeployedTenant() {
 		if (isProbeRequest(event.url.pathname)) return;
 		const userTenantId = await getCurrentUserTenantId(event);
 		const deployedTenantId = process.env.C8Y_BOOTSTRAP_TENANT;
-		if (!deployedTenantId) throw new HTTPError({
-			status: 500,
-			statusText: "Internal Server Error",
-			message: "C8Y_BOOTSTRAP_TENANT environment variable is not set"
-		});
-		if (userTenantId !== deployedTenantId) throw new HTTPError({
+		if (!deployedTenantId) throw new Error("C8Y_BOOTSTRAP_TENANT environment variable is not set");
+		if (userTenantId !== deployedTenantId) throw createError({
 			status: 403,
-			statusText: "Forbidden",
 			message: `Only users from tenant '${deployedTenantId}' can access this resource.`
 		});
 	});
@@ -400,14 +484,211 @@ function isUserFromDeployedTenant() {
 //#endregion
 //#region src/utils/internal/tenantOptionFetchers.ts
 /**
-* Internal storage for cached functions per key
+* Internal storage for cached option fetchers, keyed by
+* `${tenant}::${category}::${key}`.
+*
+* Including the tenant and category in the key keeps options from different
+* tenants (multi-tenancy) and settings categories from colliding on a shared
+* `key`.
 */
 const tenantOptionFetchers = {};
+/**
+* Builds the composite store key for a tenant/category/key triple.
+* @param tenant - The tenant id owning the option
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+function fetcherStoreKey(tenant, category, key) {
+	return `${tenant}::${category}::${key}`;
+}
 //#endregion
 //#region src/utils/tenantOptions.ts
 /**
+* The microservice's own settings category, resolved once from runtime config
+* (`manifest.settingsCategory` → `contextPath` → `name`). This is independent of
+* which tenant is targeted.
+*/
+function getOwnCategory() {
+	return useRuntimeConfig().c8ySettingsCategory;
+}
+/**
+* Resolves the tenant id a client operates on, used for per-tenant cache keys.
+*
+* Prefers the stamped `client.core.tenant` (set by the `use*Client` helpers);
+* otherwise resolves it on demand via `/tenant/currentTenant` and memoizes it
+* back onto the client.
+* @param client - The Cumulocity client
+*/
+async function resolveClientTenant(client) {
+	if (client.core.tenant) return client.core.tenant;
+	const res = await client.core.fetch("/tenant/currentTenant", {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	const tenant = res.ok ? (await res.json())?.name : void 0;
+	if (!tenant) throw createError({
+		status: 500,
+		message: "Could not determine the target tenant",
+		fix: "This is unexpected. Retry the request, and contact the microservice operator if it keeps happening.",
+		internal: {
+			reason: res.ok ? "GET /tenant/currentTenant returned no tenant name" : "GET /tenant/currentTenant failed",
+			upstreamStatus: res.status
+		}
+	});
+	client.core.tenant = tenant;
+	return tenant;
+}
+/**
+* Builds the Cumulocity Options API path for a category (and optional key).
+* @param category - The settings category
+* @param key - The tenant option key (omit for category-level operations)
+*/
+function optionsPath(category, key) {
+	const base = `/tenant/options/${encodeURIComponent(category)}`;
+	return key === void 0 ? base : `${base}/${encodeURIComponent(key)}`;
+}
+/**
+* Cumulocity role required to read tenant options.
+*/
+const OPTION_READ_ROLE = "ROLE_OPTION_MANAGEMENT_READ";
+/**
+* Cumulocity role required to create, update or delete tenant options.
+*/
+const OPTION_ADMIN_ROLE = "ROLE_OPTION_MANAGEMENT_ADMIN";
+/**
+* Builds a structured error for a failed Options API request.
+*
+* A failed options request is a microservice/config problem (e.g. a missing
+* `ROLE_OPTION_MANAGEMENT_*` role), not something the frontend caller can act on
+* — so the response is a **generic 500** that reveals nothing about tenant
+* options. All the diagnostic detail (which operation, upstream status, internal
+* endpoint/method, and the Cumulocity role it needs) goes into `internal`, which
+* is logged for debugging but never serialized to the HTTP response.
+* @param status - The upstream HTTP status (for `internal`)
+* @param operation - A human-readable summary of the failed operation (for `internal`)
+* @param internal - Backend-only debugging context (endpoint, method, required role)
+*/
+function optionRequestError(status, operation, internal) {
+	return createError({
+		status: 500,
+		message: "Internal Server Error",
+		internal: {
+			operation,
+			upstreamStatus: status,
+			...internal
+		}
+	});
+}
+/**
+* Reads a single option value directly from the Options API.
+* Returns `undefined` when the option is not set (404).
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+async function fetchOptionValue(client, category, key) {
+	const endpoint = optionsPath(category, key);
+	const res = await client.core.fetch(endpoint, {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	if (res.status === 404) return;
+	if (!res.ok) throw optionRequestError(res.status, `Failed to read tenant option '${key}'`, {
+		method: "GET",
+		endpoint,
+		requiredRole: OPTION_READ_ROLE
+	});
+	return (await res.json())?.value;
+}
+/**
+* Creates or updates a single option value (upsert) via the Options API.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+* @param value - The value to store
+*/
+async function putOptionValue(client, category, key, value) {
+	const endpoint = optionsPath(category, key);
+	const res = await client.core.fetch(endpoint, {
+		method: "PUT",
+		headers: {
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({ value })
+	});
+	if (!res.ok) throw optionRequestError(res.status, `Failed to set tenant option '${key}'`, {
+		method: "PUT",
+		endpoint,
+		requiredRole: OPTION_ADMIN_ROLE
+	});
+}
+/**
+* Deletes a single option via the Options API. Idempotent: a 404 resolves.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+async function deleteOptionValue(client, category, key) {
+	const endpoint = optionsPath(category, key);
+	const res = await client.core.fetch(endpoint, {
+		method: "DELETE",
+		headers: { Accept: "application/json" }
+	});
+	if (res.status === 404) return;
+	if (!res.ok) throw optionRequestError(res.status, `Failed to delete tenant option '${key}'`, {
+		method: "DELETE",
+		endpoint,
+		requiredRole: OPTION_ADMIN_ROLE
+	});
+}
+/**
+* Updates the `editable` flag of a single option (management tenant only).
+* @param client - The Cumulocity client (must be the management tenant)
+* @param category - The settings category
+* @param key - The tenant option key
+* @param editable - Whether the option may be edited
+* @param targetTenant - The tenant whose option flag is updated
+*/
+async function putOptionEditable(client, category, key, editable, targetTenant) {
+	const endpoint = `${optionsPath(category, key)}/editable`;
+	const res = await client.core.fetch(`${endpoint}?targetTenant=${encodeURIComponent(targetTenant)}`, {
+		method: "PUT",
+		headers: {
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({ editable })
+	});
+	if (!res.ok) throw optionRequestError(res.status, `Failed to update editable flag for tenant option '${key}'`, {
+		method: "PUT",
+		endpoint,
+		targetTenant,
+		requiredRole: `${OPTION_ADMIN_ROLE} (management tenant only)`
+	});
+}
+/**
+* Lists all options set in a category as a key/value map.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+*/
+async function listCategoryOptions(client, category) {
+	const endpoint = optionsPath(category);
+	const res = await client.core.fetch(endpoint, {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	if (res.status === 404) return {};
+	if (!res.ok) throw optionRequestError(res.status, `Failed to list tenant options for category '${category}'`, {
+		method: "GET",
+		endpoint,
+		requiredRole: OPTION_READ_ROLE
+	});
+	return { ...await res.json() };
+}
+/**
 * Gets the cache TTL for a specific tenant option key.
-* Uses per-key override if defined, otherwise falls back to default TTL.
+* Uses per-key override if defined, otherwise falls back to the default TTL.
 * @param key - The tenant option key
 */
 function getTenantOptionCacheTTL(key) {
@@ -415,24 +696,16 @@ function getTenantOptionCacheTTL(key) {
 	return config.c8yTenantOptionsPerKeyTTL?.[key] ?? config.c8yDefaultTenantOptionsTTL ?? 600;
 }
 /**
-* Factory function that creates a cached fetcher for a specific tenant option key.
+* Factory that creates a cached read fetcher for a specific tenant/category/key.
+* All fetchers share the same cache group so they can be invalidated together.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param tenant - The tenant id (for the cache key)
+* @param category - The settings category
 * @param key - The tenant option key
 */
-function createCachedTenantOptionFetcher(key) {
-	const cacheName = `_c8y_nitro_tenant_option_${key.replace(/\./g, "_")}`;
-	const cachedFetcher = defineCachedFunction(async () => {
-		const client = await useDeployedTenantClient();
-		const category = useRuntimeConfig().c8ySettingsCategory;
-		try {
-			return (await client.options.tenant.detail({
-				key,
-				category
-			})).data.value;
-		} catch (error) {
-			if (error?.res?.status === 404 || error?.status === 404) return;
-			throw error;
-		}
-	}, {
+function createCachedTenantOptionFetcher(client, tenant, category, key) {
+	const cacheName = `_c8y_nitro_tenant_option_${fetcherStoreKey(tenant, category, key).replace(/[^a-zA-Z0-9]/g, "_")}`;
+	const cachedFetcher = defineCachedFunction(async () => fetchOptionValue(client, category, key), {
 		maxAge: getTenantOptionCacheTTL(key),
 		name: cacheName,
 		group: "c8y_nitro",
@@ -444,24 +717,122 @@ function createCachedTenantOptionFetcher(key) {
 	} });
 }
 /**
-* Gets or creates a cached fetcher for a specific tenant option key.
+* Gets or creates the cached read fetcher for a tenant/category/key triple.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param tenant - The resolved tenant id
+* @param category - The settings category
 * @param key - The tenant option key
 */
-function getOrCreateFetcher(key) {
-	let fetcher = tenantOptionFetchers[key];
+function getOrCreateFetcher(client, tenant, category, key) {
+	const storeKey = fetcherStoreKey(tenant, category, key);
+	let fetcher = tenantOptionFetchers[storeKey];
 	if (!fetcher) {
-		fetcher = createCachedTenantOptionFetcher(key);
-		tenantOptionFetchers[key] = fetcher;
+		fetcher = createCachedTenantOptionFetcher(client, tenant, category, key);
+		tenantOptionFetchers[storeKey] = fetcher;
 	}
 	return fetcher;
 }
 /**
-* Fetches a tenant option value by key.\
-* Uses the deployed tenant's service user credentials to access the Options API.\
-* Results are cached based on the configured TTL (default: 10 minutes).
+* Invalidates the cached read for a store key, if one has been created.
+* @param storeKey - The composite `${tenant}::${category}::${key}` store key
+*/
+async function invalidateStoreKey(storeKey) {
+	const fetcher = tenantOptionFetchers[storeKey];
+	if (fetcher) await fetcher.invalidate();
+}
+/**
+* Invalidates every created fetcher whose store key matches the predicate.
+* @param predicate - Selects store keys to invalidate
+*/
+async function invalidateFetchers(predicate) {
+	await Promise.all(Object.entries(tenantOptionFetchers).filter(([storeKey]) => predicate(storeKey)).map(([, fetcher]) => fetcher.invalidate()));
+}
+/**
+* Refreshes every created fetcher whose store key matches the predicate.
+* @param predicate - Selects store keys to refresh
+* @returns Map of matched store keys to their refreshed values
+*/
+async function refreshFetchers(predicate) {
+	const entries = Object.entries(tenantOptionFetchers).filter(([storeKey]) => predicate(storeKey));
+	const values = await Promise.all(entries.map(([, fetcher]) => fetcher.refresh()));
+	return Object.fromEntries(entries.map(([storeKey], i) => [storeKey, values[i]]));
+}
+/**
+* Builds a single-option handle for a client/category/key.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+* @param key - The tenant option key
+*/
+function makeTenantOption(client, category, key) {
+	const currentStoreKey = async () => fetcherStoreKey(await resolveClientTenant(client), category, key);
+	const readFetcher = async () => getOrCreateFetcher(client, await resolveClientTenant(client), category, key);
+	return {
+		read: async () => (await readFetcher())(),
+		set: async (value) => {
+			await putOptionValue(client, category, key, value);
+			await invalidateStoreKey(await currentStoreKey());
+		},
+		getOrInsert: async (fallback) => {
+			const current = await (await readFetcher())();
+			if (current !== void 0) return current;
+			await putOptionValue(client, category, key, fallback);
+			await invalidateStoreKey(await currentStoreKey());
+			return fallback;
+		},
+		delete: async () => {
+			await deleteOptionValue(client, category, key);
+			await invalidateStoreKey(await currentStoreKey());
+		},
+		setEditable: async (editable, options) => {
+			await putOptionEditable(client, category, key, editable, options.targetTenant);
+			await invalidateStoreKey(await currentStoreKey());
+		},
+		refresh: async () => (await readFetcher()).refresh(),
+		invalidate: async () => invalidateStoreKey(await currentStoreKey())
+	};
+}
+/**
+* Builds a category handle. The runtime shape is identical for the own and
+* foreign categories; the public overloads differ only at the type level.
+* @param client - The Cumulocity client (determines tenant + auth)
+* @param category - The settings category
+*/
+function makeTenantOptionCategory(client, category) {
+	const categoryPrefix = async () => `${await resolveClientTenant(client)}::${category}::`;
+	return {
+		option: (key) => makeTenantOption(client, category, key),
+		list: () => listCategoryOptions(client, category),
+		setAll: async (values) => {
+			const entries = Object.entries(values);
+			await Promise.all(entries.map(([key, value]) => putOptionValue(client, category, key, value)));
+			const tenant = await resolveClientTenant(client);
+			await Promise.all(entries.map(([key]) => invalidateStoreKey(fetcherStoreKey(tenant, category, key))));
+		},
+		invalidateAll: async () => {
+			const prefix = await categoryPrefix();
+			await invalidateFetchers((storeKey) => storeKey.startsWith(prefix));
+		},
+		refreshAll: async () => {
+			const prefix = await categoryPrefix();
+			const refreshed = await refreshFetchers((storeKey) => storeKey.startsWith(prefix));
+			return Object.fromEntries(Object.entries(refreshed).map(([storeKey, value]) => [storeKey.slice(prefix.length), value]));
+		}
+	};
+}
+/**
+* Gets a handle for a single tenant option in the microservice's **own** settings
+* category, targeting the tenant of the given `client`.\
+* Reads are cached per tenant, using the client's service user credentials.
 *
-* @param key - The tenant option key to fetch (as defined in `manifest.settings`)
-* @returns The option value as a string
+* This is a shortcut for `useTenantOptions(client).option(key)` — it only drops
+* the category argument. For a single option in a **foreign** category, use
+* `useTenantOptions(client, category).option(key)`.
+*
+* Manifest-declared keys are offered via autocomplete, but any dynamic string
+* is accepted too (e.g. `encrypted.password.${hash}`).
+*
+* @param client - The Cumulocity client that determines the target tenant
+* @param key - The tenant option key
 *
 * @config Cache TTL can be configured via:
 * - `c8y.cache.defaultTenantOptionsTTL` — Default TTL for all keys (in seconds)
@@ -469,59 +840,48 @@ function getOrCreateFetcher(key) {
 * - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
 *
 * @example
-* // Fetch a tenant option:
-* const value = await useTenantOption('myOption')
+* // Read the owner tenant's config:
+* const value = await useTenantOption(await useDeployedTenantClient(), 'featureMode').read()
+*
+* // Read the current request tenant's config (multi-tenant):
+* const value = await useTenantOption(await useUserTenantClient(event), 'featureMode').read()
 *
-* // Fetch an encrypted secret:
-* const secret = await useTenantOption('credentials.apiKey')
+* // Create or update, or seed a dynamic key:
+* await useTenantOption(client, 'featureMode').set('advanced')
+* const token = await useTenantOption(client, `encrypted.password.${hash}`).getOrInsert('')
+*/
+function useTenantOption(client, key) {
+	return makeTenantOption(client, getOwnCategory(), key);
+}
+const useTenantOptionsBase = ((client, category) => makeTenantOptionCategory(client, category ?? getOwnCategory()));
+/**
+* Gets a handle for a whole settings category, targeting the tenant of the given
+* `client`.\
+* Omit the category (or pass the own {@link C8YSettingsCategory}) for the
+* microservice's own category; pass any other category to read/write options in
+* a foreign category (where `credentials.*` keys are rejected).
+*
+* @param client - The Cumulocity client that determines the target tenant
 *
-* // Invalidate cache for a specific key:
-* await useTenantOption.invalidate('myOption')
+* @example
+* const client = await useUserTenantClient(event)
+*
+* // Own category:
+* const values = await useTenantOptions(client).list()
+* await useTenantOptions(client).option('featureMode').set('advanced')
 *
-* // Force refresh a specific key:
-* const fresh = await useTenantOption.refresh('myOption')
+* // Foreign category:
+* const value = await useTenantOptions(client, 'other-service').option('someKey').read()
 *
-* // Invalidate all tenant option caches:
-* await useTenantOption.invalidateAll()
+* // Invalidate all cached options of one tenant + category:
+* await useTenantOptions(client, 'other-service').invalidateAll()
 *
-* // Refresh all tenant options:
-* const all = await useTenantOption.refreshAll()
+* // Invalidate everything, across all tenants and categories:
+* await useTenantOptions.invalidateAll()
 */
-const useTenantOption = Object.assign(async (key) => {
-	return await getOrCreateFetcher(key)();
-}, {
-	/**
-	* Invalidate the cache for a specific tenant option key.
-	* @param key - The tenant option key to invalidate
-	*/
-	invalidate: async (key) => {
-		const fetcher = tenantOptionFetchers[key];
-		if (fetcher) await fetcher.invalidate();
-	},
-	/**
-	* Force refresh a specific tenant option key (invalidates and re-fetches).
-	* @param key - The tenant option key to refresh
-	*/
-	refresh: async (key) => {
-		return await getOrCreateFetcher(key).refresh();
-	},
-	/**
-	* Invalidate all tenant option caches that have been accessed.
-	* Only invalidates keys that have been fetched at least once.
-	*/
-	invalidateAll: async () => {
-		await Promise.all(Object.values(tenantOptionFetchers).map((fetcher) => fetcher?.invalidate()));
-	},
-	/**
-	* Refresh all tenant options that have been accessed.
-	* Only refreshes keys that have been fetched at least once.
-	* @returns Object mapping keys to their refreshed values
-	*/
-	refreshAll: async () => {
-		const entries = Object.entries(tenantOptionFetchers);
-		const values = await Promise.all(entries.map(([, fetcher]) => fetcher?.refresh()));
-		return Object.fromEntries(entries.map(([key], i) => [key, values[i]]));
-	}
+const useTenantOptions = Object.assign(useTenantOptionsBase, {
+	invalidateAll: () => invalidateFetchers(() => true),
+	refreshAll: () => refreshFetchers(() => true)
 });
 //#endregion
 //#region src/utils/schedule.ts
@@ -688,4 +1048,4 @@ async function cancelScheduledTask(id) {
 	return cancelled;
 }
 //#endregion
-export { cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+export { cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };