c8y-nitro 0.2.0 → 0.4.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:
@@ -241,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.
@@ -401,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/bootstrap-CGOe2HxK.mjs

@@ -0,0 +1,61 @@
+import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BBSKRwKs.mjs";
+import { t as writeBootstrapCredentials } from "./env-file-B0BK-uZW.mjs";
+import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-Dqi-ttQi.mjs";
+import { defineCommand, runCommand } from "citty";
+import { consola as consola$1 } from "consola";
+//#region src/cli/commands/bootstrap.ts
+var bootstrap_default = defineCommand({
+	meta: {
+		name: "bootstrap",
+		description: "Bootstrap your microservice to the development tenant"
+	},
+	args: {},
+	async run() {
+		consola$1.info("Loading configuration...");
+		const { env, c8yOptions, configDir } = await loadC8yConfig();
+		consola$1.info("Validating environment variables...");
+		const envVars = validateBootstrapEnv(env);
+		consola$1.info("Building manifest...");
+		const manifest = await createC8yManifest(configDir, c8yOptions?.manifest);
+		consola$1.success(`Manifest created for: ${manifest.name} v${manifest.version}`);
+		const authHeader = createBasicAuthHeader(envVars.C8Y_DEVELOPMENT_TENANT, envVars.C8Y_DEVELOPMENT_USER, envVars.C8Y_DEVELOPMENT_PASSWORD);
+		consola$1.info(`Checking if microservice "${manifest.name}" exists...`);
+		const existingApp = await findMicroserviceByName(envVars.C8Y_BASEURL, manifest.name, authHeader);
+		let appId;
+		if (existingApp) {
+			consola$1.warn(`Microservice "${manifest.name}" already exists on development tenant (ID: ${existingApp.id})`);
+			if (!await consola$1.prompt("Do you want to update the existing microservice?", {
+				type: "confirm",
+				cancel: "reject"
+			})) {
+				consola$1.info("Bootstrap cancelled.");
+				return;
+			}
+			consola$1.info("Updating microservice...");
+			appId = (await updateMicroservice(envVars.C8Y_BASEURL, existingApp.id, manifest, authHeader)).id;
+			consola$1.success(`Microservice updated successfully (ID: ${appId})`);
+		} else {
+			consola$1.info("Creating microservice...");
+			appId = (await createMicroservice(envVars.C8Y_BASEURL, manifest, authHeader)).id;
+			consola$1.success(`Microservice created successfully (ID: ${appId})`);
+		}
+		consola$1.info("Subscribing tenant to application...");
+		await subscribeToApplication(envVars.C8Y_BASEURL, envVars.C8Y_DEVELOPMENT_TENANT, appId, authHeader);
+		consola$1.success("Tenant subscribed to application");
+		consola$1.info("Fetching bootstrap credentials...");
+		const credentials = await getBootstrapCredentials(envVars.C8Y_BASEURL, appId, authHeader);
+		consola$1.info("Writing bootstrap credentials...");
+		const envFileName = await writeBootstrapCredentials(configDir, {
+			C8Y_BOOTSTRAP_TENANT: credentials.tenant,
+			C8Y_BOOTSTRAP_USER: credentials.name,
+			C8Y_BOOTSTRAP_PASSWORD: credentials.password
+		});
+		consola$1.success(`Bootstrap credentials written to ${envFileName}`);
+		if (manifest.roles && manifest.roles.length > 0) {
+			if (await consola$1.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-DrJsxUG-.mjs").then((r) => r.default), { rawArgs: [] });
+		}
+		consola$1.success("Bootstrap complete!");
+	}
+});
+//#endregion
+export { bootstrap_default as default };

package/dist/{cli/utils/c8y-api.mjs → c8y-api-BBSKRwKs.mjs}

@@ -1,5 +1,76 @@
+import { readPackage } from "pkg-types";
 import { Buffer } from "node:buffer";
-
+//#region src/module/constants.ts
+const GENERATED_LIVENESS_ROUTE = "/_c8y_nitro/liveness";
+const GENERATED_READINESS_ROUTE = "/_c8y_nitro/readiness";
+//#endregion
+//#region src/module/manifest.ts
+async function readPackageJsonFieldsForManifest(rootDir, logger) {
+	logger?.debug(`Reading package file from ${rootDir}`);
+	const pkg = await readPackage(rootDir);
+	const name = pkg.name?.replace(/^@[^/]+\//, "");
+	const version = pkg.version;
+	const author = pkg.author;
+	const authorName = typeof author === "string" ? author : author?.name;
+	const authorEmail = typeof author === "string" ? void 0 : author?.email;
+	const authorUrl = typeof author === "string" ? void 0 : author?.url;
+	if (!name || !version || !authorName) throw new Error("package.json must contain name, version, and author name fields");
+	const support = typeof pkg.bugs === "string" ? pkg.bugs : pkg.bugs?.url ?? pkg.bugs?.email;
+	const provider = {
+		name: authorName ?? name,
+		domain: authorUrl ?? pkg.homepage,
+		support: support ?? authorEmail
+	};
+	logger?.debug(`Found package.json fields for manifest: name=${name}, version=${version}, provider=${JSON.stringify(provider)}`);
+	return {
+		name,
+		version,
+		provider,
+		contextPath: name
+	};
+}
+/**
+* Creates a Cumulocity manifest from rootDir and options.
+* Standalone function that can be used by CLI or module.
+* @param rootDir - Directory containing package.json
+* @param options - Manifest options
+* @param logger - Optional logger for debug output
+*/
+async function createC8yManifest(rootDir, options = {}, logger) {
+	const { name, version, provider, ...restManifestFields } = await readPackageJsonFieldsForManifest(rootDir, logger);
+	const probeFields = {};
+	if (!options.livenessProbe?.httpGet) probeFields.livenessProbe = {
+		...options.livenessProbe,
+		httpGet: { path: GENERATED_LIVENESS_ROUTE }
+	};
+	if (!options.readinessProbe?.httpGet) probeFields.readinessProbe = {
+		...options.readinessProbe,
+		httpGet: { path: GENERATED_READINESS_ROUTE }
+	};
+	const key = `${name}-key`;
+	const manifest = {
+		...restManifestFields,
+		...probeFields,
+		...options,
+		provider,
+		name,
+		version,
+		apiVersion: "v2",
+		key,
+		type: "MICROSERVICE"
+	};
+	logger?.debug(`Created Cumulocity manifest: ${JSON.stringify(manifest, null, 2)}`);
+	return manifest;
+}
+/**
+* Creates a Cumulocity manifest from a Nitro instance.
+* Convenience wrapper for use in the Nitro module.
+* @param nitro - The Nitro instance
+*/
+async function createC8yManifestFromNitro(nitro) {
+	return createC8yManifest(nitro.options.rootDir, nitro.options.c8y?.manifest, nitro.logger);
+}
+//#endregion
 //#region src/cli/utils/c8y-api.ts
 /**
 * Creates a Basic Auth header for Cumulocity API requests.
@@ -257,6 +328,5 @@ async function deleteTenantOption(baseUrl, category, key, authHeader) {
 		throw new Error(`Failed to delete tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
 	}
 }
-
 //#endregion
-export { assignUserRole, createBasicAuthHeader, createMicroservice, deleteTenantOption, findMicroserviceByName, getBootstrapCredentials, getTenantOption, getTenantOptionsByCategory, subscribeToApplication, unassignUserRole, updateMicroservice, updateTenantOption };
+export { findMicroserviceByName as a, getTenantOptionsByCategory as c, updateMicroservice as d, updateTenantOption as f, GENERATED_READINESS_ROUTE as g, GENERATED_LIVENESS_ROUTE as h, deleteTenantOption as i, subscribeToApplication as l, createC8yManifestFromNitro as m, createBasicAuthHeader as n, getBootstrapCredentials as o, createC8yManifest as p, createMicroservice as r, getTenantOption as s, assignUserRole as t, unassignUserRole as u };

package/dist/cli/index.mjs

@@ -1,6 +1,5 @@
-import { description, name, version } from "../package.mjs";
+import { n as name, r as version, t as description } from "../package-BAjMvZYS.mjs";
 import { defineCommand, runMain } from "citty";
-
 //#region src/cli/index.ts
 runMain(defineCommand({
 	meta: {
@@ -9,11 +8,10 @@ runMain(defineCommand({
 		description
 	},
 	subCommands: {
-		bootstrap: () => import("./commands/bootstrap.mjs").then((r) => r.default),
-		roles: () => import("./commands/roles.mjs").then((r) => r.default),
-		options: () => import("./commands/options.mjs").then((r) => r.default)
+		bootstrap: () => import("../bootstrap-CGOe2HxK.mjs").then((r) => r.default),
+		roles: () => import("../roles-DrJsxUG-.mjs").then((r) => r.default),
+		options: () => import("../options-CuGdGP4l.mjs").then((r) => r.default)
 	}
 }));
-
 //#endregion
-export {  };
+export {};

package/dist/{cli/utils/config.mjs → config-Dqi-ttQi.mjs}

@@ -1,7 +1,6 @@
 import { dirname } from "pathe";
 import { loadConfig, loadDotenv } from "c12";
 import process from "process";
-
 //#region src/cli/utils/config.ts
 /**
 * Loads c8y configuration from nitro.config and .env files.
@@ -52,6 +51,5 @@ function validateBootstrapEnv(env) {
 		C8Y_DEVELOPMENT_PASSWORD: env.C8Y_DEVELOPMENT_PASSWORD
 	};
 }
-
 //#endregion
-export { loadC8yConfig, validateBootstrapEnv };
+export { validateBootstrapEnv as n, loadC8yConfig as t };

package/dist/{cli/utils/env-file.mjs → env-file-B0BK-uZW.mjs}

@@ -1,7 +1,6 @@
 import { join } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-
 //#region src/cli/utils/env-file.ts
 /**
 * Writes or updates environment variables in a file.
@@ -56,6 +55,5 @@ async function writeBootstrapCredentials(configDir, variables) {
 	await writeEnvVariables(targetPath, variables);
 	return targetName;
 }
-
 //#endregion
-export { writeBootstrapCredentials };
+export { writeBootstrapCredentials as t };

package/dist/{types/manifest.d.mts → index-B6HtYHU0.d.mts}

@@ -1,3 +1,20 @@
+import { C8YTenantOptionKeysCacheConfig } from "c8y-nitro/types";
+
+//#region src/types/apiClient.d.ts
+interface C8YAPIClientOptions {
+  /**
+   * Relative directory from nitro configuration file to generate the API client into.
+   */
+  dir: string;
+  /**
+   * Service context path for microservice endpoints.\
+   * Defaults to contextPath from manifest (package.json name, with scope stripped).\
+   * Override this if deploying with a different context path.
+   * @example "my-microservice" results in "https://<tenant>.com/service/my-microservice/..."
+   */
+  contextPath?: string;
+}
+//#endregion
 //#region src/types/manifest.d.ts
 type C8YManifestOptions = Omit<C8YManifest, 'name' | 'version' | 'apiVersion' | 'key' | 'type' | 'provider'>;
 interface C8YManifest {
@@ -312,4 +329,80 @@ interface Extension {
   [key: string]: unknown;
 }
 //#endregion
-export { C8YManifestOptions };
+//#region src/types/zip.d.ts
+interface C8YZipOptions {
+  /**
+   * Name of the generated zip file
+   * @default '${packageName}-${version}.zip'
+   */
+  name?: string | ((packageName: string, version: string) => string);
+  /**
+   * Output directory for the generated zip file.\
+   * Relative to the config file.
+   * @default './'
+   */
+  outputDir?: string;
+  /**
+   * Configuration of the "cumulocity.json" manifest file used for the zip.
+   */
+  manifest?: C8YManifestOptions;
+}
+//#endregion
+//#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
+//#region src/types/roles.d.ts
+interface C8YRoles$1 {}
+//#endregion
+//#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$1 = Partial<Record<C8YTenantOptionKey$1, number>>;
+/**
+ * Type for tenant option keys.
+ * Overwritten by generated types from manifest settings (manifest.settings[].key).
+ */
+type C8YTenantOptionKey$1 = string;
+//#endregion
+//#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 { C8yCacheOptions as a, C8YAPIClientOptions as c, C8YRoles$1 as i, C8YTenantOptionKey$1 as n, C8YZipOptions as o, C8YTenantOptionKeysCacheConfig$1 as r, C8YManifestOptions as s, C8yNitroModuleOptions as t };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C8yNitroModuleOptions } from "./types.mjs";
+import { t as C8yNitroModuleOptions } from "./index-B6HtYHU0.mjs";
 import { NitroModule } from "nitro/types";
 
 //#region src/index.d.ts