c8y-nitro 0.6.0 → 0.7.1

package/dist/utils.d.mts

@@ -1,11 +1,9 @@
-import { t as TenantCredentials } from "./credentials-9FO7rTIR.mjs";
-import { useLogger } from "evlog/nitro/v3";
+import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
 import { Client, ICredentials, ICurrentUser } from "@c8y/client";
-import { EventHandler, H3Event } from "nitro/h3";
-import { createError, createLogger } from "evlog";
+import { createError as createError$1, createLogger } from "evlog";
+import { EventHandler, H3Event, HTTPEvent } from "nitro/h3";
 import { ServerRequest, TaskContext, TaskPayload } from "nitro/types";
-import { C8YRoles, C8YTenantOptionKey } from "c8y-nitro/types";
-
+import { C8YRoles, C8YSettingsCategory, C8YTenantOptionKey } from "c8y-nitro/types";
 //#region src/utils/client.d.ts
 /**
  * Creates a Cumulocity client authenticated with the current user's credentials.\
@@ -173,7 +171,7 @@ declare const useSubscribedTenantCredentials: (() => Promise<TenantCredentials>)
  * 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
+ * @throws {EvlogError} If no credentials found for the deployed tenant
  * @example
  * // Get deployed tenant credentials:
  * const creds = await useDeployedTenantCredentials()
@@ -196,7 +194,7 @@ declare const useDeployedTenantCredentials: (() => Promise<ICredentials>) & {
  * 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
+ * @throws {EvlogError} If no subscribed tenant credentials found for the user's tenant
  * @example
  * // In a request handler:
  * const userCreds = await useUserTenantCredentials(event)
@@ -209,12 +207,148 @@ declare function useUserTenantCredentials(requestOrEvent: ServerRequest | H3Even
 //#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).
+ * A tenant option key for the microservice's own settings category.
  *
- * @param key - The tenant option key to fetch (as defined in `manifest.settings`)
- * @returns The option value as a string
+ * Manifest-declared keys are offered via autocomplete (from the generated
+ * {@link C8YTenantOptionKey} union) while any other string is still accepted, so
+ * runtime-computed keys such as `encrypted.password.${hash}` work too.
+ */
+type TenantOptionKeyInput = C8YTenantOptionKey | (string & {});
+/**
+ * Guards a key used against a *foreign* settings category.
+ *
+ * `credentials.*` options are stored encrypted and can only be decrypted within
+ * the owning microservice's category, so they can never be read from a different
+ * category. Such keys collapse to `never`, turning the misuse into a compile error.
+ */
+type ForeignTenantOptionKeyInput<K extends string> = K & (K extends `credentials.${string}` ? never : unknown);
+/**
+ * Options for {@link TenantOption.setEditable}.
+ */
+interface SetEditableOptions {
+  /**
+   * The tenant whose option `editable` flag is updated.
+   *
+   * Required by Cumulocity: the editable-flag endpoint is only permitted from
+   * the management tenant, and the target tenant must be given explicitly.
+   */
+  targetTenant: string;
+}
+/**
+ * Handle for a single tenant option (a `category` + `key` pair).
+ *
+ * Obtained via {@link useTenantOption} (own category) or
+ * `useTenantOptions(category).option(key)`.
+ */
+interface TenantOption {
+  /**
+   * Read the current value. Returns `undefined` when the option is not set
+   * (Cumulocity responds `404`). The value is cached per the configured TTL.
+   */
+  read: () => Promise<string | undefined>;
+  /**
+   * Create or update the option value (upsert), then invalidate the cached read.
+   */
+  set: (value: string) => Promise<void>;
+  /**
+   * Read the value; if it is not set, write `fallback` and return it.
+   */
+  getOrInsert: (fallback: string) => Promise<string>;
+  /**
+   * Delete the option. Idempotent — a missing option resolves without error.
+   * Invalidates the cached read afterwards.
+   */
+  delete: () => Promise<void>;
+  /**
+   * Update the option's `editable` flag.
+   *
+   * @remarks Cumulocity only allows this from the **management tenant** (role
+   * `ROLE_OPTION_MANAGEMENT_ADMIN`). It will fail with `403` when called from a
+   * regular subscribed-tenant microservice.
+   */
+  setEditable: (editable: boolean, options: SetEditableOptions) => Promise<void>;
+  /**
+   * Invalidate the cached value, then re-read it.
+   */
+  refresh: () => Promise<string | undefined>;
+  /**
+   * Invalidate the cached value (no-op if it was never read).
+   */
+  invalidate: () => Promise<void>;
+}
+/**
+ * Handle for all options within the microservice's own settings category.
+ */
+interface TenantOptionCategory {
+  /**
+   * Get a handle for a single option in this category.
+   */
+  option: (key: TenantOptionKeyInput) => TenantOption;
+  /**
+   * List all options set in this category as a key/value map.
+   */
+  list: () => Promise<Record<string, string>>;
+  /**
+   * Create or update multiple options in this category, then invalidate their caches.
+   */
+  setAll: (values: Record<string, string>) => Promise<void>;
+  /**
+   * Invalidate every already-read option cache in this category.
+   */
+  invalidateAll: () => Promise<void>;
+  /**
+   * Refresh every already-read option cache in this category.
+   * @returns A map of the refreshed keys to their new values.
+   */
+  refreshAll: () => Promise<Record<string, string | undefined>>;
+}
+/**
+ * Handle for a *foreign* settings category (one other than the microservice's own).
+ *
+ * Identical to {@link TenantOptionCategory} except that:
+ * - `credentials.*` keys are rejected — see {@link ForeignTenantOptionKeyInput};
+ * - the optional type parameter `K` sets the known key set for autocomplete
+ *   (`useTenantOptions<'a' | 'b'>(client, 'other')`). It defaults to `string`,
+ *   which accepts any key (still minus `credentials.*`).
+ */
+interface ForeignTenantOptionCategory<K extends string = string> {
+  /**
+   * Get a handle for a single non-`credentials.*` option in this category.
+   * Completes to `K` when a key set was provided.
+   */
+  option: <Key extends K>(key: ForeignTenantOptionKeyInput<Key>) => TenantOption;
+  /**
+   * List all options set in this category as a key/value map.
+   */
+  list: () => Promise<Record<string, string>>;
+  /**
+   * Create or update multiple options in this category, then invalidate their caches.
+   */
+  setAll: (values: Record<string, string>) => Promise<void>;
+  /**
+   * Invalidate every already-read option cache in this category.
+   */
+  invalidateAll: () => Promise<void>;
+  /**
+   * Refresh every already-read option cache in this category.
+   * @returns A map of the refreshed keys to their new values.
+   */
+  refreshAll: () => Promise<Record<string, string | undefined>>;
+}
+/**
+ * Gets a handle for a single tenant option in the microservice's **own** settings
+ * category, targeting the tenant of the given `client`.\
+ * Reads are cached per tenant, using the client's service user credentials.
+ *
+ * This is a shortcut for `useTenantOptions(client).option(key)` — it only drops
+ * the category argument. For a single option in a **foreign** category, use
+ * `useTenantOptions(client, category).option(key)`.
+ *
+ * Manifest-declared keys are offered via autocomplete, but any dynamic string
+ * is accepted too (e.g. `encrypted.password.${hash}`).
+ *
+ * @param client - The Cumulocity client that determines the target tenant
+ * @param key - The tenant option key
  *
  * @config Cache TTL can be configured via:
  * - `c8y.cache.defaultTenantOptionsTTL` — Default TTL for all keys (in seconds)
@@ -222,47 +356,151 @@ declare function useUserTenantCredentials(requestOrEvent: ServerRequest | H3Even
  * - `NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL` — Environment variable for default TTL
  *
  * @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')
+ * // Read the owner tenant's config:
+ * const value = await useTenantOption(await useDeployedTenantClient(), 'featureMode').read()
  *
- * // Force refresh a specific key:
- * const fresh = await useTenantOption.refresh('myOption')
+ * // Read the current request tenant's config (multi-tenant):
+ * const value = await useTenantOption(await useUserTenantClient(event), 'featureMode').read()
  *
- * // Invalidate all tenant option caches:
- * await useTenantOption.invalidateAll()
- *
- * // Refresh all tenant options:
- * const all = await useTenantOption.refreshAll()
+ * // Create or update, or seed a dynamic key:
+ * await useTenantOption(client, 'featureMode').set('advanced')
+ * const token = await useTenantOption(client, `encrypted.password.${hash}`).getOrInsert('')
+ */
+declare function useTenantOption(client: Client, key: TenantOptionKeyInput): TenantOption;
+/**
+ * @internal
  */
-declare const useTenantOption: ((key: C8YTenantOptionKey) => Promise<string | undefined>) & {
+interface UseTenantOptions {
   /**
-   * Invalidate the cache for a specific tenant option key.
-   * @param key - The tenant option key to invalidate
+   * Handle for the client tenant's own settings category.
    */
-  invalidate: (key: C8YTenantOptionKey) => Promise<void>;
+  (client: Client): TenantOptionCategory;
   /**
-   * Force refresh a specific tenant option key (invalidates and re-fetches).
-   * @param key - The tenant option key to refresh
+   * Handle for the client tenant's own settings category (given explicitly).
    */
-  refresh: (key: C8YTenantOptionKey) => Promise<string | undefined>;
+  (client: Client, category: C8YSettingsCategory): TenantOptionCategory;
   /**
-   * Invalidate all tenant option caches that have been accessed.
-   * Only invalidates keys that have been fetched at least once.
+   * Handle for a foreign settings category (`credentials.*` keys are rejected).
+   *
+   * Provide the key set as a type argument for autocomplete, e.g.
+   * `useTenantOptions<'featureA' | 'featureB'>(client, 'other-service')`.
+   * Supplying a type argument also explicitly selects this overload.
+   */
+  <K extends string = string>(client: Client, category: string): ForeignTenantOptionCategory<K>;
+  /**
+   * Invalidate every already-read option cache, across all tenants and categories.
    */
   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
+   * Refresh every already-read option cache, across all tenants and categories.
+   * @returns Map of `${tenant}::${category}::${key}` store keys to their refreshed values.
    */
   refreshAll: () => Promise<Record<string, string | undefined>>;
-};
+}
+/**
+ * Gets a handle for a whole settings category, targeting the tenant of the given
+ * `client`.\
+ * Omit the category (or pass the own {@link C8YSettingsCategory}) for the
+ * microservice's own category; pass any other category to read/write options in
+ * a foreign category (where `credentials.*` keys are rejected).
+ *
+ * @param client - The Cumulocity client that determines the target tenant
+ *
+ * @example
+ * const client = await useUserTenantClient(event)
+ *
+ * // Own category:
+ * const values = await useTenantOptions(client).list()
+ * await useTenantOptions(client).option('featureMode').set('advanced')
+ *
+ * // Foreign category:
+ * const value = await useTenantOptions(client, 'other-service').option('someKey').read()
+ *
+ * // Invalidate all cached options of one tenant + category:
+ * await useTenantOptions(client, 'other-service').invalidateAll()
+ *
+ * // Invalidate everything, across all tenants and categories:
+ * await useTenantOptions.invalidateAll()
+ */
+declare const useTenantOptions: UseTenantOptions;
+//#endregion
+//#region src/utils/logging.d.ts
+/**
+ * Returns the request-scoped wide-event logger for the current request.
+ *
+ * Accepts **either** an `H3Event` (as received by a route handler) **or** the
+ * `ServerRequest` returned by Nitro's `useRequest()` — both carry the same
+ * request context, so `useLogger(event)` and `useLogger(useRequest())` are
+ * equivalent.
+ *
+ * evlog's own `useLogger` only accepts an `H3Event` and reads the logger from
+ * `event.req.context.log`; `useRequest()` returns that `ServerRequest` directly
+ * (no `.req`), which would throw. This wrapper normalizes both shapes to the
+ * `{ req }` event evlog expects, restoring the accept-both behavior.
+ *
+ * @param eventOrRequest - The current `H3Event` or `ServerRequest` (`useRequest()`).
+ * @param service - Optional service name to override the default.
+ * @example
+ * // In a route handler:
+ * const log = useLogger(event)
+ *
+ * // Deeper in the call stack with experimental.asyncContext enabled:
+ * import { useRequest } from 'nitro/context'
+ * const log = useLogger(useRequest())
+ */
+declare function useLogger<T extends object = Record<string, unknown>>(eventOrRequest: HTTPEvent | ServerRequest, service?: string): import("evlog").AuditableLogger<T>;
+/**
+ * Create a structured error for a Cumulocity microservice. Always prefer this
+ * over Nitro/h3's built-in `createError`: the returned error is captured in the
+ * wide log event **and** serialized into the JSON response under a `data` key.
+ *
+ * ## What the caller sees vs what stays on the server
+ *
+ * Every field **except `internal`** is sent to the client in the HTTP response.
+ * `internal` is stripped from the response and only ever appears in your logs.
+ *
+ * | Field      | Sent to client? | Purpose                                                       |
+ * | ---------- | :-------------: | ------------------------------------------------------------- |
+ * | `message`  |       yes       | Short, safe summary of what went wrong.                       |
+ * | `status`   |       yes       | HTTP status code (default `500`).                             |
+ * | `code`     |       yes       | Stable machine-readable id (e.g. `'PAYMENT_DECLINED'`).       |
+ * | `why`      |       yes       | Human-readable cause — safe to expose, no secrets.            |
+ * | `fix`      |       yes       | What the caller can do about it.                              |
+ * | `link`     |       yes       | Docs URL with more detail.                                    |
+ * | `cause`    |  no (logged)    | The original `Error` you caught.                              |
+ * | `internal` |  no (logged)    | Backend-only diagnostics — never reaches the client.          |
+ *
+ * ## Do NOT leak internal system errors
+ *
+ * Put anything sensitive or diagnostic (raw Cumulocity core responses, DB
+ * errors, tokens, tenant internals) in `internal`, **not** in `message`/`why`.
+ * `internal` is logged for debugging but never serialized to the response.
+ *
+ * @example
+ * // User-facing error — every field here is visible to the caller:
+ * throw createError({
+ *   code: 'PAYMENT_DECLINED',
+ *   message: 'Payment failed',
+ *   status: 402,
+ *   why: 'Card declined by issuer',
+ *   fix: 'Try a different payment method',
+ *   link: 'https://docs.example.com/payments/declined',
+ * })
+ *
+ * @example
+ * // Wrapping an upstream failure — keep the raw payload server-side only:
+ * catch (cause) {
+ *   throw createError({
+ *     status: 502,
+ *     message: 'Upstream request failed', // safe, generic — what the caller sees
+ *     cause: cause as Error,
+ *     internal: { upstreamStatus: cause?.res?.status, upstreamBody: cause?.data },
+ *   })
+ * }
+ *
+ * @see https://www.evlog.dev
+ */
+declare const createError: typeof createError$1;
 //#endregion
 //#region src/utils/schedule.d.ts
 type ScheduledTaskPayload = TaskPayload;
@@ -370,4 +608,4 @@ declare function listScheduledTasks(): Promise<Record<string, ScheduledTaskInfo>
  */
 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 };
+export { ForeignTenantOptionCategory, ForeignTenantOptionKeyInput, ScheduleTaskOptions, ScheduledTaskContext, ScheduledTaskInfo, ScheduledTaskInput, ScheduledTaskPayload, SetEditableOptions, TenantOption, TenantOptionCategory, TenantOptionKeyInput, cancelScheduledTask, createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, listScheduledTasks, scheduleTask, useDeployedTenantClient, useDeployedTenantCredentials, useLogger, useSubscribedTenantClients, useSubscribedTenantCredentials, useTenantOption, useTenantOptions, useUser, useUserClient, useUserRoles, useUserTenantClient, useUserTenantCredentials };