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

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

@@ -0,0 +1,42 @@
+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 {
+    /**
+     * 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,44 @@
+import type { IContextIds } from "@3sixty/context";
+import type { IComponent } from "@3sixty/core";
+import type { TenantEventCallback } from "./tenantEventCallback.js";
+import type { TenantEventType } from "./tenantEventType.js";
+/**
+ * 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>;
+    /**
+     * 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/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/dist/types/models/services/tenantEventCallback.d.ts

@@ -0,0 +1,6 @@
+import type { TenantEventType } from "./tenantEventType.js";
+/**
+ * Callback invoked when a tenant event occurs.
+ * Failures in the callback will be logged but will not prevent other callbacks from being invoked.
+ */
+export type TenantEventCallback = (tenantId: string, eventType: TenantEventType) => Promise<void>;

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

@@ -0,0 +1,21 @@
+/**
+ * The type of event that occurred for a tenant.
+ */
+export declare const TenantEventType: {
+    /**
+     * The tenant was created.
+     */
+    readonly Created: "created";
+    /**
+     * The tenant was updated.
+     */
+    readonly Updated: "updated";
+    /**
+     * The tenant was deleted.
+     */
+    readonly Deleted: "deleted";
+};
+/**
+ * The type of event that occurred for a tenant.
+ */
+export type TenantEventType = (typeof TenantEventType)[keyof typeof TenantEventType];

package/docs/changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.20.0-next.1](https://github.com/3sixtyglobal/api/compare/api-models-v0.20.0-next.0...api-models-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))