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

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

@@ -0,0 +1,6 @@
+/**
+ * Model for the standard parameters for an http request.
+ */
+export interface IHttpRequestPathParams {
+    [id: string]: string;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Model used for Http request query parameters.
+ */
+export interface IHttpRequestQuery {
+    [id: string]: string;
+}

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

@@ -0,0 +1,18 @@
+import type { HttpStatusCode, IHttpHeaders } from "@3sixty/web";
+/**
+ * Model for the standard parameters for an http response.
+ */
+export interface IHttpResponse<T = any> {
+    /**
+     * Response status code.
+     */
+    statusCode?: HttpStatusCode;
+    /**
+     * Response headers.
+     */
+    headers?: IHttpHeaders;
+    /**
+     * Data to return as the main payload.
+     */
+    body?: T;
+}

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

@@ -0,0 +1,15 @@
+import type { HttpMethod } from "@3sixty/web";
+import type { IHttpRequest } from "./IHttpRequest.js";
+/**
+ * Model for the standard parameters for an http request.
+ */
+export interface IHttpServerRequest<T = any> extends IHttpRequest<T> {
+    /**
+     * The request url.
+     */
+    url: string;
+    /**
+     * The request method.
+     */
+    method?: HttpMethod;
+}

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

@@ -0,0 +1,10 @@
+import type { IHttpRequestContext } from "./IHttpRequestContext.js";
+/**
+ * Context data from the socket request.
+ */
+export interface ISocketRequestContext extends IHttpRequestContext {
+    /**
+     * The id of the socket.
+     */
+    socketId: string;
+}

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

@@ -0,0 +1,10 @@
+import type { IHttpServerRequest } from "./IHttpServerRequest.js";
+/**
+ * Model for the standard parameters for an http request.
+ */
+export interface ISocketServerRequest<T = any> extends IHttpServerRequest<T> {
+    /**
+     * The socket id.
+     */
+    socketId: string;
+}

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

@@ -0,0 +1,22 @@
+import type { IHttpRequest } from "../protocol/IHttpRequest.js";
+/**
+ * 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 "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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,15 @@
+import type { IError } from "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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;
+}

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

@@ -0,0 +1,15 @@
+import type { IError } from "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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 "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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 "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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/INotImplementedResponse.d.ts

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

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

@@ -0,0 +1,15 @@
+import type { IError } from "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/web";
+/**
+ * The request resulted in too many requests, see the content for more details.
+ */
+export interface ITooManyRequestsResponse {
+    /**
+     * Response status code.
+     */
+    statusCode: typeof HttpStatusCode.tooManyRequests;
+    /**
+     * The body which contains the error.
+     */
+    body: IError;
+}

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

@@ -0,0 +1,15 @@
+import type { IError } from "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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 "@3sixty/core";
+import type { HttpStatusCode } from "@3sixty/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 "@3sixty/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 "@3sixty/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 "@3sixty/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 "@3sixty/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,39 @@
+import type { IRouteAuthorization } from "./IRouteAuthorization.js";
+/**
+ * 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 requirement for this route.
+     * @default false
+     */
+    skipAuth?: boolean;
+    /**
+     * Skips the tenant requirement for this route.
+     * @default false
+     */
+    skipTenant?: boolean;
+    /**
+     * Requires authorization for this route.
+     * @default true
+     */
+    requiresAuthorization?: boolean;
+    /**
+     * The default authorization which can access this route, used to seed the RBAC rules.
+     */
+    defaultAuthorization?: IRouteAuthorization;
+    /**
+     * Set to true to prevent callers from using the overrideTenant query parameter on this route.
+     * Tenant override is allowed by default, but you must hold the escalated privilege role to use it.
+     * @default false
+     */
+    disableTenantOverride?: boolean;
+}

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

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

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

@@ -0,0 +1,80 @@
+import type { HttpMethod } from "@3sixty/web";
+import type { IBaseRoute } from "./IBaseRoute.js";
+import type { IRestRouteRequestExample } from "./IRestRouteRequestExample.js";
+import type { IRestRouteResponseExample } from "./IRestRouteResponseExample.js";
+import type { IRestRouteResponseOptions } from "./IRestRouteResponseOptions.js";
+import type { IHttpRequest } from "../protocol/IHttpRequest.js";
+import type { IHttpRequestContext } from "../protocol/IHttpRequestContext.js";
+import type { IHttpResponse } from "../protocol/IHttpResponse.js";
+/**
+ * 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?: IRestRouteRequestExample<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?: IRestRouteResponseExample<U>[];
+    }[];
+    /**
+     * Exclude the route from being included in the spec file.
+     */
+    excludeFromSpec?: boolean;
+    /**
+     * The name of the body size limit to apply to the route, only used by methods that carry a body.
+     * If not provided, the default body size limit will be used. The body size limits are defined in the web server options.
+     */
+    bodyLimit?: string;
+}

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

@@ -0,0 +1,6 @@
+import type { IBaseRouteEntryPoint } from "./IBaseRouteEntryPoint.js";
+import type { IRestRoute } from "./IRestRoute.js";
+/**
+ * Route entry points are used for exposing the REST routes from a package.
+ */
+export type IRestRouteEntryPoint = IBaseRouteEntryPoint<IRestRoute>;

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

@@ -0,0 +1,13 @@
+/**
+ * Interface which defines a REST route example.
+ */
+export interface IRestRouteExample {
+    /**
+     * Example objects for the request.
+     */
+    id: string;
+    /**
+     * Description of the example.
+     */
+    description?: string;
+}

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

@@ -0,0 +1,10 @@
+import type { IRestRouteExample } from "./IRestRouteExample.js";
+/**
+ * Interface which defines a REST route request example.
+ */
+export interface IRestRouteRequestExample<T> extends IRestRouteExample {
+    /**
+     * The example request object.
+     */
+    request: T;
+}

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/IRestRouteResponseExample.d.ts

@@ -0,0 +1,10 @@
+import type { IRestRouteExample } from "./IRestRouteExample.js";
+/**
+ * Interface which defines a REST route response example.
+ */
+export interface IRestRouteResponseExample<T> extends IRestRouteExample {
+    /**
+     * The example response object.
+     */
+    response: T;
+}

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

@@ -0,0 +1,10 @@
+import type { IRestRouteResponseAttachmentOptions } from "./IRestRouteResponseAttachmentOptions.js";
+/**
+ * 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/IRouteAuthorization.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface which defines the default authorization permission for a route used to seed the RBAC rules.
+ */
+export interface IRouteAuthorization {
+    /**
+     * The permission string for the route.
+     */
+    permission: string;
+    /**
+     * The optional role string for the route.
+     */
+    role?: string;
+    /**
+     * The optional array of inherited permissions for the route.
+     */
+    inherits?: string[];
+}

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

@@ -0,0 +1,41 @@
+import type { IBaseRoute } from "./IBaseRoute.js";
+import type { IHttpRequest } from "../protocol/IHttpRequest.js";
+import type { IHttpResponse } from "../protocol/IHttpResponse.js";
+import type { ISocketRequestContext } from "../protocol/ISocketRequestContext.js";
+/**
+ * Interface which defines a socket route.
+ */
+export interface ISocketRoute<T extends IHttpRequest = any, U extends IHttpResponse = any> extends IBaseRoute {
+    /**
+     * The handler module.
+     */
+    handler: (
+    /**
+     * The request context.
+     */
+    socketRequestContext: ISocketRequestContext, 
+    /**
+     * The request object.
+     */
+    request: T, 
+    /**
+     * The function to emit an event.
+     */
+    emit: (event: string, response: U) => Promise<void>) => Promise<void>;
+    /**
+     * The connected handler.
+     */
+    connected?: (
+    /**
+     * The request context.
+     */
+    socketRequestContext: ISocketRequestContext) => Promise<void>;
+    /**
+     * The disconnected handler.
+     */
+    disconnected?: (
+    /**
+     * The request context.
+     */
+    socketRequestContext: ISocketRequestContext) => Promise<void>;
+}

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

@@ -0,0 +1,6 @@
+import type { IBaseRouteEntryPoint } from "./IBaseRouteEntryPoint.js";
+import type { ISocketRoute } from "./ISocketRoute.js";
+/**
+ * Route entry points are used for exposing the socket routes from a package.
+ */
+export type ISocketRouteEntryPoint = IBaseRouteEntryPoint<ISocketRoute>;

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/routes/httpBodyLimit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The names of the well-known body size limits for routes.
+ */
+export declare const HttpBodyLimit: {
+    /**
+     * The server default limit.
+     */
+    readonly Default: "default";
+    /**
+     * A large limit for routes carrying file payloads, defaults to 25 MiB.
+     */
+    readonly Large: "large";
+};
+/**
+ * The names of the well-known body size limits for routes.
+ */
+export type HttpBodyLimit = (typeof HttpBodyLimit)[keyof typeof HttpBodyLimit];