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

package/dist/types/informationRoutes.d.ts

@@ -0,0 +1,60 @@
+import type { IHttpRequestContext, INoContentRequest, IRestRoute, IServerFavIconResponse, IServerInfoResponse, IServerLivezResponse, IServerReadyzResponse, IServerRootResponse, IServerSpecResponse, ITag } from "@3sixty/api-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsInformation: ITag[];
+/**
+ * The REST routes for server information.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesInformation(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Get the root for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverRoot(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerRootResponse>;
+/**
+ * Get the information for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverInfo(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerInfoResponse>;
+/**
+ * Get the livez for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverLivez(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerLivezResponse>;
+/**
+ * Get the readyz for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverReadyz(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerReadyzResponse>;
+/**
+ * Get the favicon for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverFavIcon(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerFavIconResponse>;
+/**
+ * Get the spec for the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function serverSpec(httpRequestContext: IHttpRequestContext, componentName: string, request: INoContentRequest): Promise<IServerSpecResponse>;

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,19 @@
+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;
+    /**
+     * The logging component type to use for error logging.
+     */
+    loggingComponentType?: string;
+    /**
+     * Configuration for the service.
+     */
+    config?: IPlatformServiceConfig;
+}

package/dist/types/platformService.d.ts

@@ -0,0 +1,57 @@
+import { type IPlatformComponent, type TenantEventCallback, type TenantEventType } 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>;
+    /**
+     * Registers a callback to be invoked when a tenant event occurs.
+     * @param callbackId A unique identifier for the callback.
+     * @param callback The callback to invoke when a tenant event occurs.
+     */
+    registerTenantEventCallback(callbackId: string, callback: TenantEventCallback): void;
+    /**
+     * Unregisters a previously registered tenant event callback.
+     * @param callbackId The identifier of the callback to unregister.
+     */
+    unregisterTenantEventCallback(callbackId: string): void;
+    /**
+     * Fires all registered tenant event callbacks.
+     * @param tenantId The ID of the tenant for which the event occurred.
+     * @param eventType The type of event that occurred.
+     * @returns A promise that resolves when all callbacks have been invoked.
+     */
+    fireTenantEvent(tenantId: string, eventType: TenantEventType): Promise<void>;
+}

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/changelog.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.20.0-next.1](https://github.com/3sixtyglobal/api/compare/api-service-v0.20.0-next.0...api-service-v0.20.0-next.1) (2026-10-23)
+
+
+### Features
+
+* authorization ([#51](https://github.com/3sixtyglobal/api/issues/51)) ([023ef94](https://github.com/3sixtyglobal/api/commit/023ef94925114e88522cbe6f703d9b05a202bc6d))
+* publish packages under the [@3sixty](https://github.com/3sixty) namespace ([91b1822](https://github.com/3sixtyglobal/api/commit/91b1822dba38f70692087ad4643572531d6634dc))
+* updated ts compile ([d9a5c86](https://github.com/3sixtyglobal/api/commit/d9a5c86ec7dd1faf3045b5cd1e0d38a4b331313d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @3sixty/api-models bumped from 0.20.0-next.0 to 0.20.0-next.1

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
+```