c8y-nitro 0.3.0 → 0.4.1

package/dist/runtime/plugins/c8y-variables.mjs

@@ -0,0 +1,17 @@
+import process from "node:process";
+import { definePlugin } from "nitro";
+//#region src/module/runtime/plugins/c8y-variables.ts
+var c8y_variables_default = definePlugin(() => {
+	if (import.meta.dev) {
+		const env = process.env;
+		const missingVars = [
+			"C8Y_BASEURL",
+			"C8Y_BOOTSTRAP_TENANT",
+			"C8Y_BOOTSTRAP_USER",
+			"C8Y_BOOTSTRAP_PASSWORD"
+		].filter((varName) => !env[varName]);
+		if (missingVars.length > 0) throw new Error(`Missing required environment variables for development: ${missingVars.join(", ")}\n\nTo set up your development environment, run:\n  npx c8y-nitro bootstrap\n\nThis command will:\n  1. Require your development tenant credentials (C8Y_BASEURL C8Y_DEVELOPMENT_TENANT, C8Y_DEVELOPMENT_USER, C8Y_DEVELOPMENT_PASSWORD)\n  2. Register your microservice on the tenant\n  3. Generate the necessary bootstrap credentials in a .env file\n\nMake sure you have your development tenant credentials configured first.`);
+	}
+});
+//#endregion
+export { c8y_variables_default as default };

package/dist/runtime/plugins/enrich-logs.mjs

@@ -0,0 +1,15 @@
+import { definePlugin } from "nitro";
+import { c8yManifest } from "c8y-nitro/runtime";
+//#region src/module/runtime/plugins/enrich-logs.ts
+var enrich_logs_default = definePlugin(async (nitroApp) => {
+	nitroApp.hooks.hook("evlog:enrich", (enrichContext) => {
+		enrichContext.event.microservice = {
+			name: c8yManifest.name,
+			version: c8yManifest.version,
+			provider: c8yManifest.provider,
+			contextPath: c8yManifest.contextPath
+		};
+	});
+});
+//#endregion
+export { enrich_logs_default as default };

package/dist/types.d.mts

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

package/dist/types.mjs

@@ -1 +1 @@
-export {  };
+export {};

package/dist/utils.d.mts

@@ -1,7 +1,293 @@
-import { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, useUserTenantClient } from "./utils/client.mjs";
-import { hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant } from "./utils/middleware.mjs";
-import { useUser, useUserRoles } from "./utils/resources.mjs";
-import { useDeployedTenantCredentials, useSubscribedTenantCredentials, useUserTenantCredentials } from "./utils/credentials.mjs";
-import { useTenantOption } from "./utils/tenantOptions.mjs";
-import { createError, createLogger, useLogger } from "./utils/logging.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 { C8YRoles, C8YTenantOptionKey } from "c8y-nitro/types";
+
+//#region src/utils/client.d.ts
+/**
+ * Creates a Cumulocity client authenticated with the current user's credentials.\
+ * Extracts credentials from the Authorization header of the current request.
+ * @param requestOrEvent - The H3Event or ServerRequest from the current request
+ * @returns A configured Cumulocity Client instance
+ * @example
+ * // In a request handler:
+ * const client = useUserClient(event)
+ * const { data } = await client.inventory.list()
+ */
+declare function useUserClient(requestOrEvent: ServerRequest | H3Event): Client;
+/**
+ * Creates a Cumulocity client for the tenant of the current user.\
+ * Uses the tenant's service user credentials rather than the user's own credentials.
+ * @param requestOrEvent - The H3Event or ServerRequest from the current request
+ * @returns A configured Cumulocity Client instance for the user's tenant
+ * @example
+ * // In a request handler:
+ * const tenantClient = await useUserTenantClient(event)
+ * const { data } = await tenantClient.inventory.list()
+ */
+declare function useUserTenantClient(requestOrEvent: ServerRequest | H3Event): Promise<Client>;
+/**
+ * Creates Cumulocity clients for all tenants subscribed to this microservice.\
+ * Each client is authenticated with that tenant's service user credentials.\
+ * @returns Object mapping tenant IDs to their respective Client instances
+ * @example
+ * // Get clients for all subscribed tenants:
+ * const clients = await useSubscribedTenantClients()
+ * for (const [tenant, client] of Object.entries(clients)) {
+ *   const { data } = await client.inventory.list()
+ *   console.log(`Tenant ${tenant} has ${data.length} inventory items`)
+ * }
+ */
+declare function useSubscribedTenantClients(): Promise<Record<string, Client>>;
+/**
+ * Creates a Cumulocity client for the tenant where this microservice is deployed.\
+ * Uses the bootstrap tenant ID from runtime config to identify the deployed tenant.\
+ * @returns A configured Cumulocity Client instance for the deployed tenant
+ * @example
+ * // Get client for the tenant hosting this microservice:
+ * const client = await useDeployedTenantClient()
+ * const { data } = await client.application.list()
+ */
+declare function useDeployedTenantClient(): Promise<Client>;
+//#endregion
+//#region src/utils/middleware.d.ts
+type UserRole = keyof C8YRoles | (string & {});
+/**
+ * Middleware to check if the current user has the required role.\
+ * If the user doesn't have the required role, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param role - Single role ID to check for
+ * @returns Event handler that validates user roles
+ * @example
+ * // Single role:
+ * export default defineHandler({
+ *  middleware: [hasUserRequiredRole('ROLE_INVENTORY_ADMIN')],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ *
+ */
+declare function hasUserRequiredRole(role: UserRole): EventHandler;
+/**
+ * Middleware to check if the current user has at least one of the required roles.\
+ * If the user doesn't have any of the required roles, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param roles - Array of role IDs to check for
+ * @returns Event handler that validates user roles
+ * @example
+ * // Multiple roles:
+ * export default defineHandler({
+ *  middleware: [hasUserRequiredRole(['ROLE_INVENTORY_ADMIN', 'ROLE_DEVICE_CONTROL'])],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ */
+declare function hasUserRequiredRole(roles: UserRole[]): EventHandler;
+/**
+ * Middleware to check if the current user belongs to a specific allowed tenant.\
+ * If the user's tenant doesn't match, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param tenantId - Single tenant ID to allow
+ * @returns Event handler that validates user tenant
+ * @example
+ * // Single tenant:
+ * export default defineHandler({
+ *  middleware: [isUserFromAllowedTenant('t123456')],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ *
+ */
+declare function isUserFromAllowedTenant(tenantId: string): EventHandler;
+/**
+ * Middleware to check if the current user belongs to one of the allowed tenants.\
+ * If the user's tenant doesn't match any of the allowed tenants, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @param tenantIds - Array of tenant IDs to allow
+ * @returns Event handler that validates user tenant
+ * @example
+ * // Multiple tenants:
+ * export default defineHandler({
+ *  middleware: [isUserFromAllowedTenant(['t123456', 't789012'])],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ */
+declare function isUserFromAllowedTenant(tenantIds: string[]): EventHandler;
+/**
+ * Middleware to check if the current user belongs to the deployed tenant.\
+ * The deployed tenant is where this microservice is hosted (C8Y_BOOTSTRAP_TENANT).\
+ * If the user's tenant doesn't match the deployed tenant, throws a 403 Forbidden error.\
+ * Must be used within a request handler context.\
+ * @returns Event handler that validates user is from deployed tenant
+ * @example
+ * // Only allow users from the deployed tenant:
+ * export default defineHandler({
+ *  middleware: [isUserFromDeployedTenant()],
+ *  handler: async () => {
+ *   return { message: 'You have access' }
+ *  }
+ * })
+ */
+declare function isUserFromDeployedTenant(): EventHandler;
+//#endregion
+//#region src/utils/resources.d.ts
+/**
+ * Fetches the current user from Cumulocity using credentials extracted from the current request's headers.
+ * This is a non-cached version - fetches fresh data on every call.
+ * @param requestOrEvent - The H3Event or ServerRequest from the current request
+ * @returns The current user object from Cumulocity
+ * @example
+ * // In a request handler:
+ * const user = await useUser(event)
+ * console.log(user.userName, user.email)
+ */
+declare function useUser(requestOrEvent: ServerRequest | H3Event): Promise<ICurrentUser>;
+/**
+ * Fetches the roles of the current user from Cumulocity.
+ * Internally calls `useUser()` and extracts role IDs from the user object.
+ * This is a non-cached version - fetches fresh data on every call.
+ * @param requestOrEvent - The H3Event or ServerRequest from the current request
+ * @returns Array of role ID strings assigned to the current user
+ * @example
+ * // In a request handler:
+ * const roles = await useUserRoles(event)
+ * console.log(roles) // ['ROLE_INVENTORY_READ', 'ROLE_INVENTORY_ADMIN']
+ */
+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>>) & {
+  invalidate: () => Promise<void>;
+  refresh: () => Promise<Record<string, ICredentials>>;
+};
+/**
+ * Fetches credentials for the tenant where this microservice is deployed.\
+ * Uses the C8Y_BOOTSTRAP_TENANT environment variable to identify the deployed tenant.\
+ * Returns credentials from the subscribed tenant credentials cache (cached based on configured TTL, default: 10 minutes).
+ * @returns Credentials for the deployed tenant
+ * @throws {HTTPError} If no credentials found for the deployed tenant
+ * @example
+ * // Get deployed tenant credentials:
+ * const creds = await useDeployedTenantCredentials()
+ * console.log(creds.tenant, creds.user)
+ *
+ * // Invalidate cache:
+ * await useDeployedTenantCredentials.invalidate()
+ *
+ * // Force refresh:
+ * const freshCreds = await useDeployedTenantCredentials.refresh()
+ * @note This function is not cached separately. It uses the cache of `useSubscribedTenantCredentials()`. Invalidating or refreshing one will refresh `useDeployedTenantCredentials()`s cache.
+ */
+declare const useDeployedTenantCredentials: (() => Promise<ICredentials>) & {
+  invalidate: () => Promise<void>;
+  refresh: () => Promise<ICredentials>;
+};
+/**
+ * Fetches credentials for the tenant of the current user making the request.\
+ * Extracts the user's tenant ID from the request headers and returns corresponding credentials.\
+ * Results are cached in the request context for subsequent calls within the same request.
+ * @param requestOrEvent - The H3Event or ServerRequest from the current request
+ * @returns Credentials for the user's tenant
+ * @throws {HTTPError} If no subscribed tenant credentials found for the user's tenant
+ * @example
+ * // In a request handler:
+ * const userCreds = await useUserTenantCredentials(event)
+ * console.log(userCreds.tenant, userCreds.user)
+ *
+ * // Credentials are automatically cached for the request duration
+ * const sameCreds = await useUserTenantCredentials(event) // Uses cached value
+ */
+declare function useUserTenantCredentials(requestOrEvent: ServerRequest | H3Event): Promise<ICredentials>;
+//#endregion
+//#region src/utils/tenantOptions.d.ts
+/**
+ * Fetches a tenant option value by key.\
+ * Uses the deployed tenant's service user credentials to access the Options API.\
+ * Results are cached based on the configured TTL (default: 10 minutes).
+ *
+ * @param key - The tenant option key to fetch (as defined in `manifest.settings`)
+ * @returns The option value as a string
+ *
+ * @config Cache TTL can be configured via:
+ * - `c8y.cache.defaultTenantOptionsTTL` — Default TTL for all keys (in seconds)
+ * - `c8y.cache.tenantOptions` — Per-key TTL overrides
+ * - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
+ *
+ * @note For encrypted options (keys starting with `credentials.`), the value is automatically
+ * decrypted by Cumulocity if this microservice is the owner of the option (category matches
+ * the microservice's settingsCategory/contextPath/name). The `credentials.` prefix is
+ * automatically stripped when calling the API.
+ *
+ * @example
+ * // Fetch a tenant option:
+ * const value = await useTenantOption('myOption')
+ *
+ * // Fetch an encrypted secret:
+ * const secret = await useTenantOption('credentials.apiKey')
+ *
+ * // Invalidate cache for a specific key:
+ * await useTenantOption.invalidate('myOption')
+ *
+ * // Force refresh a specific key:
+ * const fresh = await useTenantOption.refresh('myOption')
+ *
+ * // Invalidate all tenant option caches:
+ * await useTenantOption.invalidateAll()
+ *
+ * // Refresh all tenant options:
+ * const all = await useTenantOption.refreshAll()
+ */
+declare const useTenantOption: ((key: C8YTenantOptionKey) => Promise<string | undefined>) & {
+  /**
+   * Invalidate the cache for a specific tenant option key.
+   * @param key - The tenant option key to invalidate
+   */
+  invalidate: (key: C8YTenantOptionKey) => Promise<void>;
+  /**
+   * Force refresh a specific tenant option key (invalidates and re-fetches).
+   * @param key - The tenant option key to refresh
+   */
+  refresh: (key: C8YTenantOptionKey) => Promise<string | undefined>;
+  /**
+   * Invalidate all tenant option caches that have been accessed.
+   * Only invalidates keys that have been fetched at least once.
+   */
+  invalidateAll: () => Promise<void>;
+  /**
+   * Refresh all tenant options that have been accessed.
+   * Only refreshes keys that have been fetched at least once.
+   * @returns Object mapping keys to their refreshed values
+   */
+  refreshAll: () => Promise<Record<string, string | undefined>>;
+};
+//#endregion
 export { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };