c8y-nitro 0.2.0 → 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:
@@ -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/index.mjs

@@ -1,3 +1,4 @@
+import { createC8yManifestFromNitro } from "./module/manifest.mjs";
 import { writeAPIClient } from "./module/apiClient.mjs";
 import { createC8yZip } from "./module/c8yzip.mjs";
 import { setupRuntime } from "./module/runtime.mjs";
@@ -6,6 +7,7 @@ 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() {
@@ -17,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"
 			];
@@ -26,7 +28,9 @@ 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 () => {
@@ -52,7 +56,6 @@ function c8y() {
 		}
 	};
 }
-var src_default = c8y;
 
 //#endregion
-export { c8y, src_default as default };
+export { c8y, c8y as default };

package/dist/package.mjs

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

package/dist/types.d.mts

@@ -11,6 +11,15 @@ interface C8yNitroModuleOptions {
   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, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, C8YZipOptions, type C8yCacheOptions, C8yNitroModuleOptions };

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.d.mts

@@ -3,4 +3,5 @@ import { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant
 import { useUser, useUserRoles } from "./utils/resources.mjs";
 import { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials } from "./utils/credentials.mjs";
 import { useTenantOption } from "./utils/tenantOptions.mjs";
-export { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+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

@@ -3,5 +3,6 @@ import { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, use
 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, useTenantOption, 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.2.0",
+  "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"
   },