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

package/dist/types/helpers/httpHeaderHelper.d.ts

@@ -0,0 +1,62 @@
+import { HeaderTypes, MimeTypes, type IHttpHeaders } from "@3sixty/web";
+/**
+ * Class to help with handling http headers.
+ */
+export declare class HttpHeaderHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Set the Link header with a next cursor relation when a cursor is present.
+     * @param headers The response headers to mutate.
+     * @param url The request URL used as the base for the link.
+     * @param publicOrigin The public origin to substitute into the URL, if any.
+     * @param cursor The cursor value; when undefined or empty the header is not set.
+     */
+    static buildCursor(headers: IHttpHeaders, url: string, publicOrigin: string | undefined, cursor: string | undefined): asserts headers is IHttpHeaders & {
+        [HeaderTypes.Link]: string | undefined;
+    };
+    /**
+     * Set the Location header to the encoded ID, optionally placed within a URL template.
+     * When the template contains `:id` (e.g. "/path1/:id/path2" or "/path?p=:id") the
+     * encoded ID is substituted at that position; otherwise it is appended.
+     * When no template is provided the bare encoded ID is used.
+     * Callers that need to combine a public origin with a path should use
+     * HttpUrlHelper.combineOriginPath to build the template before calling this method.
+     * @param headers The response headers to mutate.
+     * @param id The resource ID to encode and place.
+     * @param urlTemplate The optional URL template (absolute or relative).
+     */
+    static buildId(headers: IHttpHeaders, id: string, urlTemplate?: string): asserts headers is IHttpHeaders & {
+        [HeaderTypes.Location]: string;
+    };
+    /**
+     * Set the Content-Type header to JSON-LD or JSON depending on the request Accept header.
+     * Uses HeaderHelper.extractAccept which parses the Accept header per RFC 7231 and returns
+     * entries ordered by quality descending, preserving original order for equal q-values.
+     * @param headers The response headers to mutate.
+     * @param requestHeaders The request headers to inspect for the Accept value.
+     */
+    static buildJsonContentType(headers: IHttpHeaders, requestHeaders?: IHttpHeaders): asserts headers is IHttpHeaders & {
+        [HeaderTypes.ContentType]: typeof MimeTypes.JsonLd | typeof MimeTypes.Json;
+    };
+    /**
+     * Extract the cursor from the Link header's next relation.
+     * @param headers The response headers to extract the cursor from.
+     * @returns The cursor value or undefined if not present.
+     */
+    static extractCursor(headers?: IHttpHeaders): string | undefined;
+    /**
+     * Extract the resource ID from the Location response header.
+     * Handles absolute URLs, relative paths, and bare ID values.
+     * When a templateUrl containing ':id' is supplied (e.g. "/path1/:id/path2" or
+     * "https://host/path/:id") the ID is extracted via pattern matching at the ':id'
+     * position. Without a matching template the last path segment is returned.
+     * @param headers The response headers containing the Location header.
+     * @param templateUrl Optional URL template containing the ':id' placeholder, e.g. "/path1/:id/path2".
+     * @returns The extracted ID string.
+     * @throws GeneralError If the Location header is missing or the ID cannot be extracted.
+     */
+    static extractId(headers?: IHttpHeaders, templateUrl?: string): string;
+}

package/dist/types/helpers/httpParameterHelper.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Class to help with handling http parameters.
+ */
+export declare class HttpParameterHelper {
+    /**
+     * Convert list query to array.
+     * @param values The values query string.
+     * @returns The array of values.
+     */
+    static arrayFromString<T = string>(values?: string): T[] | undefined;
+    /**
+     * Convert array of values to query string.
+     * @param values The values to combine string.
+     * @returns The combined.
+     */
+    static arrayToString<T = string>(values?: T[]): string | undefined;
+    /**
+     * Convert object string to object.
+     * @param value The value query string.
+     * @returns The object.
+     */
+    static objectFromString<T = unknown>(value?: string): T | undefined;
+    /**
+     * Convert object to query string.
+     * @param value The value to convert to a string.
+     * @returns The converted object.
+     */
+    static objectToString<T = unknown>(value?: T): string | undefined;
+}

package/dist/types/helpers/httpUrlHelper.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Class to help with handling http URLs.
+ */
+export declare class HttpUrlHelper {
+    /**
+     * Extract the origin from the url which includes protocol,host,port.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/origin
+     * @param url The url to extract the origin from.
+     * @returns The extracted origin.
+     */
+    static extractOrigin(url: string): string | undefined;
+    /**
+     * Extract the path from the url.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname
+     * @param url The url to extract the path from.
+     * @returns The extracted path.
+     */
+    static extractPath(url: string): string | undefined;
+    /**
+     * Extract the search from the url.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/search
+     * @param url The url to extract the search from.
+     * @returns The extracted search.
+     */
+    static extractSearch(url: string): string | undefined;
+    /**
+     * Extract the path and search from the url.
+     * @param url The url to extract the path and search from.
+     * @returns The extracted path and search.
+     */
+    static extractPathAndSearch(url: string): string | undefined;
+    /**
+     * Combine an optional origin and an optional path into a single URL string.
+     * Relative paths (no protocol, no leading slash) have a leading slash prepended.
+     * Trailing slashes are trimmed from the origin before joining.
+     * Returns undefined when both arguments are absent or empty.
+     * @param origin The optional origin (e.g. "https://example.com").
+     * @param path The optional path or URL template (e.g. "/api/items" or "api/items").
+     * @returns The combined string, or undefined when both are absent.
+     */
+    static combineOriginPath(origin?: string, path?: string): string | undefined;
+    /**
+     * Encode a single URL path segment per RFC 3986 §3.3.
+     * Unlike encodeURIComponent, sub-delimiters ($ & + , ; =) and the colon and
+     * at-sign characters that are valid unencoded in path segments are preserved.
+     * @see https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+     * @param segment The raw path segment value to encode.
+     * @returns The percent-encoded path segment.
+     */
+    static encodeUriPathSegment(segment: string): string;
+    /**
+     * Replace the origin in the url.
+     * @param url The url to replace the origin in.
+     * @param newOrigin The new origin to use.
+     * @returns The url with the replaced origin.
+     */
+    static replaceOrigin(url: string, newOrigin?: string): string;
+    /**
+     * Add a query string parameter to the url.
+     * @param url The url to add the query string parameter to.
+     * @param key The key of the query string parameter.
+     * @param value The value of the query string parameter.
+     * @returns The url with the added query string parameter.
+     */
+    static addQueryStringParam(url: string, key: string, value: string): string;
+    /**
+     * Get a query string parameter from the url.
+     * @param url The url to get the query string parameter from.
+     * @param key The key of the query string parameter.
+     * @returns The value of the query string parameter.
+     */
+    static getQueryStringParam(url: string, key: string): string | undefined;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,77 @@
+export * from "./errors/forbiddenError.js";
+export * from "./errors/tooManyRequestsError.js";
+export * from "./factories/mimeTypeProcessorFactory.js";
+export * from "./factories/restClientProcessorFactory.js";
+export * from "./factories/restRouteProcessorFactory.js";
+export * from "./factories/socketRouteProcessorFactory.js";
+export * from "./helpers/httpErrorHelper.js";
+export * from "./helpers/httpHeaderHelper.js";
+export * from "./helpers/httpParameterHelper.js";
+export * from "./helpers/httpUrlHelper.js";
+export * from "./models/api/IServerFavIconResponse.js";
+export * from "./models/api/IServerHealthResponse.js";
+export * from "./models/api/IServerInfoResponse.js";
+export * from "./models/api/IServerLivezResponse.js";
+export * from "./models/api/IServerReadyzResponse.js";
+export * from "./models/api/IServerRootResponse.js";
+export * from "./models/api/IServerSpecResponse.js";
+export * from "./models/client/IRestClientProcessor.js";
+export * from "./models/client/IRestClientProcessorContext.js";
+export * from "./models/config/IBaseRestClientConfig.js";
+export * from "./models/config/IBaseSocketClientConfig.js";
+export * from "./models/healthCategory.js";
+export * from "./models/healthStatus.js";
+export * from "./models/httpContextIdKeys.js";
+export * from "./models/IHealth.js";
+export * from "./models/protocol/IHttpRequest.js";
+export * from "./models/protocol/IHttpRequestContext.js";
+export * from "./models/protocol/IHttpRequestPathParams.js";
+export * from "./models/protocol/IHttpRequestQuery.js";
+export * from "./models/protocol/IHttpResponse.js";
+export * from "./models/protocol/IHttpServerRequest.js";
+export * from "./models/protocol/ISocketRequestContext.js";
+export * from "./models/protocol/ISocketServerRequest.js";
+export * from "./models/requests/INoContentRequest.js";
+export * from "./models/responses/errors/IBadRequestResponse.js";
+export * from "./models/responses/errors/IConflictResponse.js";
+export * from "./models/responses/errors/IForbiddenResponse.js";
+export * from "./models/responses/errors/IInternalServerErrorResponse.js";
+export * from "./models/responses/errors/INotFoundResponse.js";
+export * from "./models/responses/errors/INotImplementedResponse.js";
+export * from "./models/responses/errors/ITooManyRequestsResponse.js";
+export * from "./models/responses/errors/IUnauthorizedResponse.js";
+export * from "./models/responses/errors/IUnprocessableEntityResponse.js";
+export * from "./models/responses/success/IAcceptedResponse.js";
+export * from "./models/responses/success/ICreatedResponse.js";
+export * from "./models/responses/success/INoContentResponse.js";
+export * from "./models/responses/success/IOkResponse.js";
+export * from "./models/routes/httpBodyLimit.js";
+export * from "./models/routes/IBaseRoute.js";
+export * from "./models/routes/IBaseRouteEntryPoint.js";
+export * from "./models/routes/IRestRoute.js";
+export * from "./models/routes/IRestRouteEntryPoint.js";
+export * from "./models/routes/IRestRouteExample.js";
+export * from "./models/routes/IRestRouteRequestExample.js";
+export * from "./models/routes/IRestRouteResponseAttachmentOptions.js";
+export * from "./models/routes/IRestRouteResponseExample.js";
+export * from "./models/routes/IRestRouteResponseOptions.js";
+export * from "./models/routes/IRouteAuthorization.js";
+export * from "./models/routes/ISocketRoute.js";
+export * from "./models/routes/ISocketRouteEntryPoint.js";
+export * from "./models/routes/ITag.js";
+export * from "./models/server/IBaseRouteProcessor.js";
+export * from "./models/server/IMimeTypeProcessor.js";
+export * from "./models/server/IRestRouteProcessor.js";
+export * from "./models/server/ISocketRouteProcessor.js";
+export * from "./models/server/IWebServer.js";
+export * from "./models/server/IWebServerOptions.js";
+export * from "./models/services/IHealthApplicationCallback.js";
+export * from "./models/services/IHealthComponent.js";
+export * from "./models/services/IHealthProviderComponent.js";
+export * from "./models/services/IInformationComponent.js";
+export * from "./models/services/IPlatformComponent.js";
+export * from "./models/services/IServerInfo.js";
+export * from "./models/services/ITenant.js";
+export * from "./models/services/ITenantAdminComponent.js";
+export * from "./models/services/tenantEventCallback.js";
+export * from "./models/services/tenantEventType.js";

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

@@ -0,0 +1,42 @@
+import type { IError } from "@3sixty/core";
+import type { HealthCategory } from "./healthCategory.js";
+import type { HealthStatus } from "./healthStatus.js";
+/**
+ * Provides health information for a component.
+ */
+export interface IHealth {
+    /**
+     * The source of the health information.
+     */
+    source: string;
+    /**
+     * The description of the component as an i18n key.
+     */
+    description?: string;
+    /**
+     * The category of the health check.
+     */
+    category?: HealthCategory;
+    /**
+     * The overall status of the component, the entries can also report their own health.
+     */
+    status: HealthStatus;
+    /**
+     * The error details when the status is not Ok.
+     */
+    error?: IError;
+    /**
+     * The message for the status if there are further details to provide as an i18n key.
+     */
+    message?: string;
+    /**
+     * Data to substitute in the i18n key for the message.
+     */
+    data?: {
+        [id: string]: unknown;
+    };
+    /**
+     * The grouped child components, if any.
+     */
+    grouped?: IHealth[];
+}

package/dist/types/models/api/IServerFavIconResponse.d.ts

@@ -0,0 +1,23 @@
+import type { HeaderTypes, HttpStatusCode } from "@3sixty/web";
+/**
+ * The favicon for the server.
+ */
+export interface IServerFavIconResponse {
+    /**
+     * Additional response headers.
+     */
+    headers?: {
+        /**
+         * The content type for the response.
+         */
+        [HeaderTypes.ContentType]?: string;
+    };
+    /**
+     * Response status code.
+     */
+    statusCode?: HttpStatusCode;
+    /**
+     * The favicon for the server.
+     */
+    body?: Uint8Array;
+}

package/dist/types/models/api/IServerHealthResponse.d.ts

@@ -0,0 +1,14 @@
+import type { HealthStatus } from "../healthStatus.js";
+import type { IHealth } from "../IHealth.js";
+/**
+ * The health of the server.
+ */
+export interface IServerHealthResponse {
+    /**
+     * The health for the server.
+     */
+    body: {
+        status: HealthStatus;
+        components: IHealth[];
+    };
+}

package/dist/types/models/api/IServerInfoResponse.d.ts

@@ -0,0 +1,10 @@
+import type { IServerInfo } from "../services/IServerInfo.js";
+/**
+ * The information about the server.
+ */
+export interface IServerInfoResponse {
+    /**
+     * The information for the server.
+     */
+    body: IServerInfo;
+}

package/dist/types/models/api/IServerLivezResponse.d.ts

@@ -0,0 +1,16 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+/**
+ * The livez of the server.
+ */
+export interface IServerLivezResponse {
+    /**
+     * The headers for the response.
+     */
+    headers: {
+        [HeaderTypes.ContentType]: typeof MimeTypes.PlainText;
+    };
+    /**
+     * The livez information for the server.
+     */
+    body: "alive" | "dead";
+}

package/dist/types/models/api/IServerReadyzResponse.d.ts

@@ -0,0 +1,16 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+/**
+ * The readyz of the server.
+ */
+export interface IServerReadyzResponse {
+    /**
+     * The headers for the response.
+     */
+    headers: {
+        [HeaderTypes.ContentType]: typeof MimeTypes.PlainText;
+    };
+    /**
+     * The readyz information for the server.
+     */
+    body: "ready" | "not ready";
+}

package/dist/types/models/api/IServerRootResponse.d.ts

@@ -0,0 +1,16 @@
+import type { HeaderTypes, MimeTypes } from "@3sixty/web";
+/**
+ * The root text for the server.
+ */
+export interface IServerRootResponse {
+    /**
+     * The headers for the response.
+     */
+    headers: {
+        [HeaderTypes.ContentType]: typeof MimeTypes.PlainText;
+    };
+    /**
+     * The root text for the server.
+     */
+    body: string;
+}

package/dist/types/models/api/IServerSpecResponse.d.ts

@@ -0,0 +1,14 @@
+import type { HttpStatusCode } from "@3sixty/web";
+/**
+ * The OpenAPI spec for the endpoints.
+ */
+export interface IServerSpecResponse {
+    /**
+     * Response status code.
+     */
+    statusCode?: HttpStatusCode;
+    /**
+     * The spec for the server.
+     */
+    body?: unknown;
+}

package/dist/types/models/client/IRestClientProcessor.d.ts

@@ -0,0 +1,22 @@
+import type { IComponent } from "@3sixty/core";
+import type { IRestClientProcessorContext } from "./IRestClientProcessorContext.js";
+/**
+ * A processor that participates in an outbound REST request.
+ */
+export interface IRestClientProcessor extends IComponent {
+    /**
+     * Run the processor before the fetch takes place.
+     * @param context The details of the request being made.
+     * @param next Performs the request, or calls the next processor in the chain.
+     * @returns The result of next.
+     */
+    pre?(context: IRestClientProcessorContext, next: () => Promise<Response>): Promise<Response>;
+    /**
+     * Run the processor after the fetch completes.
+     * @param context The details of the request that was made.
+     * @param response The response from the request.
+     * @param next Performs the post processing, or calls the next processor in the chain.
+     * @returns The result of next.
+     */
+    post?(context: IRestClientProcessorContext, response: Response, next: () => Promise<Response>): Promise<Response>;
+}

package/dist/types/models/client/IRestClientProcessorContext.d.ts

@@ -0,0 +1,42 @@
+import type { HttpMethod, IHttpHeaders } from "@3sixty/web";
+/**
+ * The context of a rest client processor.
+ */
+export interface IRestClientProcessorContext {
+    /**
+     * The name of the REST client making the request.
+     */
+    restClientClassName: string;
+    /**
+     * The base URL of the request.
+     */
+    baseUrl: string;
+    /**
+     * The route template before path parameter substitution.
+     */
+    routeTemplate: string;
+    /**
+     * The route being requested.
+     */
+    route: string;
+    /**
+     * The HTTP method of the request.
+     */
+    method: HttpMethod;
+    /**
+     * The headers being sent with the request.
+     */
+    headers: IHttpHeaders;
+    /**
+     * The timeout for the request in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Whether to include credentials in the request.
+     */
+    includeCredentials?: boolean;
+    /**
+     * The request being made.
+     */
+    body?: string;
+}

package/dist/types/models/config/IBaseRestClientConfig.d.ts

@@ -0,0 +1,46 @@
+import type { IError } from "@3sixty/core";
+import type { IHttpHeaders } from "@3sixty/web";
+/**
+ * Definition for the configuration of a rest client.
+ */
+export interface IBaseRestClientConfig {
+    /**
+     * The endpoint where the api is hosted.
+     */
+    endpoint: string;
+    /**
+     * The prefix to the routes.
+     */
+    pathPrefix?: string;
+    /**
+     * The headers to include in requests.
+     */
+    headers?: IHttpHeaders;
+    /**
+     * Timeout for requests in ms.
+     */
+    timeout?: number;
+    /**
+     * Include credentials in the request, defaults to true.
+     */
+    includeCredentials?: boolean;
+    /**
+     * The types of the processors to run around each request, resolved from the `RestClientProcessorFactory`.
+     */
+    processorTypes?: string[];
+    /**
+     * Hook to provide headers asynchronously.
+     * @returns A promise that resolves to the headers.
+     */
+    customHeaders?: () => Promise<IHttpHeaders>;
+    /**
+     * Hook to provide an authorization header value asynchronously.
+     * @returns A promise that resolves to the authorization header value.
+     */
+    customAuthHeader?: () => Promise<string>;
+    /**
+     * Hook to handle authorization failures asynchronously.
+     * @returns A promise that resolves when the auth failure handling is complete.
+     */
+    onAuthFailure?: (err: IError) => Promise<void>;
+}

package/dist/types/models/config/IBaseSocketClientConfig.d.ts

@@ -0,0 +1,22 @@
+import type { IHttpHeaders } from "@3sixty/web";
+/**
+ * Definition for the configuration of a socket service.
+ */
+export interface IBaseSocketClientConfig {
+    /**
+     * Base path for the socket service, defaults to /socket.
+     */
+    basePath?: string;
+    /**
+     * The endpoint where the api is hosted.
+     */
+    endpoint: string;
+    /**
+     * The prefix to the routes.
+     */
+    pathPrefix?: string;
+    /**
+     * The headers to include in requests.
+     */
+    headers?: IHttpHeaders;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The category of a health check.
+ */
+export declare const HealthCategory: {
+    /**
+     * Connectivity health check for infrastructure connectors.
+     */
+    readonly Connectivity: "connectivity";
+    /**
+     * Application health check for domain services.
+     */
+    readonly Application: "application";
+};
+/**
+ * The category of a health check.
+ */
+export type HealthCategory = (typeof HealthCategory)[keyof typeof HealthCategory];

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

@@ -0,0 +1,21 @@
+/**
+ * The health status of the component.
+ */
+export declare const HealthStatus: {
+    /**
+     * OK.
+     */
+    readonly Ok: "ok";
+    /**
+     * Warning.
+     */
+    readonly Warning: "warning";
+    /**
+     * Error.
+     */
+    readonly Error: "error";
+};
+/**
+ * The health status of the component.
+ */
+export type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];

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

@@ -0,0 +1,38 @@
+/**
+ * HTTP definition of some context keys.
+ */
+export declare const HttpContextIdKeys: {
+    /**
+     * IP address of the client.
+     */
+    readonly IpAddress: "ipAddress";
+    /**
+     * User agent of the client.
+     */
+    readonly UserAgent: "userAgent";
+    /**
+     * Correlation ID of the request.
+     */
+    readonly CorrelationId: "correlationId";
+    /**
+     * Is this a remote request, will be a random UUID if request arrived through a REST endpoint, otherwise undefined.
+     */
+    readonly RemoteRequest: "remoteRequest";
+    /**
+     * Public Origin of the request.
+     */
+    readonly PublicOrigin: "publicOrigin";
+    /**
+     * Local Origin of the request.
+     */
+    readonly LocalOrigin: "localOrigin";
+    /**
+     * The caller's original tenant ID before an escalated privilege tenant override was applied.
+     * Only present when overrideTenant substitution is active for the current request.
+     */
+    readonly OriginalTenant: "originalTenant";
+};
+/**
+ * HTTP definition of some context keys.
+ */
+export type HttpContextIdKeys = (typeof HttpContextIdKeys)[keyof typeof HttpContextIdKeys];

package/dist/types/models/protocol/IHttpRequest.d.ts

@@ -0,0 +1,24 @@
+import type { IHttpHeaders } from "@3sixty/web";
+import type { IHttpRequestPathParams } from "./IHttpRequestPathParams.js";
+import type { IHttpRequestQuery } from "./IHttpRequestQuery.js";
+/**
+ * Model for the standard parameters for an http request.
+ */
+export interface IHttpRequest<T = any> {
+    /**
+     * Incoming Http Headers.
+     */
+    headers?: IHttpHeaders;
+    /**
+     * The path parameters.
+     */
+    pathParams?: IHttpRequestPathParams;
+    /**
+     * The query parameters.
+     */
+    query?: IHttpRequestQuery;
+    /**
+     * Data to return send as the body.
+     */
+    body?: T;
+}

package/dist/types/models/protocol/IHttpRequestContext.d.ts

@@ -0,0 +1,20 @@
+import type { IHttpServerRequest } from "./IHttpServerRequest.js";
+/**
+ * Context data from the HTTP request.
+ */
+export interface IHttpRequestContext {
+    /**
+     * The raw HTTP request.
+     */
+    serverRequest: IHttpServerRequest;
+    /**
+     * The state handed through the processors.
+     */
+    processorState: {
+        [id: string]: unknown;
+    };
+    /**
+     * Logging component type for the request.
+     */
+    loggingComponentType?: string;
+}