c8y-nitro 0.1.0

package/dist/module/register.mjs

@@ -0,0 +1,58 @@
+import { GENERATED_LIVENESS_ROUTE, GENERATED_READINESS_ROUTE } from "./constants.mjs";
+import { join } from "pathe";
+import { fileURLToPath } from "node:url";
+
+//#region src/module/register.ts
+/**
+* Links runtime middleware, handlers, and plugins to the nitro instance.
+* Works by having the handlers in a relative path to this file.
+* Needs to be the same when built.
+* @param nitro - Nitro instance
+* @param options - C8yNitroModuleOptions
+*/
+function registerRuntime(nitro, options = {}) {
+	const thisFilePath = fileURLToPath(new URL(".", import.meta.url));
+	/**
+	* Plugins
+	*/
+	const plugins = [];
+	const c8yVariablesPluginPath = join(thisFilePath, "./runtime/plugins/c8y-variables");
+	plugins.push(c8yVariablesPluginPath);
+	nitro.options.plugins.push(...plugins);
+	/**
+	* Middlewares (global)
+	*/
+	const middlewares = [];
+	const devUserMiddlewarePath = join(thisFilePath, "./runtime/middlewares/dev-user");
+	middlewares.push(devUserMiddlewarePath);
+	nitro.options.handlers.push(...middlewares.map((handler) => ({
+		route: "/**",
+		handler,
+		middleware: true
+	})));
+	/**
+	* Handlers
+	*/
+	const handlers = [];
+	const probeHandlerPath = join(thisFilePath, "./runtime/handlers/liveness-readiness");
+	if (!options.manifest?.livenessProbe?.httpGet) {
+		handlers.push({
+			route: GENERATED_LIVENESS_ROUTE,
+			handler: probeHandlerPath,
+			method: "GET"
+		});
+		nitro.logger.debug(`Generated liveness probe at ${GENERATED_LIVENESS_ROUTE}`);
+	} else nitro.logger.debug("Liveness probe httpGet defined by user; skipping generation");
+	if (!options.manifest?.readinessProbe?.httpGet) {
+		handlers.push({
+			route: GENERATED_READINESS_ROUTE,
+			handler: probeHandlerPath,
+			method: "GET"
+		});
+		nitro.logger.debug(`Generated readiness probe at ${GENERATED_READINESS_ROUTE}`);
+	} else nitro.logger.debug("Readiness probe httpGet defined by user; skipping generation");
+	nitro.options.handlers.push(...handlers);
+}
+
+//#endregion
+export { registerRuntime };

package/dist/module/runtime/handlers/liveness-readiness.ts

@@ -0,0 +1,7 @@
+import { defineEventHandler } from 'nitro/h3'
+
+export default defineEventHandler(async () => {
+  return {
+    status: 'OK',
+  }
+})

package/dist/module/runtime/middlewares/dev-user.ts

@@ -0,0 +1,25 @@
+import { defineHandler } from 'nitro/h3'
+import process from 'node:process'
+import { Buffer } from 'node:buffer'
+import consola from 'consola'
+
+// Middleware to inject a development c8y user into the request during development mode
+export default defineHandler((event) => {
+  if (import.meta.dev) {
+    // in development mode, we check for a development user to inject into the request
+    // this is necessary to correctly use auth middlewares during development
+    const requiredDevEnvVars = ['C8Y_DEVELOPMENT_TENANT', 'C8Y_DEVELOPMENT_USER', 'C8Y_DEVELOPMENT_PASSWORD']
+    const missingDevVars = requiredDevEnvVars.filter((varName) => !process.env[varName])
+    if (missingDevVars.length > 0) {
+      consola.warn(`Missing development environment variables: ${missingDevVars.join(', ')}. Dev user injection will be skipped. Routes requiring authentication or roles will fail.`)
+    } else {
+      // build basic auth header in form "tenant/user:password"
+      const authString = `${process.env.C8Y_DEVELOPMENT_TENANT}/${process.env.C8Y_DEVELOPMENT_USER}:${process.env.C8Y_DEVELOPMENT_PASSWORD}`
+      const encodedAuth = Buffer.from(authString).toString('base64')
+      const authHeader = `Basic ${encodedAuth}`
+
+      // inject auth header into request
+      event.req.headers.set('authorization', authHeader)
+    }
+  }
+})

package/dist/module/runtime/plugins/c8y-variables.ts

@@ -0,0 +1,24 @@
+import { definePlugin } from 'nitro'
+import process from 'node:process'
+
+export default definePlugin(() => {
+  if (import.meta.dev) {
+    const env = process.env
+
+    const requiredVars = ['C8Y_BASEURL', 'C8Y_BOOTSTRAP_TENANT', 'C8Y_BOOTSTRAP_USER', 'C8Y_BOOTSTRAP_PASSWORD']
+    const missingVars = requiredVars.filter((varName) => !env[varName])
+
+    if (missingVars.length > 0) {
+      throw new Error(
+        `Missing required environment variables for development: ${missingVars.join(', ')}\n\n`
+        + `To set up your development environment, run:\n`
+        + `  npx c8y-nitro bootstrap\n\n`
+        + `This 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\n`
+        + `Make sure you have your development tenant credentials configured first.`,
+      )
+    }
+  }
+})

package/dist/module/runtime.mjs

@@ -0,0 +1,31 @@
+import { join } from "pathe";
+import { mkdirSync, writeFileSync } from "fs";
+
+//#region src/module/runtime.ts
+function setupRuntime(nitro, manifestOptions = {}) {
+	nitro.logger.debug("Setting up C8Y nitro runtime");
+	const roles = manifestOptions.roles ?? [];
+	const completeTypesDir = join(nitro.options.rootDir, nitro.options.typescript.generatedTypesDir ?? "node_modules/.nitro/types");
+	const rolesTypeFile = join(completeTypesDir, "c8y-nitro-roles.d.ts");
+	const rolesTypeContent = `// generated by c8y-nitro
+declare module 'c8y-nitro/types' {
+  interface C8YRoles {
+${roles.map((role) => `    '${role}': '${role}';`).join("\n")}
+  }
+}
+declare module 'c8y-nitro/runtime' {
+  import type { C8YRoles } from 'c8y-nitro/types';
+  export const c8yRoles: C8YRoles;
+}`;
+	nitro.options.virtual["c8y-nitro/runtime"] = `
+export const c8yRoles = {
+${roles.map((role) => `  '${role}': '${role}',`).join("\n")}
+}
+`;
+	mkdirSync(completeTypesDir, { recursive: true });
+	writeFileSync(rolesTypeFile, rolesTypeContent, { encoding: "utf-8" });
+	nitro.logger.debug(`Written C8Y roles types to ${rolesTypeFile}`);
+}
+
+//#endregion
+export { setupRuntime };

package/dist/package.mjs

@@ -0,0 +1,7 @@
+//#region package.json
+var name = "c8y-nitro";
+var version = "0.1.0";
+var description = "Lightning fast Cumulocity IoT microservice development powered by Nitro";
+
+//#endregion
+export { description, name, version };

package/dist/types/apiClient.d.mts

@@ -0,0 +1,16 @@
+//#region src/types/apiClient.d.ts
+interface C8YAPIClientOptions {
+  /**
+   * Relative directory from nitro configuration file to generate the API client into.
+   */
+  dir: string;
+  /**
+   * Service context path for microservice endpoints.\
+   * Defaults to contextPath from manifest (package.json name, with scope stripped).\
+   * Override this if deploying with a different context path.
+   * @example "my-microservice" results in "https://<tenant>.com/service/my-microservice/..."
+   */
+  contextPath?: string;
+}
+//#endregion
+export { C8YAPIClientOptions };

package/dist/types/manifest.d.mts

@@ -0,0 +1,323 @@
+//#region src/types/manifest.d.ts
+type C8YManifestOptions = Partial<Omit<C8YManifest, 'name' | 'version' | 'apiVersion' | 'key'>>;
+interface C8YManifest {
+  /**
+   * API version (e.g., "v2", "2"). Version 2 required for enhanced container security.
+   * Automatically set by the module to "v2".
+   */
+  apiVersion: string;
+  /**
+   * Unique microservice key
+   */
+  key: string;
+  /**
+   * Type of Cumulocity application. For microservices, always "MICROSERVICE".
+   * Technically can be "HOSTED" or "EXTERNAL" as well, but those are not supported here.
+   */
+  type: 'MICROSERVICE';
+  /**
+   * Microservice name (lowercase a-z, digits, hyphens, max 23 chars).
+   * Automatically populated from package.json name.
+   */
+  name: string;
+  /**
+   * SemVer version (no "+" allowed). Use "-SNAPSHOT" suffix for dev builds.
+   * Automatically populated from package.json version.
+   */
+  version: string;
+  /**
+   * URL path prefix for your microservice endpoints.
+   * Letters, digits, hyphens, dots, underscores, tildes allowed.
+   * Defaults to package.json name. "my-service" results in endpoints like "/service/my-service/..."
+   * @example "my-service"
+   */
+  contextPath?: string;
+  /**
+   * Company/organization information.
+   */
+  provider: Provider;
+  /**
+   * Billing strategy:
+   * - RESOURCES: Tenants pay per usage
+   * - SUBSCRIPTION: Owner pays, tenants pay flat subscription
+   * @default "RESOURCES"
+   */
+  billingMode?: 'RESOURCES' | 'SUBSCRIPTION';
+  /**
+   * Container sharing strategy:
+   * - MULTI_TENANT: One container serves all tenants (cost efficient)
+   * - PER_TENANT: Separate container per tenant (data isolation)
+   * @default "MULTI_TENANT"
+   */
+  isolation?: 'MULTI_TENANT' | 'PER_TENANT';
+  /**
+   * Auto-scaling based on CPU:
+   * - NONE: Fixed instance count
+   * - AUTO: Scales up/down automatically
+   * @default "NONE"
+   */
+  scale?: 'AUTO' | 'NONE';
+  /**
+   * Number of container instances (1-5).
+   * For AUTO scale: minimum count. Use 2+ for production.
+   * @default 1
+   */
+  replicas?: number;
+  /**
+   * Maximum resources (hard limits).
+   * Container killed if exceeded.
+   */
+  resources?: Resources;
+  /**
+   * Minimum resources (guaranteed reservation).
+   * Platform ensures availability.
+   */
+  requestedResources?: RequestedResources;
+  /**
+   * Runtime configuration exposed to tenants.
+   * Allows customization without redeployment.
+   */
+  settings?: Option[];
+  /**
+   * Category for grouping settings (letters, digits, dots).
+   * @default contextPath
+   */
+  settingsCategory?: string;
+  /**
+   * Permissions granted to microservice service user.
+   * Needed to access Cumulocity APIs (inventory, alarms, etc.).
+   * @example ["ROLE_ALARM_READ", "ROLE_INVENTORY_ADMIN"]
+   */
+  requiredRoles?: string[];
+  /**
+   * New permissions provided by this microservice.
+   * Users can be assigned these to access your endpoints.
+   * @example ["ROLE_MY_SERVICE_READ", "ROLE_MY_SERVICE_ADMIN"]
+   */
+  roles?: string[];
+  /**
+   * Health check for crashed/frozen containers.
+   * Fails trigger restart. Recommended for production.
+   */
+  livenessProbe?: Probe;
+  /**
+   * Health check for readiness to serve traffic.
+   * Fails prevent routing. Recommended for production.
+   */
+  readinessProbe?: Probe;
+  /**
+   * Platform extensions (e.g., UI plugins).
+   */
+  extensions?: Extension[];
+}
+/**
+ * Company/organization information.
+ */
+interface Provider {
+  /**
+   * Company name ("c8y" for Cumulocity).
+   * Defaults to package.json author ?? author.name
+   */
+  name: string;
+  /**
+   * Company website.
+   * Defaults to package.json author.url ?? homepage.
+   */
+  domain?: string;
+  /**
+   * Support link or email.
+   * Defaults to package.json bugs.url ?? bugs.email ?? author.email.
+   */
+  support?: string;
+}
+/**
+ * Maximum resource limits (hard caps).
+ */
+interface Resources {
+  /**
+   * CPU cores ("1", "0.5") or millicores ("500m").
+   * 1 core = 1000m. Min: "0.1" or "100m".
+   * @default  "0.5"
+   * @example "1" | "500m"
+   */
+  cpu?: string;
+  /**
+   * Max memory before kill. Units: E, P, T, G, M, K, Ei, Pi, Ti, Gi, Mi, Ki.
+   * Min: "10M".
+   * @default "512M"
+   * @example "1G" | "512M"
+   */
+  memory?: string;
+}
+/**
+ * Minimum resources (guaranteed reservation).
+ */
+interface RequestedResources {
+  /**
+   * Min CPU guaranteed (millicores typical).
+   * @default "250m".
+   * @example "100m" | "250m"
+   */
+  cpu?: string;
+  /**
+   * Min memory guaranteed. Units: E, P, T, G, M, K, Ei, Pi, Ti, Gi, Mi, Ki.
+   * @default "256M".
+   * @example "128Mi" | "256M"
+   */
+  memory?: string;
+}
+/**
+ * Runtime configuration option for tenants.
+ */
+interface Option {
+  /**
+   * Unique setting identifier.
+   * @example "tracker-id"
+   */
+  key: string;
+  /**
+   * Initial value if not overridden.
+   * @example "1234"
+   */
+  defaultValue?: string;
+  /**
+   * Allow tenants to modify at runtime.
+   * @default false
+   */
+  editable?: boolean;
+  /**
+   * Reset editable value on microservice update.
+   * @default true
+   */
+  overwriteOnUpdate?: boolean;
+  /**
+   * Inherit value from owner tenant.
+   * @default true
+   */
+  inheritFromOwner?: boolean;
+}
+/**
+ * Health check probe configuration.
+ */
+interface Probe {
+  /**
+   * Execute command in container. Success = exit code 0.
+   */
+  exec?: ExecAction;
+  /**
+   * TCP connection attempt. Success = connection established.
+   */
+  tcpSocket?: TCPSocketAction;
+  /**
+   * HTTP request. Success = 200-399 status code.
+   */
+  httpGet?: HTTPGetAction;
+  /**
+   * Seconds before first probe (startup grace period).
+   * @default 0
+   * @example 60
+   */
+  initialDelaySeconds?: number;
+  /**
+   * Seconds between probes.
+   * @default 10
+   */
+  periodSeconds?: number;
+  /**
+   * Consecutive successes to consider healthy.
+   * @default 1
+   */
+  successThreshold?: number;
+  /**
+   * Seconds before probe times out.
+   * @default 1
+   */
+  timeoutSeconds?: number;
+  /**
+   * Consecutive failures before action (restart/stop routing).
+   * @default 3
+   */
+  failureThreshold?: number;
+}
+/**
+ * Execute command probe.
+ */
+interface ExecAction {
+  /**
+   * Command and arguments to execute.
+   * @example ["cat", "/tmp/healthy"]
+   */
+  command: string[];
+}
+/**
+ * TCP socket probe.
+ */
+interface TCPSocketAction {
+  /**
+   * Hostname or IP to connect to.
+   */
+  host: string;
+  /**
+   * Port number to connect to.
+   * @default 80
+   */
+  port: number;
+}
+/**
+ * HTTP GET probe.
+ */
+interface HTTPGetAction {
+  /**
+   * Hostname to connect to.
+   */
+  host?: string;
+  /**
+   * URL path to request.
+   * @example "/health"
+   */
+  path: string;
+  /**
+   * Port to connect to.
+   * @default 80
+   */
+  port?: number;
+  /**
+   * Protocol to use.
+   * @default "HTTP"
+   */
+  scheme?: 'HTTP' | 'HTTPS';
+  /**
+   * Custom HTTP headers.
+   */
+  headers?: HttpHeader[];
+}
+/**
+ * HTTP header for probes.
+ */
+interface HttpHeader {
+  /**
+   * Header name.
+   * @example "Authorization"
+   */
+  name: string;
+  /**
+   * Header value.
+   * @example "Bearer token"
+   */
+  value: string;
+}
+/**
+ * Platform extension configuration.
+ */
+interface Extension {
+  /**
+   * Extension type identifier.
+   */
+  type: string;
+  /**
+   * Extension-specific config.
+   */
+  [key: string]: unknown;
+}
+//#endregion
+export { C8YManifestOptions };

package/dist/types/roles.d.mts

@@ -0,0 +1,4 @@
+//#region src/types/roles.d.ts
+interface C8YRoles {}
+//#endregion
+export { C8YRoles };

package/dist/types/zip.d.mts

@@ -0,0 +1,22 @@
+import { C8YManifestOptions } from "./manifest.mjs";
+
+//#region src/types/zip.d.ts
+interface C8YZipOptions {
+  /**
+   * Name of the generated zip file
+   * @default '${packageName}-${version}.zip'
+   */
+  name?: string | ((packageName: string, version: string) => string);
+  /**
+   * Output directory for the generated zip file.\
+   * Relative to the config file.
+   * @default './'
+   */
+  outputDir?: string;
+  /**
+   * Configuration of the "cumulocity.json" manifest file used for the zip.
+   */
+  manifest?: C8YManifestOptions;
+}
+//#endregion
+export { C8YZipOptions };

package/dist/types.d.mts

@@ -0,0 +1,13 @@
+import { C8YAPIClientOptions } from "./types/apiClient.mjs";
+import { C8YManifestOptions } from "./types/manifest.mjs";
+import { C8YZipOptions } from "./types/zip.mjs";
+import { C8YRoles } from "./types/roles.mjs";
+
+//#region src/types/index.d.ts
+interface C8yNitroModuleOptions {
+  manifest?: C8YManifestOptions;
+  apiClient?: C8YAPIClientOptions;
+  zip?: C8YZipOptions;
+}
+//#endregion
+export { C8YAPIClientOptions, type C8YManifestOptions, C8YRoles, C8YZipOptions, C8yNitroModuleOptions };

package/dist/types.mjs

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

package/dist/utils/client.d.mts

@@ -0,0 +1,50 @@
+import { Client } from "@c8y/client";
+
+//#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.\
+ * Must be called within a request handler context.\
+ * @returns A configured Cumulocity Client instance
+ * @example
+ * // In a request handler:
+ * const client = useUserClient()
+ * const { data } = await client.inventory.list()
+ */
+declare function useUserClient(): 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.\
+ * Must be called within a request handler context.\
+ * @returns A configured Cumulocity Client instance for the user's tenant
+ * @example
+ * // In a request handler:
+ * const tenantClient = await useUserTenantClient()
+ * const { data } = await tenantClient.inventory.list()
+ */
+declare function useUserTenantClient(): 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
+export { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, useUserTenantClient };

package/dist/utils/client.mjs

@@ -0,0 +1,91 @@
+import { convertRequestHeadersToC8yFormat } from "./internal/common.mjs";
+import { useSubscribedTenantCredentials } from "./credentials.mjs";
+import process from "node:process";
+import { BasicAuth, Client, MicroserviceClientRequestAuth } from "@c8y/client";
+import { useRequest } from "nitro/context";
+import { HTTPError } from "nitro/h3";
+
+//#region src/utils/client.ts
+/**
+* Creates a Cumulocity client authenticated with the current user's credentials.\
+* Extracts credentials from the Authorization header of the current request.\
+* Must be called within a request handler context.\
+* @returns A configured Cumulocity Client instance
+* @example
+* // In a request handler:
+* const client = useUserClient()
+* const { data } = await client.inventory.list()
+*/
+function useUserClient() {
+	const request = useRequest();
+	if (request.context?.["c8y_user_client"]) return request.context["c8y_user_client"];
+	const client = new Client(new MicroserviceClientRequestAuth(convertRequestHeadersToC8yFormat(request)), process.env.C8Y_BASEURL);
+	request.context ??= {};
+	request.context["c8y_user_client"] = client;
+	return 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.\
+* Must be called within a request handler context.\
+* @returns A configured Cumulocity Client instance for the user's tenant
+* @example
+* // In a request handler:
+* const tenantClient = await useUserTenantClient()
+* const { data } = await tenantClient.inventory.list()
+*/
+async function useUserTenantClient() {
+	const request = useRequest();
+	if (request.context?.["c8y_user_tenant_client"]) return request.context["c8y_user_tenant_client"];
+	const tenantId = useUserClient().core.tenant;
+	const creds = await useSubscribedTenantCredentials();
+	if (!creds[tenantId]) throw new HTTPError({
+		message: `No subscribed tenant credentials found for user tenant '${tenantId}'`,
+		status: 500,
+		statusText: "Internal Server Error"
+	});
+	const tenantClient = new Client(new BasicAuth(creds[tenantId]), process.env.C8Y_BASEURL);
+	request.context ??= {};
+	request.context["c8y_user_tenant_client"] = tenantClient;
+	return tenantClient;
+}
+/**
+* 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`)
+* }
+*/
+async function useSubscribedTenantClients() {
+	const creds = await useSubscribedTenantCredentials();
+	const clients = {};
+	for (const [tenant, tenantCreds] of Object.entries(creds)) clients[tenant] = new Client(new BasicAuth(tenantCreds), process.env.C8Y_BASEURL);
+	return clients;
+}
+/**
+* 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()
+*/
+async function useDeployedTenantClient() {
+	const creds = await useSubscribedTenantCredentials();
+	const tenant = process.env.C8Y_BOOTSTRAP_TENANT;
+	if (!creds[tenant]) throw new HTTPError({
+		message: `No subscribed tenant credentials found for tenant '${tenant}'`,
+		status: 500,
+		statusText: "Internal Server Error"
+	});
+	return new Client(new BasicAuth(creds[tenant]), process.env.C8Y_BASEURL);
+}
+
+//#endregion
+export { useDeployedTenantClient, useSubscribedTenantClients, useUserClient, useUserTenantClient };