c8y-nitro 0.5.0 → 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,534 +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: {
-    enableTenantOptionsInvalidationRoute: false,
-    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.
-
-If you run a local proxy that already forwards a user session or authorization header, disable this middleware:
-
-```ts
-export default defineNitroConfig({
-  c8y: {
-    dev: {
-      injectUser: false,
-    },
-  },
-  modules: [c8y()],
-})
-```
-
-When disabled, `c8y-nitro` does not register the development user injection middleware, so incoming auth headers stay untouched.
-
-### 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)
+## Documentation
 
-  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.
+Full documentation is available at [schplitt.github.io/c8y-nitro](https://schplitt.github.io/c8y-nitro/).
 
-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
-
-All utility functions that require request context accept either an `H3Event` or `ServerRequest` parameter:
-
-```ts
-// Pass the event/request parameter
-export default defineHandler(async (event) => {
-  const user = await useUser(event)
-  const client = useUserClient(event)
-  return { user }
-})
-```
+Useful entry points:
 
-**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', defaultValue: 'change-me' }, // Encrypted option
-      ],
-      settingsCategory: 'my-service', // Optional, defaults to contextPath/name
-      requiredRoles: ['ROLE_OPTION_MANAGEMENT_READ'], // Required for reading tenant options
-    },
-  },
-  modules: [c8y()],
-})
-```
-
-`manifest.settings[].defaultValue` is required and must be a non-empty string. `''` is rejected during manifest generation so invalid settings fail early during development/build.
-
-> **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. See more details [here](https://cumulocity.com/api/core/#operation/postOptionCollectionResource).
-
-> **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 |       ✅        |
-
-Probe requests targeting the manifest-defined `livenessProbe.httpGet.path` or `readinessProbe.httpGet.path` bypass these auth helpers so orchestration health checks are not blocked by route-wide access control.
-
-## 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-BSdVwFWO.mjs → bootstrap-DUDpmXcU.mjs}

@@ -1,4 +1,4 @@
-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-BgTNTqHd.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-BRnvtthI.mjs";
 import { defineCommand, runCommand } from "citty";
@@ -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-CoBPqvDv.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-BgTNTqHd.mjs → c8y-api-BbRS1-Ls.mjs}

@@ -6,6 +6,8 @@ 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;
@@ -56,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,

package/dist/cli/index.mjs

@@ -1,4 +1,4 @@
-import { n as name, r as version, t as description } from "../package-bfMasPPg.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-BSdVwFWO.mjs").then((r) => r.default),
-		roles: () => import("../roles-CoBPqvDv.mjs").then((r) => r.default),
-		options: () => import("../options-BkWL1FOa.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

package/dist/credentials-9FO7rTIR.d.mts

@@ -0,0 +1,6 @@
+import { ICredentials } from "@c8y/client";
+
+//#region src/types/credentials.d.ts
+type TenantCredentials = Record<string, ICredentials>;
+//#endregion
+export { TenantCredentials as t };

package/dist/{index-Bvu7DqDt.d.mts → index-uOwpI6rD.d.mts}

@@ -411,7 +411,7 @@ interface C8yNitroModuleOptions {
    *
    * Query params:
    * - `all`: invalidate all created tenant option fetchers
-   * - `key`: invalidate a single manifest-defined tenant option key if its fetcher exists
+   * - `key`: invalidate a single manifest-defined tenant option key if it exists
    *
    * `all` takes priority over `key`.
    * @default false

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { n as C8yNitroModuleOptions } from "./index-Bvu7DqDt.mjs";
+import { n as C8yNitroModuleOptions } from "./index-uOwpI6rD.mjs";
+import { t as TenantCredentials } from "./credentials-9FO7rTIR.mjs";
 import { NitroModule } from "nitro/types";
 
 //#region src/index.d.ts
@@ -7,6 +8,11 @@ declare module 'nitro/types' {
     c8y?: C8yNitroModuleOptions;
   }
 }
+declare module 'nitro/types' {
+  interface NitroRuntimeHooks {
+    'c8y:tenantCredentialsUpdated': (prev: TenantCredentials | null, next: TenantCredentials) => void;
+  }
+}
 declare function c8y(): NitroModule;
 //#endregion
 export { c8y, c8y as default };

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { _ as GENERATED_READINESS_ROUTE, a as findMicroserviceByName, g as GENERATED_LIVENESS_ROUTE, h as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, l as subscribeToApplication, m as createC8yManifestFromNitro, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BgTNTqHd.mjs";
+import { _ as GENERATED_READINESS_ROUTE, a as findMicroserviceByName, g as GENERATED_LIVENESS_ROUTE, h as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, l as subscribeToApplication, m as createC8yManifestFromNitro, 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 name } from "./package-bfMasPPg.mjs";
+import { n as name } from "./package-DsLC9Mo3.mjs";
 import { basename, dirname, join, relative } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { x } from "tinyexec";

package/dist/{options-BkWL1FOa.mjs → options-Web5UyIU.mjs}

@@ -1,4 +1,4 @@
-import { c as getTenantOptionsByCategory, f as upsertTenantOption, i as deleteTenantOption, n as createBasicAuthHeader, p as createC8yManifest, s as getTenantOption } from "./c8y-api-BgTNTqHd.mjs";
+import { c as getTenantOptionsByCategory, f as upsertTenantOption, i as deleteTenantOption, n as createBasicAuthHeader, p as createC8yManifest, s as getTenantOption } from "./c8y-api-BbRS1-Ls.mjs";
 import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BRnvtthI.mjs";
 import { defineCommand } from "citty";
 import { consola } from "consola";

package/dist/{package-bfMasPPg.mjs → package-DsLC9Mo3.mjs}

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "c8y-nitro";
-var version = "0.5.0";
+var version = "0.6.0";
 var description = "Lightning fast Cumulocity IoT microservice development powered by Nitro";
 //#endregion
 export { name as n, version as r, description as t };

package/dist/{roles-CoBPqvDv.mjs → roles-D7rpbxPp.mjs}

@@ -1,4 +1,4 @@
-import { n as createBasicAuthHeader, p as createC8yManifest, t as assignUserRole, u as unassignUserRole } from "./c8y-api-BgTNTqHd.mjs";
+import { n as createBasicAuthHeader, p as createC8yManifest, t as assignUserRole, u as unassignUserRole } from "./c8y-api-BbRS1-Ls.mjs";
 import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BRnvtthI.mjs";
 import { defineCommand } from "citty";
 import { consola } from "consola";

package/dist/types.d.mts

@@ -1,2 +1,3 @@
-import { a as C8YRoles, c as C8YManifest, i as C8YTenantOptionKeysCacheConfig, l as C8YManifestOptions, n as C8yNitroModuleOptions, o as C8yCacheOptions, r as C8YTenantOptionKey, s as C8YZipOptions, t as C8yDevOptions, u as C8YAPIClientOptions } from "./index-Bvu7DqDt.mjs";
-export { C8YAPIClientOptions, C8YManifest, C8YManifestOptions, C8YRoles, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, C8YZipOptions, C8yCacheOptions, C8yDevOptions, C8yNitroModuleOptions };
+import { a as C8YRoles, c as C8YManifest, i as C8YTenantOptionKeysCacheConfig, l as C8YManifestOptions, n as C8yNitroModuleOptions, o as C8yCacheOptions, r as C8YTenantOptionKey, s as C8YZipOptions, t as C8yDevOptions, u as C8YAPIClientOptions } from "./index-uOwpI6rD.mjs";
+import { t as TenantCredentials } from "./credentials-9FO7rTIR.mjs";
+export { C8YAPIClientOptions, C8YManifest, C8YManifestOptions, C8YRoles, C8YTenantOptionKey, C8YTenantOptionKeysCacheConfig, C8YZipOptions, C8yCacheOptions, C8yDevOptions, C8yNitroModuleOptions, TenantCredentials };

package/dist/utils.d.mts

@@ -1,8 +1,9 @@
+import { t as TenantCredentials } from "./credentials-9FO7rTIR.mjs";
 import { useLogger } from "evlog/nitro/v3";
 import { Client, ICredentials, ICurrentUser } from "@c8y/client";
 import { EventHandler, H3Event } from "nitro/h3";
 import { createError, createLogger } from "evlog";
-import { ServerRequest } from "nitro/types";
+import { ServerRequest, TaskContext, TaskPayload } from "nitro/types";
 import { C8YRoles, C8YTenantOptionKey } from "c8y-nitro/types";
 
 //#region src/utils/client.d.ts
@@ -163,31 +164,9 @@ declare function useUser(requestOrEvent: ServerRequest | H3Event): Promise<ICurr
 declare function useUserRoles(requestOrEvent: ServerRequest | H3Event): Promise<string[]>;
 //#endregion
 //#region src/utils/credentials.d.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 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()
- * console.log(Object.keys(credentials)) // ['t12345', 't67890']
- *
- * // Access specific tenant:
- * const tenant1Creds = credentials['t12345']
- *
- * // Invalidate cache:
- * await useSubscribedTenantCredentials.invalidate()
- *
- * // Force refresh:
- * const freshCreds = await useSubscribedTenantCredentials.refresh()
- */
-declare const useSubscribedTenantCredentials: (() => Promise<Record<string, ICredentials>>) & {
+declare const useSubscribedTenantCredentials: (() => Promise<TenantCredentials>) & {
   invalidate: () => Promise<void>;
-  refresh: () => Promise<Record<string, ICredentials>>;
+  refresh: () => Promise<TenantCredentials>;
 };
 /**
  * Fetches credentials for the tenant where this microservice is deployed.\
@@ -285,4 +264,110 @@ declare const useTenantOption: ((key: C8YTenantOptionKey) => Promise<string | un
   refreshAll: () => Promise<Record<string, string | undefined>>;
 };
 //#endregion
-export { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+//#region src/utils/schedule.d.ts
+type ScheduledTaskPayload = TaskPayload;
+type ScheduledTaskContext = TaskContext;
+/**
+ * A one-shot schedule definition for `scheduleTask()`.\
+ * Numbers are treated as seconds from now, strings are parsed as human-readable durations
+ * such as `"10 minutes"`, and dates are used as exact run times.
+ */
+type ScheduledTaskInput = Date | number | string;
+/**
+ * Options for scheduling a Nitro task to run once in the future.\
+ * `payload` and `context` are forwarded to the task handler's `run()` method.
+ */
+interface ScheduleTaskOptions {
+  /**
+   * Payload forwarded to the task handler's `TaskEvent.payload`.
+   */
+  payload?: ScheduledTaskPayload;
+  /**
+   * Context forwarded to the task handler's `TaskEvent.context`.
+   */
+  context?: ScheduledTaskContext;
+  /**
+   * When the task should run. Numbers are seconds from now.
+   */
+  schedule: ScheduledTaskInput;
+}
+/**
+ * Public information about a pending scheduled task.\
+ * Returned by `scheduleTask()` and by `listScheduledTasks()`.
+ */
+interface ScheduledTaskInfo {
+  /**
+   * Stable UUID used to list or cancel the scheduled task.
+   */
+  id: string;
+  /**
+   * Nitro task name that will be passed to `runTask()`.
+   */
+  task: string;
+  /**
+   * Exact execution time as an ISO date string.
+   */
+  runAt: string;
+}
+/**
+ * Schedules a Nitro task to run once in the future.\
+ * Resolves and calls the task handler directly from Nitro's virtual task registry\
+ * Numbers are treated as seconds, strings are parsed as human-readable durations, and dates are used as exact run times.
+ *
+ * @param taskName - The Nitro task name to run (from `tasks/*.ts`)
+ * @param options - Task payload, context, and the schedule time
+ * @returns Information about the scheduled task
+ *
+ * @example
+ * // Run a task in 30 seconds:
+ * const scheduled = await scheduleTask('emails:send', {
+ *   payload: { messageId: 'abc123' },
+ *   schedule: 30,
+ * })
+ *
+ * @example
+ * // Run a task using a human-readable duration:
+ * await scheduleTask('reports:generate', {
+ *   payload: { reportId: 'report-1' },
+ *   schedule: '1 hour',
+ * })
+ *
+ * @example
+ * // Run a task at an exact time:
+ * await scheduleTask('cleanup:tenant', {
+ *   payload: { tenant: 't12345' },
+ *   schedule: new Date('2026-05-01T12:00:00Z'),
+ * })
+ */
+declare function scheduleTask(taskName: string, options: ScheduleTaskOptions): Promise<ScheduledTaskInfo>;
+/**
+ * Lists all tasks that are currently scheduled and have not started yet.\
+ * The returned object is keyed by the scheduled task UUID for easy lookup and cancellation.
+ *
+ * @returns Object mapping scheduled task IDs to their public task information
+ *
+ * @example
+ * const tasks = await listScheduledTasks()
+ * for (const [id, task] of Object.entries(tasks)) {
+ *   console.log(id, task.task, task.runAt)
+ * }
+ */
+declare function listScheduledTasks(): Promise<Record<string, ScheduledTaskInfo>>;
+/**
+ * Cancels a scheduled task before it starts running.\
+ * Once the underlying Nitro task has started, it cannot be cancelled with this utility.
+ *
+ * @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
+ * @returns `true` when a pending task was cancelled, otherwise `false`
+ *
+ * @example
+ * const scheduled = await scheduleTask('emails:send', {
+ *   payload: { messageId: 'abc123' },
+ *   schedule: '10 minutes',
+ * })
+ *
+ * const cancelled = await cancelScheduledTask(scheduled.id)
+ */
+declare function cancelScheduledTask(id: string): Promise<boolean>;
+//#endregion
+export { ScheduleTaskOptions, ScheduledTaskContext, ScheduledTaskInfo, ScheduledTaskInput, ScheduledTaskPayload, cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/dist/utils.mjs

@@ -3,12 +3,14 @@ import process from "node:process";
 import { useLogger } from "evlog/nitro/v3";
 import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
 import { defineCachedFunction } from "nitro/cache";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { HTTPError, defineHandler } from "nitro/h3";
-import { useStorage } from "nitro/storage";
 import { useRuntimeConfig } from "nitro/runtime-config";
+import { useNitroHooks } from "nitro/app";
 import { c8yManifest } from "c8y-nitro/runtime";
 import { createError, createLogger } from "evlog";
+import { ms } from "itty-time";
+import { tasks } from "#nitro/virtual/tasks";
 //#region src/utils/internal/common.ts
 /**
 * Converts undici Request headers to the format expected by MicroserviceClientRequestAuth.\
@@ -83,6 +85,14 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 });
 //#endregion
 //#region src/utils/credentials.ts
+let prevCredentials = null;
+function shouldEmitTenantCredentialsUpdated(prev, next) {
+	if (!prev) return true;
+	const prevTenantIds = Object.keys(prev);
+	const nextTenantIds = Object.keys(next);
+	if (prevTenantIds.length !== nextTenantIds.length) return true;
+	return new Set(nextTenantIds).symmetricDifference(new Set(prevTenantIds)).size > 0;
+}
 /**
 * Fetches credentials for all tenants subscribed to this microservice.\
 * Uses bootstrap credentials from runtime config to query the microservice subscriptions API.\
@@ -90,7 +100,7 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 * @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
+* - `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable
 * @example
 * // Get all subscribed tenant credentials:
 * const credentials = await useSubscribedTenantCredentials()
@@ -105,8 +115,8 @@ const getCurrentUserTenantId = defineCachedFunction(async (requestOrEvent) => {
 * // Force refresh:
 * const freshCreds = await useSubscribedTenantCredentials.refresh()
 */
-const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async () => {
-	return (await Client.getMicroserviceSubscriptions({
+const cachedSubscribedTenantCredentials = defineCachedFunction(async () => {
+	const newCredentials = (await Client.getMicroserviceSubscriptions({
 		tenant: process.env.C8Y_BOOTSTRAP_TENANT,
 		user: process.env.C8Y_BOOTSTRAP_USER,
 		password: process.env.C8Y_BOOTSTRAP_PASSWORD
@@ -114,18 +124,26 @@ const useSubscribedTenantCredentials = Object.assign(defineCachedFunction(async
 		if (cred.tenant) acc[cred.tenant] = cred;
 		return acc;
 	}, {});
+	if (shouldEmitTenantCredentialsUpdated(prevCredentials, newCredentials)) useNitroHooks().callHook("c8y:tenantCredentialsUpdated", prevCredentials, newCredentials);
+	prevCredentials = newCredentials;
+	return newCredentials;
 }, {
 	maxAge: useRuntimeConfig().c8yCredentialsCacheTTL ?? 600,
 	name: "_c8y_nitro_get_subscribed_tenant_credentials",
 	group: "c8y_nitro",
 	swr: false
-}), {
-	invalidate: async () => {
-		await useStorage("cache").removeItem(`c8y_nitro:functions:_c8y_nitro_get_subscribed_tenant_credentials.json`);
-	},
+});
+const useSubscribedTenantCredentials = Object.assign(async () => {
+	const credentials = await cachedSubscribedTenantCredentials();
+	prevCredentials = credentials;
+	return credentials;
+}, {
+	invalidate: cachedSubscribedTenantCredentials.invalidate,
 	refresh: async () => {
-		await useSubscribedTenantCredentials.invalidate();
-		return await useSubscribedTenantCredentials();
+		await cachedSubscribedTenantCredentials.invalidate();
+		const credentials = await cachedSubscribedTenantCredentials();
+		prevCredentials = credentials;
+		return credentials;
 	}
 });
 /**
@@ -158,7 +176,7 @@ const useDeployedTenantCredentials = Object.assign(async () => {
 }, {
 	invalidate: useSubscribedTenantCredentials.invalidate,
 	refresh: async () => {
-		await useDeployedTenantCredentials.invalidate();
+		await useSubscribedTenantCredentials.refresh();
 		return await useDeployedTenantCredentials();
 	}
 });
@@ -402,7 +420,7 @@ function getTenantOptionCacheTTL(key) {
 */
 function createCachedTenantOptionFetcher(key) {
 	const cacheName = `_c8y_nitro_tenant_option_${key.replace(/\./g, "_")}`;
-	const fetcher = defineCachedFunction(async () => {
+	const cachedFetcher = defineCachedFunction(async () => {
 		const client = await useDeployedTenantClient();
 		const category = useRuntimeConfig().c8ySettingsCategory;
 		try {
@@ -420,17 +438,10 @@ function createCachedTenantOptionFetcher(key) {
 		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();
-		}
-	});
+	return Object.assign(cachedFetcher, { refresh: async () => {
+		await cachedFetcher.invalidate();
+		return await cachedFetcher();
+	} });
 }
 /**
 * Gets or creates a cached fetcher for a specific tenant option key.
@@ -479,16 +490,33 @@ function getOrCreateFetcher(key) {
 const useTenantOption = Object.assign(async (key) => {
 	return await getOrCreateFetcher(key)();
 }, {
+	/**
+	* Invalidate the cache for a specific tenant option key.
+	* @param key - The tenant option key to invalidate
+	*/
 	invalidate: async (key) => {
 		const fetcher = tenantOptionFetchers[key];
 		if (fetcher) await fetcher.invalidate();
 	},
+	/**
+	* Force refresh a specific tenant option key (invalidates and re-fetches).
+	* @param key - The tenant option key to refresh
+	*/
 	refresh: async (key) => {
 		return await getOrCreateFetcher(key).refresh();
 	},
+	/**
+	* Invalidate all tenant option caches that have been accessed.
+	* Only invalidates keys that have been fetched at least once.
+	*/
 	invalidateAll: async () => {
 		await Promise.all(Object.values(tenantOptionFetchers).map((fetcher) => fetcher?.invalidate()));
 	},
+	/**
+	* Refresh all tenant options that have been accessed.
+	* Only refreshes keys that have been fetched at least once.
+	* @returns Object mapping keys to their refreshed values
+	*/
 	refreshAll: async () => {
 		const entries = Object.entries(tenantOptionFetchers);
 		const values = await Promise.all(entries.map(([, fetcher]) => fetcher?.refresh()));
@@ -496,4 +524,168 @@ const useTenantOption = Object.assign(async (key) => {
 	}
 });
 //#endregion
-export { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };
+//#region src/utils/schedule.ts
+const MAX_TIMEOUT_MS = 2147483647;
+const SCHEDULE_LOOKAHEAD_MS = 3600 * 1e3;
+const SCHEDULER_TICK_MS = 100;
+const scheduledTasks = /* @__PURE__ */ new Map();
+const scheduledTaskTimers = /* @__PURE__ */ new Map();
+const schedulerReady = Promise.resolve();
+let schedulerInterval;
+function createScheduledTaskId() {
+	return randomUUID();
+}
+function resolveScheduleTime(schedule) {
+	if (schedule instanceof Date) {
+		const timestamp = schedule.getTime();
+		if (Number.isNaN(timestamp)) throw new TypeError("schedule date must be valid");
+		return timestamp;
+	}
+	if (typeof schedule === "number") {
+		if (!Number.isFinite(schedule) || schedule < 0) throw new TypeError("schedule number must be a non-negative number of seconds");
+		return Date.now() + schedule * 1e3;
+	}
+	const delay = ms(schedule);
+	if (!Number.isFinite(delay) || delay < 0) throw new TypeError("schedule string must be a valid non-negative duration");
+	return Date.now() + delay;
+}
+async function executeScheduledTask(id) {
+	const record = scheduledTasks.get(id);
+	if (!record) return;
+	if (record.timeoutId !== void 0) scheduledTaskTimers.delete(record.timeoutId);
+	scheduledTasks.delete(id);
+	stopSchedulerIntervalIfIdle();
+	const taskDef = tasks[record.taskName];
+	if (!taskDef) throw new Error(`Task "${record.taskName}" is not available!`);
+	if (!taskDef.resolve) throw new Error(`Task "${record.taskName}" is not implemented!`);
+	await (await taskDef.resolve()).run({
+		name: record.taskName,
+		payload: record.payload,
+		context: record.context
+	});
+}
+function armScheduledTaskTimeout(id) {
+	const record = scheduledTasks.get(id);
+	if (!record || record.timeoutId !== void 0) return;
+	const remainingMs = Math.max(record.runAt - Date.now(), 0);
+	if (remainingMs > SCHEDULE_LOOKAHEAD_MS) return;
+	const timeout = setTimeout(() => {
+		executeScheduledTask(id);
+	}, Math.min(remainingMs, MAX_TIMEOUT_MS));
+	record.timeoutId = Number(timeout);
+	scheduledTaskTimers.set(record.timeoutId, timeout);
+}
+function runSchedulerTick() {
+	for (const record of scheduledTasks.values()) armScheduledTaskTimeout(record.id);
+}
+function ensureSchedulerInterval() {
+	if (schedulerInterval) return;
+	schedulerInterval = setInterval(runSchedulerTick, SCHEDULER_TICK_MS);
+}
+function stopSchedulerIntervalIfIdle() {
+	if (!schedulerInterval || scheduledTasks.size > 0) return;
+	clearInterval(schedulerInterval);
+	schedulerInterval = void 0;
+}
+/**
+* Schedules a Nitro task to run once in the future.\
+* Resolves and calls the task handler directly from Nitro's virtual task registry\
+* Numbers are treated as seconds, strings are parsed as human-readable durations, and dates are used as exact run times.
+*
+* @param taskName - The Nitro task name to run (from `tasks/*.ts`)
+* @param options - Task payload, context, and the schedule time
+* @returns Information about the scheduled task
+*
+* @example
+* // Run a task in 30 seconds:
+* const scheduled = await scheduleTask('emails:send', {
+*   payload: { messageId: 'abc123' },
+*   schedule: 30,
+* })
+*
+* @example
+* // Run a task using a human-readable duration:
+* await scheduleTask('reports:generate', {
+*   payload: { reportId: 'report-1' },
+*   schedule: '1 hour',
+* })
+*
+* @example
+* // Run a task at an exact time:
+* await scheduleTask('cleanup:tenant', {
+*   payload: { tenant: 't12345' },
+*   schedule: new Date('2026-05-01T12:00:00Z'),
+* })
+*/
+async function scheduleTask(taskName, options) {
+	if (!import.meta._tasks) throw new Error("scheduleTask() requires tasks to be enabled. Set `experimental: { tasks: true }` in your nitro.config.ts.");
+	if (!taskName) throw new TypeError("taskName is required");
+	const runAt = resolveScheduleTime(options.schedule);
+	const record = {
+		id: createScheduledTaskId(),
+		taskName,
+		payload: options.payload ?? {},
+		context: options.context ?? {},
+		runAt
+	};
+	scheduledTasks.set(record.id, record);
+	armScheduledTaskTimeout(record.id);
+	ensureSchedulerInterval();
+	return {
+		id: record.id,
+		task: record.taskName,
+		runAt: new Date(record.runAt).toISOString()
+	};
+}
+/**
+* Lists all tasks that are currently scheduled and have not started yet.\
+* The returned object is keyed by the scheduled task UUID for easy lookup and cancellation.
+*
+* @returns Object mapping scheduled task IDs to their public task information
+*
+* @example
+* const tasks = await listScheduledTasks()
+* for (const [id, task] of Object.entries(tasks)) {
+*   console.log(id, task.task, task.runAt)
+* }
+*/
+async function listScheduledTasks() {
+	await schedulerReady;
+	return Object.fromEntries([...scheduledTasks.values()].map((record) => [record.id, {
+		id: record.id,
+		task: record.taskName,
+		runAt: new Date(record.runAt).toISOString()
+	}]));
+}
+/**
+* Cancels a scheduled task before it starts running.\
+* Once the underlying Nitro task has started, it cannot be cancelled with this utility.
+*
+* @param id - The scheduled task UUID returned by `scheduleTask()` or `listScheduledTasks()`
+* @returns `true` when a pending task was cancelled, otherwise `false`
+*
+* @example
+* const scheduled = await scheduleTask('emails:send', {
+*   payload: { messageId: 'abc123' },
+*   schedule: '10 minutes',
+* })
+*
+* const cancelled = await cancelScheduledTask(scheduled.id)
+*/
+async function cancelScheduledTask(id) {
+	await schedulerReady;
+	const record = scheduledTasks.get(id);
+	if (!record) return false;
+	if (record.timeoutId !== void 0) {
+		const timeout = scheduledTaskTimers.get(record.timeoutId);
+		if (timeout) {
+			clearTimeout(timeout);
+			scheduledTaskTimers.delete(record.timeoutId);
+		}
+	}
+	const cancelled = scheduledTasks.delete(id);
+	stopSchedulerIntervalIfIdle();
+	return cancelled;
+}
+//#endregion
+export { cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8y-nitro",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Lightning fast Cumulocity IoT microservice development powered by Nitro",
   "keywords": [
@@ -38,31 +38,34 @@
     "dist"
   ],
   "dependencies": {
-    "c12": "^4.0.0-beta.4",
+    "c12": "^4.0.0-beta.5",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
-    "evlog": "^2.11.1",
+    "evlog": "^2.17.0",
+    "itty-time": "^2.0.2",
     "jszip": "^3.10.1",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.0",
+    "pkg-types": "^2.3.1",
     "spinnies": "^0.5.1",
-    "tinyexec": "^1.1.1",
-    "tsnapi": "^0.1.1"
+    "tinyexec": "^1.1.2"
   },
   "devDependencies": {
-    "@schplitt/eslint-config": "^1.3.1",
+    "@schplitt/eslint-config": "^1.5.0",
+    "@types/node": "^24.12.3",
     "@types/spinnies": "^0.5.3",
-    "bumpp": "^11.0.1",
+    "bumpp": "^11.1.0",
     "changelogithub": "^14.0.0",
-    "eslint": "^10.2.0",
-    "memfs": "^4.57.1",
-    "tsdown": "^0.21.7",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.4"
+    "eslint": "^10.3.0",
+    "memfs": "^4.57.2",
+    "tsdown": "^0.22.0",
+    "tsnapi": "^0.3.3",
+    "typescript": "^6.0.3",
+    "vitepress": "2.0.0-alpha.17",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
     "@c8y/client": ">=1021",
-    "nitro": "3.0.260311-beta"
+    "nitro": "3.0.260429-beta"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -77,6 +80,9 @@
     "prerelease": "eslint && tsc --noEmit && tsdown && vitest run",
     "release": "bumpp",
     "test": "vitest",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }