c8y-nitro 0.4.2 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # c8y-nitro
 
-Lightning fast Cumulocity IoT microservice development powered by [Nitro](https://v3.nitro.build).
+Nitro-powered tooling for building Cumulocity IoT microservices without manually stitching together bootstrap, manifest generation, packaging, and tenant-aware runtime helpers.
 
 ## Features
 
@@ -14,514 +14,37 @@ Lightning fast Cumulocity IoT microservice development powered by [Nitro](https:
 - 🛠️ **TypeScript First** - Full type safety with excellent DX
 - 🔄 **Auto-Bootstrap** - Automatically registers and configures your microservice in development
 
-## Quick Start
+## Quickstart
 
-The fastest way to get started is using the [c8y-nitro-starter](https://github.com/schplitt/c8y-nitro-starter) template:
+Start with the [Quickstart docs](https://schplitt.github.io/c8y-nitro/quickstart).
 
-```sh
-pnpm dlx giget@latest gh:schplitt/c8y-nitro-starter my-microservice
-cd my-microservice
-pnpm install
-```
-
-Configure your development tenant in `.env`:
-
-```sh
-C8Y_BASEURL=https://your-tenant.cumulocity.com
-C8Y_DEVELOPMENT_TENANT=t12345
-C8Y_DEVELOPMENT_USER=your-username
-C8Y_DEVELOPMENT_PASSWORD=your-password
-```
-
-Then start developing:
-
-```sh
-pnpm dev
-```
-
-## Installation
-
-```sh
-pnpm add c8y-nitro nitro@latest
-```
-
-## Usage
-
-Configure your Cumulocity microservice in `nitro.config.ts`:
-
-```ts
-import c8y from 'c8y-nitro'
-
-export default defineNitroConfig({
-  preset: 'node-server', // or "node-cluster", Required!
-  c8y: {
-    // c8y-nitro configuration options go here
-  },
-  modules: [c8y()],
-})
-```
-
-### Prerequisites
-
-`c8y-nitro` requires:
-
-- `preset` - must be a node preset (`node-server` or `node-cluster`)
-
-**Recommended:**
-
-- `builder: 'rolldown'` - for faster build times
-
-**Optional:**
-
-- `experimental.asyncContext: true` - enables using utility functions without passing event/request parameters
-
-## Getting Started
-
-Create a `.env` or `.env.local` file with your development tenant credentials:
-
-```sh
-C8Y_BASEURL=https://your-tenant.cumulocity.com
-C8Y_DEVELOPMENT_TENANT=t12345
-C8Y_DEVELOPMENT_USER=your-username
-C8Y_DEVELOPMENT_PASSWORD=your-password
-```
-
-Then simply run `pnpm dev` - that's it! The module will automatically:
-
-1. Check if the microservice exists on the tenant
-2. Create it if needed (or use existing one without overwriting)
-3. Subscribe your tenant to the microservice
-4. Retrieve and save bootstrap credentials to your env file
-
-After auto-bootstrap, your env file will contain:
-
-```sh
-C8Y_BOOTSTRAP_TENANT=<bootstrap-tenant-id>
-C8Y_BOOTSTRAP_USER=<bootstrap-username>
-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:
-
-1. **Dockerfile Generation** - Creates an optimized Dockerfile using Node.js 22-slim
-2. **Docker Image Build** - Builds and saves the Docker image to `image.tar`
-3. **Manifest Generation** - Creates `cumulocity.json` from your package.json and configuration
-4. **Zip Package** - Combines `image.tar` and `cumulocity.json` into a deployable zip file
-
-> **Note**: Docker must be installed and available in your PATH.
-
-The generated zip file (default: `<package-name>-<version>.zip` in root directory) is ready to upload directly to Cumulocity.
-
-## Manifest Configuration
-
-The `cumulocity.json` manifest is automatically generated from your `package.json` and can be customized via the `manifest` option.
-
-**Auto-generated from package.json:**
-
-- `name` (scope stripped), `version` - from package fields
-- `provider.name` - from `author` field
-- `provider.domain` - from `author.url` or `homepage`
-- `provider.support` - from `bugs` or `author.email`
-- `contextPath` - defaults to package name
-
-For all available manifest options, see the [Cumulocity Microservice Manifest documentation](https://cumulocity.com/docs/microservice-sdk/general-aspects/#microservice-manifest).
-
-> **Note**: Custom roles defined in the manifest are automatically available as TypeScript types for use in middleware and runtime code during development.
-
-> **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.
-
-The module uses the development credentials from your `.env` file:
-
-```sh
-C8Y_DEVELOPMENT_TENANT=t12345
-C8Y_DEVELOPMENT_USER=your-username
-C8Y_DEVELOPMENT_PASSWORD=your-password
-```
-
-This enables testing of access control middlewares like `hasUserRequiredRole()` and `isUserFromAllowedTenant()` without needing to manually set authorization headers.
-
-### Managing Development User Roles
-
-Use the [CLI roles command](#cli-commands) to assign or remove your microservice's custom roles to your development user:
-
-```sh
-pnpm dlx c8y-nitro roles
-```
-
-This interactive command lets you select which roles from your manifest to assign to your development user for testing.
-
-## API Client Generation
-
-For monorepo architectures, `c8y-nitro` can generate TypeScript Angular services that provide fully typed access to your microservice routes.
-
-### Configuration
-
-```ts
-export default defineNitroConfig({
-  c8y: {
-    apiClient: {
-      dir: '../ui/src/app/services', // Output directory for generated client
-      contextPath: 'my-service' // Optional: override context path
-    }
-  },
-  modules: [c8y()],
-})
-```
-
-### Generated Client
-
-The generated service creates one method per route with automatic type inference:
-
-```ts
-// Generated: my-serviceAPIClient.ts
-@Injectable({ providedIn: 'root' })
-export class GeneratedMyServiceAPIClient {
-  async GETHealth(): Promise<{ status: string }> { }
-  async GETUsersById(params: { id: string | number }): Promise<User> { }
-  async POSTUsers(body: CreateUserDto): Promise<User> { }
-}
-```
-
-### Usage in Angular
-
-```ts
-import { GeneratedMyServiceAPIClient } from './services/my-serviceAPIClient'
-
-@Component({
-  /**
-   * ...
-   */
-})
-export class MyComponent {
-  private api = inject(GeneratedMyServiceAPIClient)
-
-  async ngOnInit() {
-    const health = await this.api.GETHealth()
-    const user = await this.api.GETUsersById({ id: 123 })
-  }
-}
-```
-
-> **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.
-
-To use these utilities, simply import them from `c8y-nitro/utils`:
-
-```ts
-import { useUser, useUserClient } from 'c8y-nitro/utils'
-```
-
-### Usage
+## Documentation
 
-All utility functions that require request context accept either an `H3Event` or `ServerRequest` parameter:
+Full documentation is available at [schplitt.github.io/c8y-nitro](https://schplitt.github.io/c8y-nitro/).
 
-```ts
-// Pass the event/request parameter
-export default defineHandler(async (event) => {
-  const user = await useUser(event)
-  const client = useUserClient(event)
-  return { user }
-})
-```
-
-**Optional: Using with `asyncContext`**
-
-If you enable `experimental.asyncContext: true` in your Nitro config, you can use Nitro's `useRequest()` to avoid passing the event through deeply nested function calls:
-
-```ts
-import { useRequest } from 'nitro/context'
-
-export default defineHandler(async (event) => {
-  // Deep nested function - no need to pass event down
-  return await someDeepFunction()
-})
-
-async function someDeepFunction() {
-  return await anotherFunction()
-}
-
-async function anotherFunction() {
-  // Use useRequest() to get the request in any nested function
-  const request = useRequest()
-  const user = await useUser(request)
-  return { user }
-}
-```
-
-### Credentials
-
-| 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()],
-})
-```
+Useful entry points:
 
-> **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
-
-| Function         | Description                        | Request Context |
-| ---------------- | ---------------------------------- | :-------------: |
-| `useUser()`      | Fetch current user from Cumulocity |       ✅        |
-| `useUserRoles()` | Get roles of the current user      |       ✅        |
-
-### Client
-
-| Function                       | Description                                         | Request Context |
-| ------------------------------ | --------------------------------------------------- | :-------------: |
-| `useUserClient()`              | Create client authenticated with user's credentials |       ✅        |
-| `useUserTenantClient()`        | Create client for user's tenant (microservice user) |       ✅        |
-| `useSubscribedTenantClients()` | Create clients for all subscribed tenants           |       ❌        |
-| `useDeployedTenantClient()`    | Create client for the deployed tenant               |       ❌        |
-
-### Middleware
-
-| Function                                   | Description                               | Request Context |
-| ------------------------------------------ | ----------------------------------------- | :-------------: |
-| `hasUserRequiredRole(role\|roles)`         | Check if user has required role(s)        |       ✅        |
-| `isUserFromAllowedTenant(tenant\|tenants)` | Check if user is from allowed tenant(s)   |       ✅        |
-| `isUserFromDeployedTenant()`               | Check if user is from the deployed tenant |       ✅        |
-
-## CLI Commands
-
-| Command     | Description                                             |
-| ----------- | ------------------------------------------------------- |
-| `bootstrap` | Manually register microservice and retrieve credentials |
-| `roles`     | Manage development user roles                           |
-| `options`   | Manage tenant options on development tenant             |
-
-For more information, run:
-
-```sh
-pnpm dlx c8y-nitro -h
-```
+- [What is c8y-nitro?](https://schplitt.github.io/c8y-nitro/guide/what-is-c8y-nitro)
+- [Configuration](https://schplitt.github.io/c8y-nitro/guide/configuration)
+- [Module Options](https://schplitt.github.io/c8y-nitro/reference/module-options)
+- [Utilities](https://schplitt.github.io/c8y-nitro/reference/utilities)
 
 ## Development
 
+For contributors working on this repository:
+
 ```sh
-# Install dependencies
 pnpm install
-
-# Run dev watcher
 pnpm dev
-
-# Build for production
 pnpm build
-
-# Run tests (watch mode)
-pnpm test
-
-# Run tests once
 pnpm test:run
+pnpm lint
+pnpm typecheck
+pnpm docs:build
 ```
 
-### 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.
+Use `pnpm dev` for the package watcher, `pnpm docs:dev` for the VitePress site, and check the full contributor-facing behavior in the docs plus <AGENTS.md>.
 
 ## License
 
-MIT
+Use `pnpm dev` for the package watcher, `pnpm docs:dev` for the VitePress site, and check the full contributor-facing behavior in the docs plus <AGENTS.md>.

package/dist/{bootstrap-BqWPkH8q.mjs → bootstrap-DUDpmXcU.mjs}

@@ -1,6 +1,6 @@
-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 { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BbRS1-Ls.mjs";
 import { t as writeBootstrapCredentials } from "./env-file-B0BK-uZW.mjs";
-import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-Dqi-ttQi.mjs";
+import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BRnvtthI.mjs";
 import { defineCommand, runCommand } from "citty";
 import { consola } from "consola";
 //#region src/cli/commands/bootstrap.ts
@@ -52,7 +52,7 @@ var bootstrap_default = defineCommand({
 		});
 		consola.success(`Bootstrap credentials written to ${envFileName}`);
 		if (manifest.roles && manifest.roles.length > 0) {
-			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-DJxp2d8p.mjs").then((r) => r.default), { rawArgs: [] });
+			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-D7rpbxPp.mjs").then((r) => r.default), { rawArgs: [] });
 		}
 		consola.success("Bootstrap complete!");
 	}

package/dist/{c8y-api-BBSKRwKs.mjs → c8y-api-BbRS1-Ls.mjs}

@@ -3,8 +3,17 @@ import { Buffer } from "node:buffer";
 //#region src/module/constants.ts
 const GENERATED_LIVENESS_ROUTE = "/_c8y_nitro/liveness";
 const GENERATED_READINESS_ROUTE = "/_c8y_nitro/readiness";
+const GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE = "/_c8y_nitro/invalidate-tenant-options";
 //#endregion
 //#region src/module/manifest.ts
+const ROLE_OPTION_MANAGEMENT_READ = "ROLE_OPTION_MANAGEMENT_READ";
+const ROLE_OPTION_MANAGEMENT_ADMIN = "ROLE_OPTION_MANAGEMENT_ADMIN";
+function validateManifestSettings(options) {
+	const invalidSettings = options.settings?.filter((setting) => typeof setting.defaultValue !== "string" || setting.defaultValue.length === 0) ?? [];
+	if (invalidSettings.length === 0) return;
+	const invalidKeys = invalidSettings.map((setting) => `"${setting.key}"`).join(", ");
+	throw new Error(`manifest.settings entries must define a non-empty defaultValue. Invalid keys: ${invalidKeys}`);
+}
 async function readPackageJsonFieldsForManifest(rootDir, logger) {
 	logger?.debug(`Reading package file from ${rootDir}`);
 	const pkg = await readPackage(rootDir);
@@ -37,6 +46,7 @@ async function readPackageJsonFieldsForManifest(rootDir, logger) {
 * @param logger - Optional logger for debug output
 */
 async function createC8yManifest(rootDir, options = {}, logger) {
+	validateManifestSettings(options);
 	const { name, version, provider, ...restManifestFields } = await readPackageJsonFieldsForManifest(rootDir, logger);
 	const probeFields = {};
 	if (!options.livenessProbe?.httpGet) probeFields.livenessProbe = {
@@ -48,10 +58,16 @@ async function createC8yManifest(rootDir, options = {}, logger) {
 		httpGet: { path: GENERATED_READINESS_ROUTE }
 	};
 	const key = `${name}-key`;
+	let requiredRoles = options.requiredRoles ? [...options.requiredRoles] : void 0;
+	if (options.settings && options.settings.length > 0 && !requiredRoles?.includes(ROLE_OPTION_MANAGEMENT_READ) && !requiredRoles?.includes(ROLE_OPTION_MANAGEMENT_ADMIN)) {
+		requiredRoles = [...requiredRoles ?? [], ROLE_OPTION_MANAGEMENT_READ];
+		logger?.debug(`Auto-added ${ROLE_OPTION_MANAGEMENT_READ} to requiredRoles because manifest.settings are defined`);
+	}
 	const manifest = {
 		...restManifestFields,
 		...probeFields,
 		...options,
+		...requiredRoles !== void 0 ? { requiredRoles } : {},
 		provider,
 		name,
 		version,
@@ -286,7 +302,35 @@ async function getTenantOption(baseUrl, category, key, authHeader) {
 	return (await response.json()).value;
 }
 /**
-* Updates or creates a tenant option.
+* 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 value to set
+* @param authHeader - The Basic Auth header
+*/
+async function createTenantOption(baseUrl, category, key, value, authHeader) {
+	const url = `${baseUrl}/tenant/options`;
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Authorization": authHeader,
+			"Content-Type": "application/vnd.com.nsn.cumulocity.option+json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({
+			category,
+			key,
+			value
+		})
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Failed to create tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
+	}
+}
+/**
+* Updates an existing tenant option.
 * @param baseUrl - The Cumulocity base URL
 * @param category - The category of the option
 * @param key - The option key
@@ -310,6 +354,25 @@ async function updateTenantOption(baseUrl, category, key, value, authHeader) {
 	}
 }
 /**
+* Updates a tenant option if it exists, otherwise creates it.
+* @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 upsertTenantOption(baseUrl, category, key, value, authHeader) {
+	try {
+		await updateTenantOption(baseUrl, category, key, value, authHeader);
+	} catch (error) {
+		if (error.cause?.status === 404) {
+			await createTenantOption(baseUrl, category, key, value, authHeader);
+			return;
+		}
+		throw error;
+	}
+}
+/**
 * Deletes a tenant option.
 * @param baseUrl - The Cumulocity base URL
 * @param category - The category of the option
@@ -329,4 +392,4 @@ async function deleteTenantOption(baseUrl, category, key, authHeader) {
 	}
 }
 //#endregion
-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 };
+export { GENERATED_READINESS_ROUTE as _, findMicroserviceByName as a, getTenantOptionsByCategory as c, updateMicroservice as d, upsertTenantOption as f, GENERATED_LIVENESS_ROUTE as g, GENERATED_INVALIDATE_TENANT_OPTIONS_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,4 +1,4 @@
-import { n as name, r as version, t as description } from "../package-C4HtuVu_.mjs";
+import { n as name, r as version, t as description } from "../package-DsLC9Mo3.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/cli/index.ts
 runMain(defineCommand({
@@ -8,9 +8,9 @@ runMain(defineCommand({
 		description
 	},
 	subCommands: {
-		bootstrap: () => import("../bootstrap-BqWPkH8q.mjs").then((r) => r.default),
-		roles: () => import("../roles-DJxp2d8p.mjs").then((r) => r.default),
-		options: () => import("../options-BDDJWdph.mjs").then((r) => r.default)
+		bootstrap: () => import("../bootstrap-DUDpmXcU.mjs").then((r) => r.default),
+		roles: () => import("../roles-D7rpbxPp.mjs").then((r) => r.default),
+		options: () => import("../options-Web5UyIU.mjs").then((r) => r.default)
 	}
 }));
 //#endregion