@3sixty/api-models 0.0.0-stage → 0.20.0-next.0

package/dist/types/models/server/IBaseRouteProcessor.d.ts

@@ -0,0 +1,49 @@
+import type { IContextIds } from "@3sixty/context";
+import type { IComponent } from "@3sixty/core";
+import type { IHttpResponse } from "../protocol/IHttpResponse.js";
+import type { IHttpServerRequest } from "../protocol/IHttpServerRequest.js";
+import type { IBaseRoute } from "../routes/IBaseRoute.js";
+/**
+ * The definition for a base processor for handling REST routes.
+ */
+export interface IBaseRouteProcessor<T = IBaseRoute, R = IHttpServerRequest> extends IComponent {
+    /**
+     * Features supported by this processor.
+     * If a route has any of these features listed, this processor will be run for that route.
+     * If this is not implemented, the processor will run for all routes.
+     * @returns The features supported by this processor.
+     */
+    features?(): string[];
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The request to handle.
+     * @param response The response data to send if any.
+     * @param route The route being requested, if a matching one was found.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @param componentTypes The component types for the request.
+     * @param componentTypes.loggingComponentType The logging component type.
+     * @returns Promise that resolves when the request is processed.
+     */
+    pre?(request: R, response: IHttpResponse, route: T | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }, componentTypes?: {
+        loggingComponentType?: string;
+    }): Promise<void>;
+    /**
+     * Post process the REST request for the specified route.
+     * @param request The request to handle.
+     * @param response The response data to send if any.
+     * @param route The route being requested, if a matching one was found.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @param componentTypes The component types for the request.
+     * @param componentTypes.loggingComponentType The logging component type.
+     * @returns Promise that resolves when the request is processed.
+     */
+    post?(request: R, response: IHttpResponse, route: T | undefined, contextIds: IContextIds, processorState: {
+        [id: string]: unknown;
+    }, componentTypes?: {
+        loggingComponentType?: string;
+    }): Promise<void>;
+}

package/dist/types/models/server/IMimeTypeProcessor.d.ts

@@ -0,0 +1,17 @@
+import type { IComponent } from "@3sixty/core";
+/**
+ * The definition for a handler for a specific MIME type.
+ */
+export interface IMimeTypeProcessor extends IComponent {
+    /**
+     * Get the MIME types that this handler can handle.
+     * @returns The MIME types that this handler can handle.
+     */
+    getTypes(): string[];
+    /**
+     * Handle content.
+     * @param body The body to process.
+     * @returns The processed body.
+     */
+    handle(body: Uint8Array): Promise<unknown>;
+}

package/dist/types/models/server/IRestRouteProcessor.d.ts

@@ -0,0 +1,24 @@
+import type { IBaseRouteProcessor } from "./IBaseRouteProcessor.js";
+import type { IHttpResponse } from "../protocol/IHttpResponse.js";
+import type { IHttpServerRequest } from "../protocol/IHttpServerRequest.js";
+import type { IRestRoute } from "../routes/IRestRoute.js";
+/**
+ * The definition for a processor for handling REST routes.
+ */
+export interface IRestRouteProcessor extends IBaseRouteProcessor<IRestRoute> {
+    /**
+     * Process the REST request for the specified route.
+     * @param request The request to handle.
+     * @param response The response data to send if any.
+     * @param route The route being requested, if a matching one was found.
+     * @param processorState The state handed through the processors.
+     * @param componentTypes The component types for the request.
+     * @param componentTypes.loggingComponentType The logging component type.
+     * @returns Promise that resolves when the request is processed.
+     */
+    process?(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, processorState: {
+        [id: string]: unknown;
+    }, componentTypes?: {
+        loggingComponentType?: string;
+    }): Promise<void>;
+}

package/dist/types/models/server/ISocketRouteProcessor.d.ts

@@ -0,0 +1,38 @@
+import type { IBaseRouteProcessor } from "./IBaseRouteProcessor.js";
+import type { IHttpResponse } from "../protocol/IHttpResponse.js";
+import type { ISocketServerRequest } from "../protocol/ISocketServerRequest.js";
+import type { ISocketRoute } from "../routes/ISocketRoute.js";
+/**
+ * The definition for a processor for handling socket routes.
+ */
+export interface ISocketRouteProcessor extends IBaseRouteProcessor<ISocketRoute, ISocketServerRequest> {
+    /**
+     * Process the connected event.
+     * @param request The server request object containing the socket id and other parameters.
+     * @param route The route being requested, if a matching one was found.
+     * @param loggingComponentType The logging component type for the request.
+     * @returns Promise that resolves when the request is processed.
+     */
+    connected?(request: ISocketServerRequest, route: ISocketRoute | undefined, loggingComponentType?: string): Promise<void>;
+    /**
+     * Process the disconnected event.
+     * @param request The server request object containing the socket id and other parameters.
+     * @param route The route being requested, if a matching one was found.
+     * @param loggingComponentType The logging component type for the request.
+     * @returns Promise that resolves when the request is processed.
+     */
+    disconnected?(request: ISocketServerRequest, route: ISocketRoute | undefined, loggingComponentType?: string): Promise<void>;
+    /**
+     * Process the REST request for the specified route.
+     * @param request The server request object containing the socket id and other parameters.
+     * @param response The response data to send if any.
+     * @param route The route being requested, if a matching one was found.
+     * @param processorState The state handed through the processors.
+     * @param responseEmitter The function to emit a response.
+     * @param loggingComponentType The logging component type for the request.
+     * @returns Promise that resolves when the request is processed.
+     */
+    process?(request: ISocketServerRequest, response: IHttpResponse, route: ISocketRoute | undefined, processorState: {
+        [id: string]: unknown;
+    }, responseEmitter: (topic: string, response: IHttpResponse) => Promise<void>, loggingComponentType?: string): Promise<void>;
+}

package/dist/types/models/server/IWebServer.d.ts

@@ -0,0 +1,36 @@
+import type { IComponent } from "@3sixty/core";
+import type { IRestRouteProcessor } from "./IRestRouteProcessor.js";
+import type { ISocketRouteProcessor } from "./ISocketRouteProcessor.js";
+import type { IWebServerOptions } from "./IWebServerOptions.js";
+import type { IRestRoute } from "../routes/IRestRoute.js";
+import type { ISocketRoute } from "../routes/ISocketRoute.js";
+/**
+ * Interface describing a web server.
+ */
+export interface IWebServer<T> extends IComponent {
+    /**
+     * Get the web server instance.
+     * @returns The web server instance.
+     */
+    getInstance(): T;
+    /**
+     * Build the server.
+     * @param restRouteProcessors The processors for incoming requests over REST.
+     * @param restRoutes The REST routes.
+     * @param socketRouteProcessors The processors for incoming requests over Sockets.
+     * @param socketRoutes The socket routes.
+     * @param options Options for building the server.
+     * @returns A promise that resolves when the server is fully built and ready to start.
+     */
+    build(restRouteProcessors?: IRestRouteProcessor[], restRoutes?: IRestRoute[], socketRouteProcessors?: ISocketRouteProcessor[], socketRoutes?: ISocketRoute[], options?: IWebServerOptions): Promise<void>;
+    /**
+     * Start the server.
+     * @returns A promise that resolves when the server is listening for connections.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server.
+     * @returns A promise that resolves when the server has shut down all connections.
+     */
+    stop(): Promise<void>;
+}

package/dist/types/models/server/IWebServerOptions.d.ts

@@ -0,0 +1,54 @@
+import type { HttpMethod } from "@3sixty/web";
+/**
+ * Options for the web server.
+ */
+export interface IWebServerOptions {
+    /**
+     * The port to bind the web server to.
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * The address to bind the web server to.
+     * @default localhost
+     */
+    host?: string;
+    /**
+     * The methods that the server accepts.
+     * @default ["GET", "PUT", "POST", "PATCH", "DELETE", "OPTIONS"]
+     */
+    methods?: HttpMethod[];
+    /**
+     * Any additional allowed headers.
+     */
+    allowedHeaders?: string[];
+    /**
+     * And additional exposed headers.
+     */
+    exposedHeaders?: string[];
+    /**
+     * The allowed CORS domains.
+     * @default ["*"]
+     */
+    corsOrigins?: string | string[];
+    /**
+     * The public origin of the server, used for constructing the request URL.
+     * If not provided, it will be determined from the incoming request.
+     */
+    publicOrigin?: string;
+    /**
+     * Named body size limits in bytes for REST routes, referenced by a route's bodyLimit name.
+     * Merged over the server's built-in limits; the "default" entry applies to routes with no bodyLimit name.
+     */
+    bodyLimits?: {
+        [name: string]: number;
+    };
+    /**
+     * Custom configuration for the web server.
+     */
+    customWebConfig?: unknown;
+    /**
+     * Custom configuration for the socket server.
+     */
+    customSocketConfig?: unknown;
+}

package/dist/types/models/services/IHealthApplicationCallback.d.ts

@@ -0,0 +1,6 @@
+import type { IHealth } from "../IHealth.js";
+/**
+ * Callback invoked by a component to supply a deferred application health result.
+ * Only called when healthApplication returns undefined.
+ */
+export type HealthApplicationCallback = (result: IHealth[]) => Promise<void>;

package/dist/types/models/services/IHealthComponent.d.ts

@@ -0,0 +1,16 @@
+import type { IComponent } from "@3sixty/core";
+import type { HealthStatus } from "../healthStatus.js";
+import type { IHealth } from "../IHealth.js";
+/**
+ * The health component for the server.
+ */
+export interface IHealthComponent extends IComponent {
+    /**
+     * Get the server health.
+     * @returns The service health.
+     */
+    healthStatus(): Promise<{
+        status: HealthStatus;
+        components: IHealth[];
+    }>;
+}

package/dist/types/models/services/IHealthProviderComponent.d.ts

@@ -0,0 +1,31 @@
+import type { IContextIds } from "@3sixty/context";
+import type { IHealth } from "../IHealth.js";
+import type { HealthApplicationCallback } from "./IHealthApplicationCallback.js";
+/**
+ * The health provider component for the server.
+ */
+export interface IHealthProviderComponent {
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component, can return multiple entries for elements within the component.
+     */
+    health?(): Promise<IHealth[]>;
+    /**
+     * Initialize the application health processing for a component.
+     * @param contextIds The context IDs provisioned during the init pass.
+     * @returns A promise that resolves when the initialization is complete.
+     */
+    healthApplicationInit?(contextIds: IContextIds): Promise<void>;
+    /**
+     * Returns the application health status of the component, context IDs from init are set in the current context.
+     * Returns undefined when the result will be provided asynchronously via the callback.
+     * @param callback The callback to invoke when a deferred health result is ready.
+     * @returns The health status, or undefined if the result will be provided via the callback.
+     */
+    healthApplication?(callback: HealthApplicationCallback): Promise<IHealth[] | undefined>;
+    /**
+     * Teardown the application health processing for a component.
+     * @returns A promise that resolves when the teardown is complete.
+     */
+    healthApplicationTeardown?(): Promise<void>;
+}

package/dist/types/models/services/IInformationComponent.d.ts

@@ -0,0 +1,41 @@
+import type { IComponent } from "@3sixty/core";
+import type { IServerInfo } from "./IServerInfo.js";
+/**
+ * The information component for the server.
+ */
+export interface IInformationComponent extends IComponent {
+    /**
+     * Get the root information.
+     * @returns The root information.
+     */
+    root(): Promise<string>;
+    /**
+     * Get the server information.
+     * @returns The service information.
+     */
+    info(): Promise<IServerInfo>;
+    /**
+     * Get the favicon.
+     * @returns The favicon.
+     */
+    favicon(): Promise<Uint8Array | undefined>;
+    /**
+     * Get the OpenAPI spec.
+     * @returns The OpenAPI spec.
+     */
+    spec(): Promise<unknown>;
+    /**
+     * Is the server live.
+     * @returns The livez status of the server.
+     */
+    livez(): Promise<{
+        status: "alive" | "dead";
+    }>;
+    /**
+     * Is the server ready.
+     * @returns The readyz status of the server.
+     */
+    readyz(): Promise<{
+        status: "ready" | "not ready";
+    }>;
+}

package/dist/types/models/services/IPlatformComponent.d.ts

@@ -0,0 +1,24 @@
+import type { IContextIds } from "@3sixty/context";
+import type { IComponent } from "@3sixty/core";
+/**
+ * Interface for the platform component.
+ */
+export interface IPlatformComponent extends IComponent {
+    /**
+     * Indicates whether the component is running in a multi-tenant environment.
+     * @returns True if the component is running in a multi-tenant environment, false otherwise.
+     */
+    isMultiTenant(): boolean;
+    /**
+     * Execute a method, if single tenant will run once, if multi-tenant will run for each tenant.
+     * @param method The method to run for each tenant, returning false will stop any further iterations.
+     * @returns A promise that resolves when the method has been executed for all applicable tenants.
+     */
+    execute(method: () => Promise<undefined | boolean> | Promise<void>): Promise<void>;
+    /**
+     * Get the local origin context IDs for the given URL.
+     * @param url The URL to check.
+     * @returns A promise that resolves to the context IDs if the URL is a local origin, undefined otherwise.
+     */
+    getLocalOriginContext(url: string): Promise<IContextIds | undefined>;
+}

package/dist/types/models/services/IServerInfo.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The information about the server.
+ */
+export interface IServerInfo {
+    /**
+     * The application name.
+     */
+    name: string;
+    /**
+     * The version of the server.
+     */
+    version: string;
+}

package/dist/types/models/services/ITenant.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Model defining the tenant.
+ */
+export interface ITenant {
+    /**
+     * The unique identifier for the tenant.
+     */
+    id: string;
+    /**
+     * The api key for the tenant.
+     */
+    apiKey: string;
+    /**
+     * The label of the tenant.
+     */
+    label: string;
+    /**
+     * The date the tenant was created.
+     */
+    dateCreated: string;
+    /**
+     * The date the tenant was modified.
+     */
+    dateModified: string;
+    /**
+     * The public origin available to the public for accessing the API.
+     */
+    publicOrigin?: string;
+    /**
+     * The organization id for the tenant.
+     */
+    organizationId: string;
+    /**
+     * Optional list of organization aliases that can are used for legacy lookups.
+     */
+    organizationIdLegacy?: string[];
+}

package/dist/types/models/services/ITenantAdminComponent.d.ts

@@ -0,0 +1,70 @@
+import type { IComponent } from "@3sixty/core";
+import type { EntityCondition } from "@3sixty/entity";
+import type { ITenant } from "./ITenant.js";
+/**
+ * Configuration for the tenant admin component
+ */
+export interface ITenantAdminComponent extends IComponent {
+    /**
+     * Create a tenant.
+     * @param tenant The tenant to store.
+     * @returns The tenant id.
+     */
+    create(tenant: Omit<ITenant, "id" | "dateCreated" | "dateModified"> & {
+        id?: string;
+    }): Promise<string>;
+    /**
+     * Update a tenant.
+     * @param tenant The tenant to update.
+     * @returns A promise that resolves when the tenant has been updated.
+     */
+    update(tenant: Partial<Omit<ITenant, "dateCreated" | "dateModified">>): Promise<void>;
+    /**
+     * Get a tenant by its id.
+     * @param tenantId The id of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    get(tenantId: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its api key.
+     * @param apiKey The api key of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getByApiKey(apiKey: string): Promise<ITenant>;
+    /**
+     * Get a tenant by its public origin.
+     * @param publicOrigin The origin of the tenant.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getByPublicOrigin(publicOrigin: string): Promise<ITenant>;
+    /**
+     * Remove a tenant by its id.
+     * @param tenantId The id of the tenant.
+     * @returns A promise that resolves when the tenant has been removed.
+     * @throws Error if the tenant is not found.
+     */
+    remove(tenantId: string): Promise<void>;
+    /**
+     * Get a tenant by its organization id, optionally searching legacy ids.
+     * @param organizationId The organization id of the tenant.
+     * @param includeLegacy Whether to also search the legacy organization id array.
+     * @returns The tenant.
+     * @throws Error if the tenant is not found.
+     */
+    getTenantByOrganizationId(organizationId: string, includeLegacy?: boolean): Promise<ITenant>;
+    /**
+     * Query tenants with pagination.
+     * @param conditions The conditions to filter the tenants.
+     * @param properties The properties to include in the returned tenants.
+     * @param cursor The cursor to start from.
+     * @param limit The maximum number of tenants to return.
+     * @returns The tenants and the next cursor if more tenants are available.
+     */
+    query(conditions?: EntityCondition<ITenant>, properties?: (keyof ITenant)[], cursor?: string, limit?: number): Promise<{
+        tenants: ITenant[];
+        cursor?: string;
+    }>;
+}

package/docs/examples.md

@@ -0,0 +1,200 @@
+# Models Examples
+
+These snippets show practical helpers for URL manipulation, request parameter conversion, consistent error responses, and secure parameter encryption.
+
+## HttpUrlHelper
+
+```typescript
+import { HttpUrlHelper } from '@3sixty/api-models';
+
+const fullUrl = 'https://tenant.example.org/orders?page=2';
+
+console.log(HttpUrlHelper.extractOrigin(fullUrl)); // https://tenant.example.org
+console.log(HttpUrlHelper.extractPath(fullUrl)); // /orders
+console.log(HttpUrlHelper.extractSearch(fullUrl)); // ?page=2
+console.log(HttpUrlHelper.extractPathAndSearch(fullUrl)); // /orders?page=2
+```
+
+```typescript
+import { HttpUrlHelper } from '@3sixty/api-models';
+
+const combined = HttpUrlHelper.combineParts('https://tenant.example.org/', '/api/v1/orders');
+const replaced = HttpUrlHelper.replaceOrigin(combined ?? '', 'https://edge.example.org');
+
+console.log(combined); // https://tenant.example.org/api/v1/orders
+console.log(replaced); // https://edge.example.org/api/v1/orders
+```
+
+## HttpParameterHelper
+
+```typescript
+import { HttpParameterHelper } from '@3sixty/api-models';
+
+const ids = HttpParameterHelper.arrayFromString('id-1,id-2,id-3');
+const idsAsString = HttpParameterHelper.arrayToString(ids);
+
+const filterObject = HttpParameterHelper.objectFromString('{"status":"active"}');
+const filterString = HttpParameterHelper.objectToString(filterObject);
+
+console.log(ids.length); // 3
+console.log(idsAsString); // id-1,id-2,id-3
+console.log(filterString); // {"status":"active"}
+```
+
+## HttpErrorHelper
+
+```typescript
+import { HttpErrorHelper } from '@3sixty/api-models';
+
+try {
+  throw new Error('Invalid request');
+} catch (err) {
+  const mapped = HttpErrorHelper.processError(err, false);
+  const response: {
+    body?: unknown;
+    statusCode?: number;
+    headers?: { [id: string]: string };
+  } = {};
+  HttpErrorHelper.buildResponse(response, mapped.error, mapped.httpStatusCode);
+
+  console.log(response.statusCode); // 500
+  console.log(mapped.error.message); // Error: Invalid request
+}
+```
+
+## IHostingComponent
+
+When working with the hosting component, you can encrypt and decrypt query parameters for secure transmission. The encryption mechanism automatically handles salt generation to prevent rainbow table attacks.
+
+```typescript
+import type { IComponent, IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent extends IComponent {
+  addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+  getDecryptedParamsFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<IHttpRequestQuery>;
+  encryptParam(paramValue: string): Promise<string>;
+  decryptParam(encryptedValue: string): Promise<string>;
+}
+
+// Get the hosting component from the component factory
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt parameters and add them to a URL
+const baseUrl = 'https://api.example.com/callback';
+const encrypted = await hosting.addEncryptedParamsToUrl(baseUrl, {
+  token: 'secret-token-123',
+  userId: 'user-456'
+});
+console.log(encrypted); // https://api.example.com/callback?x-enc-token=...&x-enc-userId=...
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+  getDecryptedParamsFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<IHttpRequestQuery>;
+  encryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+  decryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Decrypt specific parameters from a query object
+const queryParams: IHttpRequestQuery = {
+  'x-enc-token': 'CngBAgMEBQYH...',
+  'x-enc-userId': 'CxgICSoLDAwN...',
+  status: 'active'
+};
+
+const decrypted = await hosting.getDecryptedParamsFromQueryParams(queryParams, ['token', 'userId']);
+console.log(decrypted); // { token: 'secret-token-123', userId: 'user-456' }
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  addTenantTokenToUrl(url: string, tenantId: string): Promise<string>;
+  getTenantTokenFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined
+  ): Promise<string | undefined>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Add encrypted tenant token to a URL
+const redirectUrl = 'https://tenant.example.com/dashboard';
+const urlWithTenant = await hosting.addTenantTokenToUrl(
+  redirectUrl,
+  'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
+);
+console.log(urlWithTenant); // https://tenant.example.com/dashboard?x-enc-tenant-token=...
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  encryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+  decryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt specific query parameters in place
+const query: IHttpRequestQuery = {
+  token: 'secret-123',
+  apiKey: 'key-456',
+  status: 'active'
+};
+
+await hosting.encryptQueryParams(query, ['token', 'apiKey']);
+console.log(query); // { 'x-enc-token': '...', 'x-enc-apiKey': '...', status: 'active' }
+
+// Decrypt the parameters back to their original keys
+await hosting.decryptQueryParams(query, ['token', 'apiKey']);
+console.log(query); // { token: 'secret-123', apiKey: 'key-456', status: 'active' }
+```
+
+```typescript
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  encryptParam(paramValue: string): Promise<string>;
+  decryptParam(encryptedValue: string): Promise<string>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt a single parameter value
+const plainText = 'confidential-data';
+const encrypted = await hosting.encryptParam(plainText);
+console.log(encrypted); // CngBAgMEBQYHCAkKCwwNDg8QERAh...
+
+// Decrypt the parameter value
+const decrypted = await hosting.decryptParam(encrypted);
+console.log(decrypted); // confidential-data
+```