c8y-nitro 0.1.2 → 0.3.0

package/README.md

@@ -103,6 +103,8 @@ C8Y_BOOTSTRAP_PASSWORD=<generated-password>
 
 > **Manual Bootstrap**: For more control or troubleshooting, you can use the [CLI bootstrap command](#cli-commands) to manually register your microservice.
 
+> **Disable Auto-Bootstrap**: Set `skipBootstrap: true` in your c8y config to disable auto-bootstrap entirely. This is useful in CI/CD pipelines or when you want to manage bootstrap manually.
+
 ## Automatic Zip Creation
 
 `c8y-nitro` automatically generates a ready-to-deploy microservice zip package after each build. The process includes:
@@ -134,6 +136,35 @@ For all available manifest options, see the [Cumulocity Microservice Manifest do
 
 > **Note**: Health probe endpoints (`/_c8y_nitro/liveness` and `/_c8y_nitro/readiness`) are automatically injected if not manually defined.
 
+## Cache Configuration
+
+Credential caching can be configured to optimize performance. By default, subscribed tenant credentials are cached for 10 minutes.
+
+```ts
+export default defineNitroConfig({
+  c8y: {
+    cache: {
+      credentialsTTL: 300, // Cache credentials for 5 minutes (in seconds)
+      defaultTenantOptionsTTL: 600, // Default cache for tenant options (in seconds)
+      tenantOptions: {
+        'myOption': 300, // Per-key override: 5 minutes
+        'credentials.secret': 60, // Per-key override: 1 minute
+      },
+    }
+  },
+  modules: [c8y()],
+})
+```
+
+You can also override these at runtime using environment variables:
+
+```sh
+NITRO_C8Y_CREDENTIALS_CACHE_TTL=300
+NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL=300
+```
+
+> **Note**: The credentials cache is used by `useSubscribedTenantCredentials()` and `useDeployedTenantCredentials()` utilities. Both share the same cache.
+
 ## Development User Injection
 
 During development, `c8y-nitro` automatically injects your development user credentials into all requests. This allows you to test authentication and authorization middlewares locally.
@@ -212,6 +243,109 @@ export class MyComponent {
 
 > **Note**: The client regenerates automatically when routes change during development.
 
+## Logging
+
+`c8y-nitro` builds on [evlog](https://www.evlog.dev) to provide structured **wide-event logging**, one comprehensive log per request that accumulates all relevant context rather than scattering individual log lines throughout your code.
+
+evlog is automatically configured, no extra setup required. The service name is derived from your package name.
+
+### useLogger
+
+Use `useLogger(event)` in your route handlers to get a request-scoped logger. The logger accumulates context throughout the request lifetime and emits a single wide event when the response is sent.
+
+```ts
+import { defineHandler } from 'nitro/h3'
+import { useLogger } from 'c8y-nitro/utils'
+
+export default defineHandler(async (event) => {
+  const log = useLogger(event)
+
+  const user = await useUser(event)
+  log.set({ action: 'process-order', user: { id: user.userName } })
+
+  // Add more context as it becomes available
+  log.set({ order: { id: '42', total: 9999 } })
+
+  return { success: true }
+})
+```
+
+> **Note**: `useLogger` requires the `event` parameter. If you enable `experimental.asyncContext: true` in your Nitro config, you can access the logger anywhere in the call stack via `useRequest()` from `nitro/context` — see the [evlog Nitro v3 setup](https://www.evlog.dev/getting-started/installation#nitro-v3) for details.
+
+### createError
+
+Use `createError` from `c8y-nitro/utils` instead of Nitro's built-in error helper to get richer, structured error responses. This adds `why`, `fix`, and `link` fields that are:
+
+- Logged as part of the wide event so you can see exactly what went wrong without guessing
+- Returned in the JSON response body so clients can display actionable context
+
+```ts
+import { defineHandler } from 'nitro/h3'
+import { useLogger, createError } from 'c8y-nitro/utils'
+
+export default defineHandler(async (event) => {
+  const log = useLogger(event)
+  log.set({ action: 'payment', userId: 'user_123' })
+
+  throw createError({
+    message: 'Payment failed',
+    status: 402,
+    why: 'Card declined by issuer (insufficient funds)',
+    fix: 'Try a different payment method or contact your bank',
+    link: 'https://docs.example.com/payments/declined',
+  })
+})
+```
+
+The error response returned to the client:
+
+```json
+{
+  "message": "Payment failed",
+  "status": 402,
+  "data": {
+    "why": "Card declined by issuer (insufficient funds)",
+    "fix": "Try a different payment method or contact your bank",
+    "link": "https://docs.example.com/payments/declined"
+  }
+}
+```
+
+> **Tip**: Always prefer `createError` from `c8y-nitro/utils`. It ensures the error is captured in the wide log event with full context, making investigation straightforward.
+
+### createLogger (standalone)
+
+For code that runs **outside a request handler** — background jobs, queue workers, event-driven workflows, scheduled tasks — use `createLogger()` to get the same wide-event logger interface without needing an HTTP event.
+
+```ts
+import { createLogger } from 'c8y-nitro/utils'
+
+export async function processSubscriptionRenewal(tenantId: string) {
+  const log = createLogger({ job: 'subscription-renewal', tenantId })
+
+  log.set({ subscription: { id: 'sub_123', plan: 'pro' } })
+
+  // ... do work ...
+
+  log.set({ result: 'renewed' })
+  log.emit() // Must call emit() manually outside request context
+}
+```
+
+This is useful for Cumulocity notification workflows where your microservice reacts to platform events (device management, alarms, etc.) outside of the standard request/response cycle.
+
+> **Note**: Unlike `useLogger`, `createLogger` does **not** auto-emit at request end. You must call `log.emit()` manually when the work is complete.
+
+For more on wide events, structured errors, and advanced configuration (sampling, draining to Axiom/Loki, enrichers), see the [evlog documentation](https://www.evlog.dev/core-concepts/wide-events).
+
+### Logging Utilities
+
+| Function               | Description                                                   | Request Context |
+| ---------------------- | ------------------------------------------------------------- | :-------------: |
+| `useLogger(event)`     | Get the request-scoped wide-event logger                      |       ✅        |
+| `createLogger(ctx?)`   | Create a standalone wide-event logger; call `emit()` manually |       ❌        |
+| `createError(options)` | Create a structured error with `why`, `fix`, `link`           |       ❌        |
+
 ## Utilities
 
 `c8y-nitro` provides several utility functions to simplify common tasks in Cumulocity microservices.
@@ -261,13 +395,66 @@ async function anotherFunction() {
 
 ### Credentials
 
-| Function                           | Description                                               | Request Context |
-| ---------------------------------- | --------------------------------------------------------- | :-------------: |
-| `useSubscribedTenantCredentials()` | Get credentials for all subscribed tenants (cached 10min) |       ❌        |
-| `useDeployedTenantCredentials()`   | Get credentials for the deployed tenant (cached 10 min)   |       ❌        |
-| `useUserTenantCredentials()`       | Get credentials for the current user's tenant             |       ✅        |
+| Function                           | Description                                                        | Request Context |
+| ---------------------------------- | ------------------------------------------------------------------ | :-------------: |
+| `useSubscribedTenantCredentials()` | Get credentials for all subscribed tenants (cached, default 10min) |       ❌        |
+| `useDeployedTenantCredentials()`   | Get credentials for the deployed tenant (cached, default 10min)    |       ❌        |
+| `useUserTenantCredentials()`       | Get credentials for the current user's tenant                      |       ✅        |
 
 > **Note**: `useDeployedTenantCredentials()` shares its cache with `useSubscribedTenantCredentials()`. Both functions support `.invalidate()` and `.refresh()` methods. Invalidating or refreshing one will affect the other.
+>
+> **Cache Duration**: The cache TTL is configurable via the `cache.credentialsTTL` option or `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable. See [Cache Configuration](#cache-configuration) for details.
+
+### Tenant Options
+
+| Function            | Description                                              | Request Context |
+| ------------------- | -------------------------------------------------------- | :-------------: |
+| `useTenantOption()` | Get a tenant option value by key (cached, default 10min) |       ❌        |
+
+Fetch tenant options (settings) configured for your microservice:
+
+```ts
+import { useTenantOption } from 'c8y-nitro/utils'
+
+export default defineHandler(async (event) => {
+  // Fetch a tenant option
+  const value = await useTenantOption('myOption')
+
+  // Fetch an encrypted secret
+  const secret = await useTenantOption('credentials.apiKey')
+
+  // Cache management
+  await useTenantOption.invalidate('myOption') // Invalidate specific key
+  const fresh = await useTenantOption.refresh('myOption') // Force refresh
+  await useTenantOption.invalidateAll() // Invalidate all accessed keys
+  await useTenantOption.refreshAll() // Refresh all accessed keys
+  return { value, secret, fresh }
+})
+```
+
+Define your settings in the manifest to get type-safe keys:
+
+```ts
+export default defineNitroConfig({
+  c8y: {
+    manifest: {
+      settings: [
+        { key: 'myOption', defaultValue: 'default' },
+        { key: 'credentials.secret' }, // Encrypted option
+      ],
+      settingsCategory: 'my-service', // Optional, defaults to contextPath/name
+      requiredRoles: ['ROLE_OPTION_MANAGEMENT_READ'], // Required for reading tenant options
+    },
+  },
+  modules: [c8y()],
+})
+```
+
+> **Important**: To read tenant options, your microservice **must** have the `ROLE_OPTION_MANAGEMENT_READ` role in `manifest.requiredRoles`. Without this role, API calls will fail with a 403 Forbidden error.
+
+> **Note on Encrypted Options**: Keys prefixed with `credentials.` are stored encrypted by Cumulocity. The value is automatically decrypted when fetched if your microservice is the owner of the option (the option's category matches your microservice's `settingsCategory`, `contextPath`, or name). The `credentials.` prefix is automatically stripped when calling the API.
+
+> **Note on Missing Options**: If a tenant option is not set (404 Not Found), `useTenantOption()` returns `undefined` instead of throwing an error. Other errors (e.g., 403 Forbidden) are thrown normally.
 
 ### Resources
 
@@ -299,6 +486,7 @@ async function anotherFunction() {
 | ----------- | ------------------------------------------------------- |
 | `bootstrap` | Manually register microservice and retrieve credentials |
 | `roles`     | Manage development user roles                           |
+| `options`   | Manage tenant options on development tenant             |
 
 For more information, run:
 
@@ -318,10 +506,22 @@ pnpm dev
 # Build for production
 pnpm build
 
-# Run tests
+# Run tests (watch mode)
 pnpm test
+
+# Run tests once
+pnpm test:run
 ```
 
+### Testing
+
+Tests are organized in two categories:
+
+- **Unit tests** (`tests/unit/`) — Test individual functions in isolation
+- **Server tests** (`tests/server/`) — Integration tests that spin up a Nitro dev server with the c8y-nitro module
+
+Server tests use Nitro's virtual modules to mock `@c8y/client` at build time, allowing full integration testing without real Cumulocity API calls. See [AGENTS.md](AGENTS.md#server-integration-tests) for implementation details.
+
 ## License
 
 MIT

package/dist/cli/commands/options.mjs

@@ -0,0 +1,148 @@
+import { createC8yManifest } from "../../module/manifest.mjs";
+import { createBasicAuthHeader, deleteTenantOption, getTenantOption, getTenantOptionsByCategory, updateTenantOption } from "../utils/c8y-api.mjs";
+import { loadC8yConfig, validateBootstrapEnv } from "../utils/config.mjs";
+import { defineCommand } from "citty";
+import { consola } from "consola";
+
+//#region src/cli/commands/options.ts
+var options_default = defineCommand({
+	meta: {
+		name: "options",
+		description: "Manage tenant options on the development tenant"
+	},
+	args: {},
+	async run() {
+		consola.info("Loading configuration...");
+		const { env, c8yOptions, configDir } = await loadC8yConfig();
+		consola.info("Validating environment variables...");
+		const envVars = validateBootstrapEnv(env);
+		consola.info("Loading manifest...");
+		const manifest = await createC8yManifest(configDir, c8yOptions?.manifest);
+		const category = manifest.settingsCategory || manifest.contextPath || manifest.name;
+		if (!manifest.settings || manifest.settings.length === 0) throw new Error("No settings defined in manifest. Add settings to your c8y.manifest configuration.");
+		consola.success(`Using category: ${category}`);
+		const authHeader = createBasicAuthHeader(envVars.C8Y_DEVELOPMENT_TENANT, envVars.C8Y_DEVELOPMENT_USER, envVars.C8Y_DEVELOPMENT_PASSWORD);
+		consola.info("Fetching current tenant options...");
+		const currentOptions = await getTenantOptionsByCategory(envVars.C8Y_BASEURL, category, authHeader);
+		const availableKeys = manifest.settings.map((s) => s.key);
+		consola.success(`Found ${Object.keys(currentOptions).length} options set on tenant`);
+		const action = await consola.prompt("What do you want to do?", {
+			type: "select",
+			options: [
+				{
+					label: "Read option value",
+					value: "read"
+				},
+				{
+					label: "Update/Create option",
+					value: "update"
+				},
+				{
+					label: "Delete option(s)",
+					value: "delete"
+				}
+			]
+		});
+		if (action === "read") await handleRead(envVars.C8Y_BASEURL, category, authHeader, availableKeys, currentOptions);
+		else if (action === "update") await handleUpdate(envVars.C8Y_BASEURL, category, authHeader, availableKeys, currentOptions);
+		else if (action === "delete") await handleDelete(envVars.C8Y_BASEURL, category, authHeader, availableKeys, currentOptions);
+	}
+});
+/**
+* Handle reading a single option
+* @param baseUrl - The Cumulocity base URL
+* @param category - The tenant option category
+* @param authHeader - The Basic Auth header
+* @param availableKeys - List of available option keys
+* @param currentOptions - Current option values from tenant
+*/
+async function handleRead(baseUrl, category, authHeader, availableKeys, currentOptions) {
+	const setKeys = availableKeys.filter((k) => !k.startsWith("credentials.") && currentOptions[k] !== void 0);
+	const credentialsKeys = availableKeys.filter((k) => k.startsWith("credentials."));
+	const allKeys = [...setKeys, ...credentialsKeys];
+	if (allKeys.length === 0) {
+		consola.warn("No options are currently set");
+		return;
+	}
+	const key = await consola.prompt("Select option to read:", {
+		type: "select",
+		options: allKeys.map((k) => ({
+			label: k.startsWith("credentials.") ? `${k} (unknown)` : k,
+			value: k
+		})),
+		cancel: "reject"
+	});
+	consola.info(`Reading option: ${key}`);
+	const value = await getTenantOption(baseUrl, category, key.startsWith("credentials.") ? key.replace(/^credentials\./, "") : key, authHeader);
+	if (value === void 0) consola.warn(`Option '${key}' is not set`);
+	else consola.success(`Value: ${value}`);
+}
+/**
+* Handle updating options (with loop for multiple updates)
+* @param baseUrl - The Cumulocity base URL
+* @param category - The tenant option category
+* @param authHeader - The Basic Auth header
+* @param availableKeys - List of available option keys
+* @param currentOptions - Current option values from tenant
+*/
+async function handleUpdate(baseUrl, category, authHeader, availableKeys, currentOptions) {
+	let continueUpdating = true;
+	while (continueUpdating) {
+		const key = await consola.prompt("Select option to update:", {
+			type: "select",
+			options: availableKeys.map((k) => ({
+				label: currentOptions[k] !== void 0 ? `${k} (current: ${currentOptions[k]})` : k.startsWith("credentials.") ? `${k} (current: unknown)` : `${k} (not set)`,
+				value: k
+			})),
+			cancel: "reject"
+		});
+		const currentValue = currentOptions[key];
+		const newValue = await consola.prompt("Enter new value:", {
+			type: "text",
+			default: currentValue,
+			cancel: "reject"
+		});
+		consola.info(`Updating option: ${key}`);
+		await updateTenantOption(baseUrl, category, key.replace(/^credentials\./, ""), newValue, authHeader);
+		currentOptions[key] = newValue;
+		consola.success(`Option '${key}' updated successfully`);
+		if (!await consola.prompt("Update another option?", {
+			type: "confirm",
+			initial: false,
+			cancel: "reject"
+		})) continueUpdating = false;
+	}
+}
+/**
+* Handle deleting multiple options
+* @param baseUrl - The Cumulocity base URL
+* @param category - The tenant option category
+* @param authHeader - The Basic Auth header
+* @param availableKeys - List of available option keys
+* @param currentOptions - Current option values from tenant
+*/
+async function handleDelete(baseUrl, category, authHeader, availableKeys, currentOptions) {
+	const setKeys = availableKeys.filter((k) => !k.startsWith("credentials.") && currentOptions[k] !== void 0);
+	const credentialsKeys = availableKeys.filter((k) => k.startsWith("credentials."));
+	const allKeys = [...setKeys, ...credentialsKeys];
+	if (allKeys.length === 0) {
+		consola.warn("No options are currently set");
+		return;
+	}
+	const keysToDelete = await consola.prompt("Select option(s) to delete:", {
+		type: "multiselect",
+		options: allKeys,
+		required: true,
+		cancel: "reject"
+	});
+	consola.info(`Deleting ${keysToDelete.length} option(s)...`);
+	for (const key of keysToDelete) {
+		consola.info(`Deleting option: ${key}`);
+		await deleteTenantOption(baseUrl, category, key.startsWith("credentials.") ? key.replace(/^credentials\./, "") : key, authHeader);
+		consola.success(`✓ Deleted: ${key}`);
+	}
+	consola.success("Delete operation completed");
+}
+
+//#endregion
+export { options_default as default };

package/dist/cli/index.mjs

@@ -10,7 +10,8 @@ runMain(defineCommand({
 	},
 	subCommands: {
 		bootstrap: () => import("./commands/bootstrap.mjs").then((r) => r.default),
-		roles: () => import("./commands/roles.mjs").then((r) => r.default)
+		roles: () => import("./commands/roles.mjs").then((r) => r.default),
+		options: () => import("./commands/options.mjs").then((r) => r.default)
 	}
 }));
 

package/dist/cli/utils/c8y-api.mjs

@@ -167,6 +167,96 @@ async function unassignUserRole(baseUrl, tenantId, userId, roleId, authHeader) {
 		throw new Error(`Failed to unassign role ${roleId}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
 	}
 }
+/**
+* Gets all tenant options for a specific category.
+* @param baseUrl - The Cumulocity base URL
+* @param category - The category to fetch options for
+* @param authHeader - The Basic Auth header
+* @returns Record of key-value pairs for the category
+*/
+async function getTenantOptionsByCategory(baseUrl, category, authHeader) {
+	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}`;
+	const response = await fetch(url, {
+		method: "GET",
+		headers: {
+			Authorization: authHeader,
+			Accept: "application/json"
+		}
+	});
+	if (response.status === 404) return {};
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Failed to get tenant options for category ${category}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+	}
+	return await response.json();
+}
+/**
+* Gets a specific tenant option value.
+* @param baseUrl - The Cumulocity base URL
+* @param category - The category of the option
+* @param key - The option key
+* @param authHeader - The Basic Auth header
+* @returns The option value, or undefined if not set
+*/
+async function getTenantOption(baseUrl, category, key, authHeader) {
+	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}/${encodeURIComponent(key)}`;
+	const response = await fetch(url, {
+		method: "GET",
+		headers: {
+			Authorization: authHeader,
+			Accept: "application/json"
+		}
+	});
+	if (response.status === 404) return;
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Failed to get tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+	}
+	return (await response.json()).value;
+}
+/**
+* Updates or creates a tenant option.
+* @param baseUrl - The Cumulocity base URL
+* @param category - The category of the option
+* @param key - The option key
+* @param value - The new value to set
+* @param authHeader - The Basic Auth header
+*/
+async function updateTenantOption(baseUrl, category, key, value, authHeader) {
+	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}/${encodeURIComponent(key)}`;
+	const response = await fetch(url, {
+		method: "PUT",
+		headers: {
+			"Authorization": authHeader,
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({ value })
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Failed to update tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+	}
+}
+/**
+* Deletes a tenant option.
+* @param baseUrl - The Cumulocity base URL
+* @param category - The category of the option
+* @param key - The option key to delete
+* @param authHeader - The Basic Auth header
+*/
+async function deleteTenantOption(baseUrl, category, key, authHeader) {
+	const url = `${baseUrl}/tenant/options/${encodeURIComponent(category)}/${encodeURIComponent(key)}`;
+	const response = await fetch(url, {
+		method: "DELETE",
+		headers: { Authorization: authHeader }
+	});
+	if (response.status === 404) return;
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Failed to delete tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+	}
+}
 
 //#endregion
-export { assignUserRole, createBasicAuthHeader, createMicroservice, findMicroserviceByName, getBootstrapCredentials, subscribeToApplication, unassignUserRole, updateMicroservice };
+export { assignUserRole, createBasicAuthHeader, createMicroservice, deleteTenantOption, findMicroserviceByName, getBootstrapCredentials, getTenantOption, getTenantOptionsByCategory, subscribeToApplication, unassignUserRole, updateMicroservice, updateTenantOption };

package/dist/index.mjs

@@ -1,10 +1,13 @@
+import { createC8yManifestFromNitro } from "./module/manifest.mjs";
 import { writeAPIClient } from "./module/apiClient.mjs";
 import { createC8yZip } from "./module/c8yzip.mjs";
 import { setupRuntime } from "./module/runtime.mjs";
+import { setupRuntimeConfig } from "./module/runtimeConfig.mjs";
 import { registerRuntime } from "./module/register.mjs";
 import { checkProbes } from "./module/probeCheck.mjs";
 import { autoBootstrap } from "./module/autoBootstrap.mjs";
 import { name } from "./package.mjs";
+import evlog from "evlog/nitro/v3";
 
 //#region src/index.ts
 function c8y() {
@@ -16,8 +19,8 @@ function c8y() {
 			nitro.options.typescript.tsConfig = {};
 			nitro.options.typescript.tsConfig.include = ["./**/*.d.ts"];
 			nitro.options.typescript.tsConfig.exclude = [];
-			nitro.options.noExternals = nitro.options.noExternals && nitro.options.noExternals === true ? nitro.options.noExternals : [
-				...nitro.options.noExternals || [],
+			nitro.options.noExternals = nitro.options.noExternals === true ? true : [
+				...Array.isArray(nitro.options.noExternals) ? nitro.options.noExternals : [],
 				name,
 				"@c8y/client"
 			];
@@ -25,7 +28,10 @@ function c8y() {
 				nitro.logger.error(`Unsupported preset "${nitro.options.preset}" for c8y-nitro module, only node presets are supported.`);
 				throw new Error("Unsupported preset for c8y-nitro module");
 			}
-			await autoBootstrap(nitro);
+			const { setup: setupEvlog } = evlog({ env: { service: (await createC8yManifestFromNitro(nitro)).name } });
+			await setupEvlog(nitro);
+			if (!options.skipBootstrap) await autoBootstrap(nitro);
+			await setupRuntimeConfig(nitro, options);
 			setupRuntime(nitro, options.manifest);
 			nitro.hooks.hook("dev:reload", async () => {
 				setupRuntime(nitro, options.manifest);
@@ -50,7 +56,6 @@ function c8y() {
 		}
 	};
 }
-var src_default = c8y;
 
 //#endregion
-export { c8y, src_default as default };
+export { c8y, c8y as default };

package/dist/module/manifest.mjs

@@ -47,9 +47,9 @@ async function createC8yManifest(rootDir, options = {}, logger) {
 	const key = `${name}-key`;
 	const manifest = {
 		...restManifestFields,
-		provider,
 		...probeFields,
 		...options,
+		provider,
 		name,
 		version,
 		apiVersion: "v2",

package/dist/module/runtime.mjs

@@ -5,26 +5,33 @@ import { mkdirSync, writeFileSync } from "fs";
 function setupRuntime(nitro, manifestOptions = {}) {
 	nitro.logger.debug("Setting up C8Y nitro runtime");
 	const roles = manifestOptions.roles ?? [];
+	const settingKeys = (manifestOptions.settings ?? []).map((s) => s.key);
 	const completeTypesDir = join(nitro.options.rootDir, nitro.options.typescript.generatedTypesDir ?? "node_modules/.nitro/types");
-	const rolesTypeFile = join(completeTypesDir, "c8y-nitro-roles.d.ts");
-	const rolesTypeContent = `// generated by c8y-nitro
+	const typesFile = join(completeTypesDir, "c8y-nitro.d.ts");
+	const typesContent = `// generated by c8y-nitro
 declare module 'c8y-nitro/types' {
   interface C8YRoles {
 ${roles.map((role) => `    '${role}': '${role}';`).join("\n")}
   }
+  type C8YTenantOptionKey = ${settingKeys.length > 0 ? `${settingKeys.map((k) => `'${k}'`).join(" | ")}` : "never"}
+  type C8YTenantOptionKeysCacheConfig = Partial<Record<C8YTenantOptionKey, number>>;
 }
+
 declare module 'c8y-nitro/runtime' {
   import type { C8YRoles } from 'c8y-nitro/types';
   export const c8yRoles: C8YRoles;
+  export const c8yTenantOptionKeys: readonly [${settingKeys.map((key) => `'${key}'`).join(", ")}];
 }`;
 	nitro.options.virtual["c8y-nitro/runtime"] = `
 export const c8yRoles = {
 ${roles.map((role) => `  '${role}': '${role}',`).join("\n")}
 }
+
+export const c8yTenantOptionKeys = [${settingKeys.map((key) => `'${key}'`).join(", ")}]
 `;
 	mkdirSync(completeTypesDir, { recursive: true });
-	writeFileSync(rolesTypeFile, rolesTypeContent, { encoding: "utf-8" });
-	nitro.logger.debug(`Written C8Y roles types to ${rolesTypeFile}`);
+	writeFileSync(typesFile, typesContent, { encoding: "utf-8" });
+	nitro.logger.debug(`Written C8Y types to ${typesFile}`);
 }
 
 //#endregion

package/dist/module/runtimeConfig.mjs

@@ -0,0 +1,20 @@
+import { createC8yManifest } from "./manifest.mjs";
+
+//#region src/module/runtimeConfig.ts
+/**
+* Sets up runtime configuration values from module options.
+* These can be overridden by environment variables.
+* @param nitro - The Nitro instance
+* @param options - The c8y-nitro module options
+*/
+async function setupRuntimeConfig(nitro, options) {
+	nitro.logger.debug("Setting up C8Y runtime config");
+	nitro.options.runtimeConfig.c8yCredentialsCacheTTL = options.cache?.credentialsTTL ?? 600;
+	nitro.options.runtimeConfig.c8yDefaultTenantOptionsTTL = options.cache?.defaultTenantOptionsTTL ?? 600;
+	nitro.options.runtimeConfig.c8yTenantOptionsPerKeyTTL = options.cache?.tenantOptions ?? {};
+	const manifest = await createC8yManifest(nitro.options.rootDir, options.manifest, nitro.logger);
+	nitro.options.runtimeConfig.c8ySettingsCategory = options.manifest?.settingsCategory ?? manifest.contextPath ?? manifest.name;
+}
+
+//#endregion
+export { setupRuntimeConfig };

package/dist/package.mjs

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "c8y-nitro";
-var version = "0.1.2";
+var version = "0.3.0";
 var description = "Lightning fast Cumulocity IoT microservice development powered by Nitro";
 
 //#endregion

package/dist/types/cache.d.mts

@@ -0,0 +1,28 @@
+import { C8YTenantOptionKeysCacheConfig } from "c8y-nitro/types";
+
+//#region src/types/cache.d.ts
+interface C8yCacheOptions {
+  /**
+   * Cache TTL for subscribed tenant credentials in seconds.
+   * @default 600 (10 minutes)
+   */
+  credentialsTTL?: number;
+  /**
+   * Default cache TTL for tenant options in seconds.
+   * Applied to all keys unless overridden in `tenantOptions`.
+   * @default 600 (10 minutes)
+   */
+  defaultTenantOptionsTTL?: number;
+  /**
+   * Per-key cache TTL overrides for tenant options in seconds.
+   * Keys should match those defined in `manifest.settings[].key`.
+   * @example
+   * {
+   *   'myOption': 300,           // 5 minutes
+   *   'credentials.secret': 60,  // 1 minute
+   * }
+   */
+  tenantOptions?: C8YTenantOptionKeysCacheConfig;
+}
+//#endregion
+export { C8yCacheOptions };

package/dist/types/manifest.d.mts

@@ -1,5 +1,5 @@
 //#region src/types/manifest.d.ts
-type C8YManifestOptions = Partial<Omit<C8YManifest, 'name' | 'version' | 'apiVersion' | 'key'>>;
+type C8YManifestOptions = Omit<C8YManifest, 'name' | 'version' | 'apiVersion' | 'key' | 'type' | 'provider'>;
 interface C8YManifest {
   /**
    * API version (e.g., "v2", "2"). Version 2 required for enhanced container security.
@@ -253,10 +253,6 @@ interface ExecAction {
  * TCP socket probe.
  */
 interface TCPSocketAction {
-  /**
-   * Hostname or IP to connect to.
-   */
-  host: string;
   /**
    * Port number to connect to.
    * @default 80
@@ -267,10 +263,6 @@ interface TCPSocketAction {
  * HTTP GET probe.
  */
 interface HTTPGetAction {
-  /**
-   * Hostname to connect to.
-   */
-  host?: string;
   /**
    * URL path to request.
    * @example "/health"

package/dist/types/tenantOptions.d.mts

@@ -0,0 +1,13 @@
+//#region src/types/tenantOptions.d.ts
+/**
+ * Per-key cache TTL configuration for tenant options.
+ * Overwritten by generated types from manifest settings (manifest.settings[].key).
+ */
+type C8YTenantOptionKeysCacheConfig = Partial<Record<C8YTenantOptionKey, number>>;
+/**
+ * Type for tenant option keys.
+ * Overwritten by generated types from manifest settings (manifest.settings[].key).
+ */
+type C8YTenantOptionKey = string;
+//#endregion
+export { C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig };

package/dist/types.d.mts

@@ -1,13 +1,25 @@
 import { C8YAPIClientOptions } from "./types/apiClient.mjs";
 import { C8YManifestOptions } from "./types/manifest.mjs";
 import { C8YZipOptions } from "./types/zip.mjs";
+import { C8yCacheOptions } from "./types/cache.mjs";
 import { C8YRoles } from "./types/roles.mjs";
+import { C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig } from "./types/tenantOptions.mjs";
 
 //#region src/types/index.d.ts
 interface C8yNitroModuleOptions {
   manifest?: C8YManifestOptions;
   apiClient?: C8YAPIClientOptions;
   zip?: C8YZipOptions;
+  cache?: C8yCacheOptions;
+  /**
+   * Disable auto-bootstrap during development.
+   * When true, the module will not automatically register the microservice
+   * or retrieve bootstrap credentials on startup.
+   *
+   * Useful for CI/CD pipelines or manual bootstrap management.
+   * @default false
+   */
+  skipBootstrap?: boolean;
 }
 //#endregion
-export { C8YAPIClientOptions, type C8YManifestOptions, C8YRoles, C8YZipOptions, C8yNitroModuleOptions };
+export { C8YAPIClientOptions, type C8YManifestOptions, C8YRoles, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, C8YZipOptions, type C8yCacheOptions, C8yNitroModuleOptions };

package/dist/utils/credentials.d.mts

@@ -6,8 +6,11 @@ import { ServerRequest } from "nitro/types";
 /**
  * Fetches credentials for all tenants subscribed to this microservice.\
  * Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
- * Results are cached for 10 minutes.\
+ * 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_CACHE_CREDENTIALS_TTL` environment variable
  * @example
  * // Get all subscribed tenant credentials:
  * const credentials = await useSubscribedTenantCredentials()
@@ -29,7 +32,7 @@ declare const useSubscribedTenantCredentials: (() => Promise<Record<string, ICre
 /**
  * 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 for 10 minutes).
+ * 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
  * @example

package/dist/utils/credentials.mjs

@@ -4,13 +4,17 @@ import { Client } from "@c8y/client";
 import { defineCachedFunction } from "nitro/cache";
 import { HTTPError } from "nitro/h3";
 import { useStorage } from "nitro/storage";
+import { useRuntimeConfig } from "nitro/runtime-config";
 
 //#region src/utils/credentials.ts
 /**
 * Fetches credentials for all tenants subscribed to this microservice.\
 * Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
-* Results are cached for 10 minutes.\
+* 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_CACHE_CREDENTIALS_TTL` environment variable
 * @example
 * // Get all subscribed tenant credentials:
 * const credentials = await useSubscribedTenantCredentials()
@@ -35,7 +39,7 @@ const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async
 		return acc;
 	}, {});
 }, {
-	maxAge: 600,
+	maxAge: useRuntimeConfig().c8yCredentialsCacheTTL ?? 600,
 	name: "_c8y_nitro_get_subscribed_tenant_credentials",
 	group: "c8y_nitro",
 	swr: false
@@ -51,7 +55,7 @@ const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async
 /**
 * 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 for 10 minutes).
+* 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
 * @example

package/dist/utils/logging.d.mts

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

package/dist/utils/logging.mjs

@@ -0,0 +1,4 @@
+import { useLogger } from "evlog/nitro/v3";
+import { createError, createLogger } from "evlog";
+
+export { createError, createLogger, useLogger };

package/dist/utils/tenantOptions.d.mts

@@ -0,0 +1,65 @@
+import { C8YTenantOptionKey } from "c8y-nitro/types";
+
+//#region src/utils/tenantOptions.d.ts
+/**
+ * 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).
+ *
+ * @param key - The tenant option key to fetch (as defined in `manifest.settings`)
+ * @returns The option value as a string
+ *
+ * @config Cache TTL can be configured via:
+ * - `c8y.cache.defaultTenantOptionsTTL` — Default TTL for all keys (in seconds)
+ * - `c8y.cache.tenantOptions` — Per-key TTL overrides
+ * - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
+ *
+ * @note For encrypted options (keys starting with `credentials.`), the value is automatically
+ * decrypted by Cumulocity if this microservice is the owner of the option (category matches
+ * the microservice's settingsCategory/contextPath/name). The `credentials.` prefix is
+ * automatically stripped when calling the API.
+ *
+ * @example
+ * // Fetch a tenant option:
+ * const value = await useTenantOption('myOption')
+ *
+ * // Fetch an encrypted secret:
+ * const secret = await useTenantOption('credentials.apiKey')
+ *
+ * // Invalidate cache for a specific key:
+ * await useTenantOption.invalidate('myOption')
+ *
+ * // Force refresh a specific key:
+ * const fresh = await useTenantOption.refresh('myOption')
+ *
+ * // Invalidate all tenant option caches:
+ * await useTenantOption.invalidateAll()
+ *
+ * // Refresh all tenant options:
+ * const all = await useTenantOption.refreshAll()
+ */
+declare const useTenantOption: ((key: C8YTenantOptionKey) => Promise<string | undefined>) & {
+  /**
+   * Invalidate the cache for a specific tenant option key.
+   * @param key - The tenant option key to invalidate
+   */
+  invalidate: (key: C8YTenantOptionKey) => Promise<void>;
+  /**
+   * Force refresh a specific tenant option key (invalidates and re-fetches).
+   * @param key - The tenant option key to refresh
+   */
+  refresh: (key: C8YTenantOptionKey) => Promise<string | undefined>;
+  /**
+   * Invalidate all tenant option caches that have been accessed.
+   * Only invalidates keys that have been fetched at least once.
+   */
+  invalidateAll: () => Promise<void>;
+  /**
+   * 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: () => Promise<Record<string, string | undefined>>;
+};
+//#endregion
+export { useTenantOption };

package/dist/utils/tenantOptions.mjs

@@ -0,0 +1,127 @@
+import { useDeployedTenantClient } from "./client.mjs";
+import { defineCachedFunction } from "nitro/cache";
+import { useStorage } from "nitro/storage";
+import { useRuntimeConfig } from "nitro/runtime-config";
+
+//#region src/utils/tenantOptions.ts
+/**
+* Gets the cache TTL for a specific tenant option key.
+* Uses per-key override if defined, otherwise falls back to default TTL.
+* @param key - The tenant option key
+*/
+function getTenantOptionCacheTTL(key) {
+	const config = useRuntimeConfig();
+	return config.c8yTenantOptionsPerKeyTTL?.[key] ?? config.c8yDefaultTenantOptionsTTL ?? 600;
+}
+/**
+* Internal storage for cached functions per key
+*/
+const tenantOptionFetchers = {};
+/**
+* Factory function that creates a cached fetcher for a specific tenant option key.
+* @param key - The tenant option key
+*/
+function createCachedTenantOptionFetcher(key) {
+	const cacheName = `_c8y_nitro_tenant_option_${key.replace(/\./g, "_")}`;
+	const fetcher = defineCachedFunction(async () => {
+		const client = await useDeployedTenantClient();
+		const category = useRuntimeConfig().c8ySettingsCategory;
+		const apiKey = key.replace(/^credentials\./, "");
+		try {
+			return (await client.options.tenant.detail({
+				key: apiKey,
+				category
+			})).data.value;
+		} catch (error) {
+			if (error?.res?.status === 404 || error?.status === 404) return;
+			throw error;
+		}
+	}, {
+		maxAge: getTenantOptionCacheTTL(key),
+		name: cacheName,
+		group: "c8y_nitro",
+		swr: false
+	});
+	return Object.assign(fetcher, {
+		invalidate: async () => {
+			const completeKey = `c8y_nitro:functions:${cacheName}.json`;
+			await useStorage("cache").removeItem(completeKey);
+		},
+		refresh: async () => {
+			const completeKey = `c8y_nitro:functions:${cacheName}.json`;
+			await useStorage("cache").removeItem(completeKey);
+			return await fetcher();
+		}
+	});
+}
+/**
+* Gets or creates a cached fetcher for a specific tenant option key.
+* @param key - The tenant option key
+*/
+function getOrCreateFetcher(key) {
+	let fetcher = tenantOptionFetchers[key];
+	if (!fetcher) {
+		fetcher = createCachedTenantOptionFetcher(key);
+		tenantOptionFetchers[key] = 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).
+*
+* @param key - The tenant option key to fetch (as defined in `manifest.settings`)
+* @returns The option value as a string
+*
+* @config Cache TTL can be configured via:
+* - `c8y.cache.defaultTenantOptionsTTL` — Default TTL for all keys (in seconds)
+* - `c8y.cache.tenantOptions` — Per-key TTL overrides
+* - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
+*
+* @note For encrypted options (keys starting with `credentials.`), the value is automatically
+* decrypted by Cumulocity if this microservice is the owner of the option (category matches
+* the microservice's settingsCategory/contextPath/name). The `credentials.` prefix is
+* automatically stripped when calling the API.
+*
+* @example
+* // Fetch a tenant option:
+* const value = await useTenantOption('myOption')
+*
+* // Fetch an encrypted secret:
+* const secret = await useTenantOption('credentials.apiKey')
+*
+* // Invalidate cache for a specific key:
+* await useTenantOption.invalidate('myOption')
+*
+* // Force refresh a specific key:
+* const fresh = await useTenantOption.refresh('myOption')
+*
+* // Invalidate all tenant option caches:
+* await useTenantOption.invalidateAll()
+*
+* // Refresh all tenant options:
+* const all = await useTenantOption.refreshAll()
+*/
+const useTenantOption = Object.assign(async (key) => {
+	return await getOrCreateFetcher(key)();
+}, {
+	invalidate: async (key) => {
+		const fetcher = tenantOptionFetchers[key];
+		if (fetcher) await fetcher.invalidate();
+	},
+	refresh: async (key) => {
+		return await getOrCreateFetcher(key).refresh();
+	},
+	invalidateAll: async () => {
+		await Promise.all(Object.values(tenantOptionFetchers).map((fetcher) => fetcher?.invalidate()));
+	},
+	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]]));
+	}
+});
+
+//#endregion
+export { useTenantOption };

package/dist/utils.d.mts

@@ -2,4 +2,6 @@ import { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, use
 import { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant } from "./utils/middleware.mjs";
 import { useUser, useUserRoles } from "./utils/resources.mjs";
 import { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials } from "./utils/credentials.mjs";
-export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useSubscribedTenantClients, useSubscribedTenantCredentials, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+import { useTenantOption } from "./utils/tenantOptions.mjs";
+import { createError, createLogger, useLogger } from "./utils/logging.mjs";
+export { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/dist/utils.mjs

@@ -2,5 +2,7 @@ import { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTe
 import { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, useUserTenantClient } from "./utils/client.mjs";
 import { useUser, useUserRoles } from "./utils/resources.mjs";
 import { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant } from "./utils/middleware.mjs";
+import { useTenantOption } from "./utils/tenantOptions.mjs";
+import { createError, createLogger, useLogger } from "./utils/logging.mjs";
 
-export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useSubscribedTenantClients, useSubscribedTenantCredentials, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+export { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8y-nitro",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -48,9 +48,10 @@
     "dist"
   ],
   "dependencies": {
-    "c12": "^3.3.3",
+    "c12": "^4.0.0-beta.2",
     "citty": "^0.2.0",
     "consola": "^3.4.2",
+    "evlog": "^2.1.0",
     "jszip": "^3.10.1",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
@@ -58,12 +59,12 @@
     "tinyexec": "^1.0.2"
   },
   "devDependencies": {
-    "@schplitt/eslint-config": "^1.2.0",
+    "@schplitt/eslint-config": "^1.3.1",
     "@types/spinnies": "^0.5.3",
-    "bumpp": "^10.4.0",
-    "eslint": "^9.39.2",
+    "bumpp": "^10.4.1",
+    "eslint": "^10.0.0",
     "memfs": "^4.56.10",
-    "tsdown": "^0.20.1",
+    "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
@@ -82,6 +83,7 @@
     "typecheck": "tsc --noEmit",
     "prerelease": "eslint && tsc --noEmit && tsdown && vitest run",
     "release": "bumpp",
-    "test": "vitest"
+    "test": "vitest",
+    "test:run": "vitest run"
   }
 }