@twin.org/api-models 0.0.1-next.1

package/dist/types/models/requests/INoContentRequest.d.ts

@@ -0,0 +1,22 @@
+import type { IHttpRequest } from "../protocol/IHttpRequest";
+/**
+ * A REST request with no input parameters.
+ */
+export interface INoContentRequest extends IHttpRequest {
+    /**
+     * Incoming Http Headers.
+     */
+    headers?: never;
+    /**
+     * The path parameters.
+     */
+    pathParams?: never;
+    /**
+     * The query parameters.
+     */
+    query?: never;
+    /**
+     * Data to return send as the body.
+     */
+    body?: never;
+}

package/dist/types/models/responses/errors/IBadRequestResponse.d.ts

@@ -0,0 +1,15 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The server cannot process the request, see the content for more details.
+ */
+export interface IBadRequestResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.badRequest;
+    /**
+     * The body which contains the error.
+     */
+    body: IError;
+}

package/dist/types/models/responses/errors/IConflictResponse.d.ts

@@ -0,0 +1,20 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The request resulted in a conflicting operation, see the content for more details.
+ */
+export interface IConflictResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.conflict;
+    /**
+     * The body which contains the error.
+     */
+    body: IError & {
+        /**
+         * The conflicting items.
+         */
+        conflicts: string[];
+    };
+}

package/dist/types/models/responses/errors/IForbiddenResponse.d.ts

@@ -0,0 +1,15 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The operation that you tried to perform is not possible, see the content for more details.
+ */
+export interface IForbiddenResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.forbidden;
+    /**
+     * The body which contains the error.
+     */
+    body: IError;
+}

package/dist/types/models/responses/errors/IInternalServerErrorResponse.d.ts

@@ -0,0 +1,15 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The server has encountered a situation it does not know how to handle, see the content for more details.
+ */
+export interface IInternalServerErrorResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.internalServerError;
+    /**
+     * The body which contains the error.
+     */
+    body: IError;
+}

package/dist/types/models/responses/errors/INotFoundResponse.d.ts

@@ -0,0 +1,20 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The resource you tried to access does not exist, see the content for more details.
+ */
+export interface INotFoundResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.notFound;
+    /**
+     * The body which contains the error.
+     */
+    body: IError & {
+        /**
+         * The id if the item that was not found.
+         */
+        notFoundId?: string;
+    };
+}

package/dist/types/models/responses/errors/IUnauthorizedResponse.d.ts

@@ -0,0 +1,15 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * You are not authorized to use the API or no credentials were supplied, see the content for more details.
+ */
+export interface IUnauthorizedResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.unauthorized;
+    /**
+     * The body which contains the error.
+     */
+    body: IError;
+}

package/dist/types/models/responses/errors/IUnprocessableEntityResponse.d.ts

@@ -0,0 +1,15 @@
+import type { IError } from "@twin.org/core";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The server cannot process the request, see the content for more details.
+ */
+export interface IUnprocessableEntityResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.unprocessableEntity;
+    /**
+     * The body which contains the error.
+     */
+    body: IError;
+}

package/dist/types/models/responses/success/IAcceptedResponse.d.ts

@@ -0,0 +1,19 @@
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The rest request ended in accepted response.
+ */
+export interface IAcceptedResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.accepted;
+    /**
+     * Additional response headers.
+     */
+    headers: {
+        /**
+         * The location where the resource was accepted.
+         */
+        location: string;
+    };
+}

package/dist/types/models/responses/success/ICreatedResponse.d.ts

@@ -0,0 +1,19 @@
+import type { HeaderTypes, HttpStatusCode } from "@twin.org/web";
+/**
+ * The rest request ended in created response.
+ */
+export interface ICreatedResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.created;
+    /**
+     * Additional response headers.
+     */
+    headers: {
+        /**
+         * The location where the resource was created.
+         */
+        [HeaderTypes.Location]: string;
+    };
+}

package/dist/types/models/responses/success/INoContentResponse.d.ts

@@ -0,0 +1,10 @@
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The rest request ended in success with no data.
+ */
+export interface INoContentResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.noContent;
+}

package/dist/types/models/responses/success/IOkResponse.d.ts

@@ -0,0 +1,10 @@
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * The rest request ended in success with no data.
+ */
+export interface IOkResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.ok;
+}

package/dist/types/models/routes/IBaseRoute.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface which defines a route.
+ */
+export interface IBaseRoute {
+    /**
+     * The id of the operation.
+     */
+    operationId: string;
+    /**
+     * The path to use for routing.
+     */
+    path: string;
+    /**
+     * Skips the authentication for this route.
+     */
+    skipAuth?: boolean;
+}

package/dist/types/models/routes/IRestRoute.d.ts

@@ -0,0 +1,81 @@
+import type { HttpMethod } from "@twin.org/web";
+import type { IBaseRoute } from "./IBaseRoute";
+import type { IRestRouteResponseOptions } from "./IRestRouteResponseOptions";
+import type { IHttpRequest } from "../protocol/IHttpRequest";
+import type { IHttpRequestContext } from "../protocol/IHttpRequestContext";
+import type { IHttpResponse } from "../protocol/IHttpResponse";
+/**
+ * Interface which defines a REST route.
+ */
+export interface IRestRoute<T extends IHttpRequest = any, U extends IHttpResponse & IRestRouteResponseOptions = any> extends IBaseRoute {
+    /**
+     * Summary of what task the operation performs.
+     */
+    summary: string;
+    /**
+     * Tag for the operation.
+     */
+    tag: string;
+    /**
+     * The http method.
+     */
+    method: HttpMethod;
+    /**
+     * The handler module.
+     */
+    handler: (
+    /**
+     * The http request context.
+     */
+    httpRequestContext: IHttpRequestContext, 
+    /**
+     * The request object, combined query param, path params and body.
+     */
+    request: T) => Promise<U>;
+    /**
+     * The type of the request object.
+     */
+    requestType?: {
+        /**
+         * The object type for the request.
+         */
+        type: string;
+        /**
+         * The mime type of the request, defaults to "application/json" if there is a body.
+         */
+        mimeType?: string;
+        /**
+         * Example objects for the request.
+         */
+        examples?: {
+            id: string;
+            description?: string;
+            request: T;
+        }[];
+    };
+    /**
+     * The type of the response object.
+     */
+    responseType?: {
+        /**
+         * The object type of the response.
+         */
+        type: string;
+        /**
+         * The mime type of the response, defaults to "application/json" if there is a body.
+         */
+        mimeType?: string;
+        /**
+         * Example objects of the response.
+         */
+        examples?: {
+            id: string;
+            description?: string;
+            response: U;
+        }[];
+    }[];
+    /**
+     * Exclude the route from being included in the spec file.
+     */
+    excludeFromSpec?: boolean;
+}

package/dist/types/models/routes/IRestRouteEntryPoint.d.ts

@@ -0,0 +1,23 @@
+import type { IRestRoute } from "./IRestRoute";
+import type { ITag } from "./ITag";
+/**
+ * Route entry points are used for exposing the REST routes from a package.
+ */
+export interface IRestRouteEntryPoint {
+    /**
+     * The name of the REST routes.
+     */
+    name: string;
+    /**
+     * The default base route name for the REST routes.
+     */
+    defaultBaseRoute: string;
+    /**
+     * The tags for the REST routes.
+     */
+    tags: ITag[];
+    /**
+     * The method to generate the REST routes.
+     */
+    generateRoutes: (baseRouteName: string, componentName: string) => IRestRoute[];
+}

package/dist/types/models/routes/IRestRouteResponseAttachmentOptions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface which defines a REST route response for attachments.
+ */
+export interface IRestRouteResponseAttachmentOptions {
+    /**
+     * The content type to use in the response.
+     */
+    mimeType?: string;
+    /**
+     * The filename to use in content disposition.
+     */
+    filename?: string;
+    /**
+     * Whether to inline the content.
+     */
+    inline?: boolean;
+}

package/dist/types/models/routes/IRestRouteResponseOptions.d.ts

@@ -0,0 +1,10 @@
+import type { IRestRouteResponseAttachmentOptions } from "./IRestRouteResponseAttachmentOptions";
+/**
+ * Interface which defines a REST route response.
+ */
+export interface IRestRouteResponseOptions {
+    /**
+     * Additional options that can be used to control the response.
+     */
+    attachment?: IRestRouteResponseAttachmentOptions;
+}

package/dist/types/models/routes/ISocketRoute.d.ts

@@ -0,0 +1,27 @@
+import type { IBaseRoute } from "./IBaseRoute";
+import type { IHttpRequestContext } from "../protocol/IHttpRequestContext";
+/**
+ * Interface which defines a socket route.
+ */
+export interface ISocketRoute extends IBaseRoute {
+    /**
+     * The handler module.
+     */
+    handler: (
+    /**
+     * The request context.
+     */
+    httpRequestContext: IHttpRequestContext, 
+    /**
+     * The id of the socket the request is arriving on.
+     */
+    socketId: string, 
+    /**
+     * The request object.
+     */
+    request: unknown, 
+    /**
+     * Method to emit data on the socket.
+     */
+    emitter: (topic: string, response?: unknown) => Promise<void>) => Promise<void>;
+}

package/dist/types/models/routes/ITag.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tag for routes used to generate OpenAPI information.
+ */
+export interface ITag {
+    /**
+     * The name of the tag.
+     */
+    name: string;
+    /**
+     * Description for the tag.
+     */
+    description: string;
+}

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

@@ -0,0 +1,46 @@
+import type { IComponent } from "@twin.org/core";
+import type { IHttpRequestIdentity } from "../protocol/IHttpRequestIdentity";
+import type { IHttpResponse } from "../protocol/IHttpResponse";
+import type { IHttpServerRequest } from "../protocol/IHttpServerRequest";
+import type { IRestRoute } from "../routes/IRestRoute";
+/**
+ * The definition for a processor for handling REST routes.
+ */
+export interface IHttpRestRouteProcessor 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 requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     * @returns Promise that resolves when the request is processed.
+     */
+    pre?(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+    /**
+     * 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 requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     * @returns Promise that resolves when the request is processed.
+     */
+    process?(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): 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 requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     * @returns Promise that resolves when the request is processed.
+     */
+    post?(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

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

@@ -0,0 +1,31 @@
+import type { IHttpRestRouteProcessor } from "./IHttpRestRouteProcessor";
+import type { IWebServerOptions } from "./IWebServerOptions";
+import type { IRestRoute } from "../routes/IRestRoute";
+/**
+ * Interface describing a web server.
+ */
+export interface IWebServer<T> {
+    /**
+     * Get the web server instance.
+     * @returns The web server instance.
+     */
+    getInstance(): T;
+    /**
+     * Build the server.
+     * @param restRouteProcessors The hooks to process the incoming requests.
+     * @param restRoutes The REST routes.
+     * @param options Options for building the server.
+     * @returns Nothing.
+     */
+    build(restRouteProcessors: IHttpRestRouteProcessor[], restRoutes: IRestRoute[], options?: IWebServerOptions): Promise<void>;
+    /**
+     * Start the server.
+     * @returns Nothing.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server.
+     * @returns Nothing.
+     */
+    stop(): Promise<void>;
+}

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

@@ -0,0 +1,34 @@
+import type { HttpMethod } from "@twin.org/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", "DELETE", "OPTIONS"]
+     */
+    methods?: HttpMethod[];
+    /**
+     * Any additional allowed headers.
+     */
+    allowedHeaders?: string[];
+    /**
+     * And additional exposed headers.
+     */
+    exposedHeaders?: string[];
+    /**
+     * The allowed CORS domains.
+     * @default ["*"]
+     */
+    corsOrigins?: string | string[];
+}

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

@@ -0,0 +1,27 @@
+import type { HealthStatus } from "./healthStatus";
+/**
+ * The status of the server.
+ */
+export interface IHealthInfo {
+    /**
+     * The status.
+     */
+    status: HealthStatus;
+    /**
+     * The status of the components.
+     */
+    components?: {
+        /**
+         * The name of the component.
+         */
+        name: string;
+        /**
+         * The status of the component.
+         */
+        status: HealthStatus;
+        /**
+         * The details for the status.
+         */
+        details?: string;
+    }[];
+}

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

@@ -0,0 +1,38 @@
+import type { IComponent } from "@twin.org/core";
+import type { HealthStatus } from "./healthStatus";
+import type { IHealthInfo } from "./IHealthInfo";
+import type { IServerInfo } from "./IServerInfo";
+/**
+ * The information component for the server.
+ */
+export interface IInformationComponent extends IComponent {
+    /**
+     * Get the server information.
+     * @returns The service information.
+     */
+    info(): Promise<IServerInfo>;
+    /**
+     * Get the OpenAPI spec.
+     * @returns The OpenAPI spec.
+     */
+    spec(): Promise<unknown>;
+    /**
+     * Get the server health.
+     * @returns The service health.
+     */
+    health(): Promise<IHealthInfo>;
+    /**
+     * Set the status of a component.
+     * @param name The component name.
+     * @param status The status of the component.
+     * @param details The details for the status.
+     * @returns Nothing.
+     */
+    setComponentHealth(name: string, status: HealthStatus, details?: string): Promise<void>;
+    /**
+     * Remove the status of a component.
+     * @param name The component name.
+     * @returns Nothing.
+     */
+    removeComponentHealth(name: string): 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/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/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/api-models - Changelog
+
+## v0.0.1
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/api-models - Examples