c8y-nitro 0.5.0 → 0.7.0

package/dist/utils.d.mts

@@ -1,10 +1,10 @@
+import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.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";
-
+import { EventHandler, H3Event } from "nitro/h3";
+import { ServerRequest, TaskContext, TaskPayload } from "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.\
@@ -163,38 +163,16 @@ 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.\
  * 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()
@@ -217,7 +195,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)
@@ -230,12 +208,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)
@@ -243,46 +357,178 @@ 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')
+ * // Read the owner tenant's config:
+ * const value = await useTenantOption(await useDeployedTenantClient(), 'featureMode').read()
+ *
+ * // Read the current request tenant's config (multi-tenant):
+ * const value = await useTenantOption(await useUserTenantClient(event), 'featureMode').read()
+ *
+ * // 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
+ */
+interface UseTenantOptions {
+  /**
+   * Handle for the client tenant's own settings category.
+   */
+  (client: Client): TenantOptionCategory;
+  /**
+   * Handle for the client tenant's own settings category (given explicitly).
+   */
+  (client: Client, category: C8YSettingsCategory): TenantOptionCategory;
+  /**
+   * 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 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
  *
- * // Fetch an encrypted secret:
- * const secret = await useTenantOption('credentials.apiKey')
+ * @example
+ * const client = await useUserTenantClient(event)
  *
- * // Invalidate cache for a specific key:
- * await useTenantOption.invalidate('myOption')
+ * // Own category:
+ * const values = await useTenantOptions(client).list()
+ * await useTenantOptions(client).option('featureMode').set('advanced')
  *
- * // Force refresh a specific key:
- * const fresh = await useTenantOption.refresh('myOption')
+ * // Foreign category:
+ * const value = await useTenantOptions(client, 'other-service').option('someKey').read()
  *
- * // Invalidate all tenant option caches:
- * await useTenantOption.invalidateAll()
+ * // Invalidate all cached options of one tenant + category:
+ * await useTenantOptions(client, 'other-service').invalidateAll()
  *
- * // Refresh all tenant options:
- * const all = await useTenantOption.refreshAll()
+ * // Invalidate everything, across all tenants and categories:
+ * await useTenantOptions.invalidateAll()
+ */
+declare const useTenantOptions: UseTenantOptions;
+//#endregion
+//#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.
  */
-declare const useTenantOption: ((key: C8YTenantOptionKey) => Promise<string | undefined>) & {
+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 {
   /**
-   * Invalidate the cache for a specific tenant option key.
-   * @param key - The tenant option key to invalidate
+   * Payload forwarded to the task handler's `TaskEvent.payload`.
    */
-  invalidate: (key: C8YTenantOptionKey) => Promise<void>;
+  payload?: ScheduledTaskPayload;
   /**
-   * Force refresh a specific tenant option key (invalidates and re-fetches).
-   * @param key - The tenant option key to refresh
+   * Context forwarded to the task handler's `TaskEvent.context`.
    */
-  refresh: (key: C8YTenantOptionKey) => Promise<string | undefined>;
+  context?: ScheduledTaskContext;
   /**
-   * Invalidate all tenant option caches that have been accessed.
-   * Only invalidates keys that have been fetched at least once.
+   * When the task should run. Numbers are seconds from now.
    */
-  invalidateAll: () => Promise<void>;
+  schedule: ScheduledTaskInput;
+}
+/**
+ * Public information about a pending scheduled task.\
+ * Returned by `scheduleTask()` and by `listScheduledTasks()`.
+ */
+interface ScheduledTaskInfo {
   /**
-   * 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
+   * Stable UUID used to list or cancel the scheduled task.
    */
-  refreshAll: () => Promise<Record<string, string | undefined>>;
-};
+  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 { createError, createLogger, hasUserRequiredRole, isUserFromAllowedTenant, isUserFromDeployedTenant, 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 };