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

package/dist/types/informationService.d.ts

@@ -0,0 +1,60 @@
+import type { IInformationComponent, IServerInfo } from "@3sixty/api-models";
+import type { IInformationServiceConstructorOptions } from "./models/IInformationServiceConstructorOptions.js";
+/**
+ * The information service for the server.
+ */
+export declare class InformationService implements IInformationComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of InformationService.
+     * @param options The options to create the service.
+     */
+    constructor(options: IInformationServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @returns A promise that resolves when the OpenAPI spec and favicon have been loaded from disk.
+     */
+    start(): Promise<void>;
+    /**
+     * 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 liveness 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/IHealthServiceConfig.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration for the health service.
+ */
+export interface IHealthServiceConfig {
+    /**
+     * The interval for checking the health of the components.
+     * @default 60000
+     */
+    healthCheckInterval?: number;
+    /**
+     * The interval for running the application health lifecycle (init, application, teardown).
+     * @default 300000
+     */
+    healthCheckApplicationInterval?: number;
+    /**
+     * The initial interval for checking the health of the components and setting it in the health service.
+     * This is used to check the health of the components immediately after the service is started.
+     * @default 2000
+     */
+    initialInterval?: number;
+    /**
+     * Whether to include stack traces in health check error details.
+     * @default false
+     */
+    includeErrorStack?: boolean;
+    /**
+     * The URL of the module to use for the application health background task.
+     * If not provided, the default healthApplicationTask module will be used.
+     */
+    overrideApplicationHealthTaskHandler?: string;
+    /**
+     * The component types to exclude from the engine clone used by the application health
+     * background task. Each entry is a regular expression matched against the engine config
+     * type keys, for example "^rightsManagement" or "messaging.*Connector".
+     */
+    excludeCloneComponents?: string[];
+}

package/dist/types/models/IHealthServiceConstructorOptions.d.ts

@@ -0,0 +1,15 @@
+import type { IHealthServiceConfig } from "./IHealthServiceConfig.js";
+/**
+ * Options for the HealthService constructor.
+ */
+export interface IHealthServiceConstructorOptions {
+    /**
+     * The background task component type to use for running application health checks.
+     * @default background-task
+     */
+    backgroundTaskComponentType?: string;
+    /**
+     * The configuration for the service.
+     */
+    config?: IHealthServiceConfig;
+}

package/dist/types/models/IInformationServiceConfig.d.ts

@@ -0,0 +1,18 @@
+import type { IServerInfo } from "@3sixty/api-models";
+/**
+ * Configuration for the information service.
+ */
+export interface IInformationServiceConfig {
+    /**
+     * The server information.
+     */
+    serverInfo: IServerInfo;
+    /**
+     * The path to the OpenAPI Spec.
+     */
+    openApiSpecPath?: string;
+    /**
+     * The path to the favicon.
+     */
+    favIconPath?: string;
+}

package/dist/types/models/IInformationServiceConstructorOptions.d.ts

@@ -0,0 +1,10 @@
+import type { IInformationServiceConfig } from "./IInformationServiceConfig.js";
+/**
+ * Options for the InformationService constructor.
+ */
+export interface IInformationServiceConstructorOptions {
+    /**
+     * The configuration for the service.
+     */
+    config: IInformationServiceConfig;
+}

package/dist/types/models/IPlatformServiceConfig.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Configuration for the platform service
+ */
+export interface IPlatformServiceConfig {
+    /**
+     * Indicates whether the service is running in a multi-tenant environment.
+     * @default false
+     */
+    isMultiTenant?: boolean;
+}

package/dist/types/models/IPlatformServiceConstructorOptions.d.ts

@@ -0,0 +1,15 @@
+import type { IPlatformServiceConfig } from "./IPlatformServiceConfig.js";
+/**
+ * Options for the Platform Service constructor.
+ */
+export interface IPlatformServiceConstructorOptions {
+    /**
+     * The entity storage for the tenants.
+     * @default tenant
+     */
+    tenantEntityStorageType?: string;
+    /**
+     * Configuration for the service.
+     */
+    config?: IPlatformServiceConfig;
+}

package/dist/types/platformService.d.ts

@@ -0,0 +1,39 @@
+import { type IPlatformComponent } from "@3sixty/api-models";
+import { type IContextIds } from "@3sixty/context";
+import type { IPlatformServiceConstructorOptions } from "./models/IPlatformServiceConstructorOptions.js";
+/**
+ * Service for performing platform operations.
+ */
+export declare class PlatformService implements IPlatformComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of PlatformService.
+     * @param options The options for the connector.
+     */
+    constructor(options?: IPlatformServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * 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/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@3sixty/api-models";
+/**
+ * REST entry points for the information and health services.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/docs/examples.md

@@ -0,0 +1,74 @@
+# Service Examples
+
+These snippets demonstrate how to configure service-level URL generation and expose operational information for monitoring.
+
+## InformationService
+
+```typescript
+import { InformationService } from '@3sixty/api-service';
+
+const infoService = new InformationService({
+  config: {
+    serverInfo: {
+      name: '3Sixty API',
+      version: '1.2.0'
+    }
+  }
+});
+
+await infoService.start();
+console.log(infoService.className()); // InformationService
+
+const root = await infoService.root();
+const info = await infoService.info();
+const favicon = await infoService.favicon();
+
+console.log(root); // 3Sixty API - 1.2.0
+console.log(info.version); // 1.2.0
+console.log((favicon?.byteLength ?? 0) > 0); // true
+```
+
+```typescript
+import { InformationService } from '@3sixty/api-service';
+
+const infoService = new InformationService({
+  config: {
+    serverInfo: {
+      name: '3Sixty API',
+      version: '1.2.0'
+    }
+  }
+});
+
+const spec = await infoService.spec();
+const live = await infoService.livez();
+const health = await infoService.health();
+
+await infoService.setComponentHealth('queue', 'ok');
+await infoService.removeComponentHealth('queue');
+
+console.log(typeof spec); // undefined
+console.log(live); // true
+console.log(health.status); // ok
+```
+
+## HostingService
+
+```typescript
+import { HostingService } from '@3sixty/api-service';
+
+const hostingService = new HostingService({
+  config: {
+    localOrigin: 'http://localhost:3000',
+    publicOrigin: 'https://api.example.org'
+  }
+});
+
+console.log(hostingService.className()); // HostingService
+
+const publicOrigin = await hostingService.getPublicOrigin('http://localhost:3000/users');
+const usersUrl = await hostingService.buildPublicUrl('http://localhost:3000/users');
+
+console.log(publicOrigin); // https://api.example.org
+console.log(usersUrl); // https://api.example.org/users
+```