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

package/docs/reference/classes/ScopeHelper.md

@@ -0,0 +1,88 @@
+# Class: ScopeHelper
+
+Helper methods for working with scope values stored as comma-separated strings.
+
+## Constructors
+
+### Constructor
+
+> **new ScopeHelper**(): `ScopeHelper`
+
+#### Returns
+
+`ScopeHelper`
+
+## Methods
+
+### toArray() {#toarray}
+
+> `static` **toArray**(`scope`): `string`[]
+
+Converts a scope value to a normalised lowercase array. Accepts either a comma-separated
+string or an already-split array, so callers do not need to branch on input type.
+Returns an empty array for an empty or undefined input.
+
+#### Parameters
+
+##### scope
+
+`string` \| `string`[] \| `undefined`
+
+The comma-separated scope string, or an array of scope entries.
+
+#### Returns
+
+`string`[]
+
+The scope entries as a trimmed, lowercase array.
+
+***
+
+### toString() {#tostring}
+
+> `static` **toString**(`scopes`): `string`
+
+Joins a scope array into a normalised comma-separated string, trimming and lowercasing each entry.
+
+#### Parameters
+
+##### scopes
+
+`string`[]
+
+The scope entries to join.
+
+#### Returns
+
+`string`
+
+The comma-separated scope string.
+
+***
+
+### includes() {#includes}
+
+> `static` **includes**(`scope`, `value`): `boolean`
+
+Returns true if the scope includes the specified value. Accepts either a
+comma-separated string or an array, matching the input forms accepted by toArray.
+
+#### Parameters
+
+##### scope
+
+`string` \| `string`[] \| `undefined`
+
+The comma-separated scope string or array to search.
+
+##### value
+
+`string`
+
+The scope value to look for.
+
+#### Returns
+
+`boolean`
+
+True when value is present in the scope.

package/docs/reference/classes/TooManyRequestsError.md

@@ -0,0 +1,67 @@
+# Class: TooManyRequestsError
+
+Class to handle errors which are triggered by too many requests.
+
+## Extends
+
+- `BaseError`
+
+## Constructors
+
+### Constructor
+
+> **new TooManyRequestsError**(`source`, `message`, `requestCount`, `nextRequestTime`, `properties?`, `cause?`): `TooManyRequestsError`
+
+Create a new instance of TooManyRequestsError.
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### message
+
+`string`
+
+The message as a code.
+
+##### requestCount
+
+`number`
+
+The current request count.
+
+##### nextRequestTime
+
+`string`
+
+The time when the next request can be made, as date ISO string.
+
+##### properties?
+
+Any additional information for the error.
+
+##### cause?
+
+`unknown`
+
+The cause of the error if we have wrapped another error.
+
+#### Returns
+
+`TooManyRequestsError`
+
+#### Overrides
+
+`BaseError.constructor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.

package/docs/reference/index.md

@@ -0,0 +1,92 @@
+# @3sixty/api-models
+
+## Classes
+
+- [ForbiddenError](classes/ForbiddenError.md)
+- [TooManyRequestsError](classes/TooManyRequestsError.md)
+- [HttpErrorHelper](classes/HttpErrorHelper.md)
+- [HttpHeaderHelper](classes/HttpHeaderHelper.md)
+- [HttpParameterHelper](classes/HttpParameterHelper.md)
+- [HttpUrlHelper](classes/HttpUrlHelper.md)
+- [ScopeHelper](classes/ScopeHelper.md)
+
+## Interfaces
+
+- [IHealth](interfaces/IHealth.md)
+- [IServerFavIconResponse](interfaces/IServerFavIconResponse.md)
+- [IServerHealthResponse](interfaces/IServerHealthResponse.md)
+- [IServerInfoResponse](interfaces/IServerInfoResponse.md)
+- [IServerLivezResponse](interfaces/IServerLivezResponse.md)
+- [IServerReadyzResponse](interfaces/IServerReadyzResponse.md)
+- [IServerRootResponse](interfaces/IServerRootResponse.md)
+- [IServerSpecResponse](interfaces/IServerSpecResponse.md)
+- [IRestClientProcessor](interfaces/IRestClientProcessor.md)
+- [IRestClientProcessorContext](interfaces/IRestClientProcessorContext.md)
+- [IBaseRestClientConfig](interfaces/IBaseRestClientConfig.md)
+- [IBaseSocketClientConfig](interfaces/IBaseSocketClientConfig.md)
+- [IHttpRequest](interfaces/IHttpRequest.md)
+- [IHttpRequestContext](interfaces/IHttpRequestContext.md)
+- [IHttpRequestPathParams](interfaces/IHttpRequestPathParams.md)
+- [IHttpRequestQuery](interfaces/IHttpRequestQuery.md)
+- [IHttpResponse](interfaces/IHttpResponse.md)
+- [IHttpServerRequest](interfaces/IHttpServerRequest.md)
+- [ISocketRequestContext](interfaces/ISocketRequestContext.md)
+- [ISocketServerRequest](interfaces/ISocketServerRequest.md)
+- [INoContentRequest](interfaces/INoContentRequest.md)
+- [IBadRequestResponse](interfaces/IBadRequestResponse.md)
+- [IConflictResponse](interfaces/IConflictResponse.md)
+- [IForbiddenResponse](interfaces/IForbiddenResponse.md)
+- [IInternalServerErrorResponse](interfaces/IInternalServerErrorResponse.md)
+- [INotFoundResponse](interfaces/INotFoundResponse.md)
+- [INotImplementedResponse](interfaces/INotImplementedResponse.md)
+- [ITooManyRequestsResponse](interfaces/ITooManyRequestsResponse.md)
+- [IUnauthorizedResponse](interfaces/IUnauthorizedResponse.md)
+- [IUnprocessableEntityResponse](interfaces/IUnprocessableEntityResponse.md)
+- [IAcceptedResponse](interfaces/IAcceptedResponse.md)
+- [ICreatedResponse](interfaces/ICreatedResponse.md)
+- [INoContentResponse](interfaces/INoContentResponse.md)
+- [IOkResponse](interfaces/IOkResponse.md)
+- [IBaseRoute](interfaces/IBaseRoute.md)
+- [IBaseRouteEntryPoint](interfaces/IBaseRouteEntryPoint.md)
+- [IRestRoute](interfaces/IRestRoute.md)
+- [IRestRouteExample](interfaces/IRestRouteExample.md)
+- [IRestRouteRequestExample](interfaces/IRestRouteRequestExample.md)
+- [IRestRouteResponseAttachmentOptions](interfaces/IRestRouteResponseAttachmentOptions.md)
+- [IRestRouteResponseExample](interfaces/IRestRouteResponseExample.md)
+- [IRestRouteResponseOptions](interfaces/IRestRouteResponseOptions.md)
+- [ISocketRoute](interfaces/ISocketRoute.md)
+- [ITag](interfaces/ITag.md)
+- [IBaseRouteProcessor](interfaces/IBaseRouteProcessor.md)
+- [IMimeTypeProcessor](interfaces/IMimeTypeProcessor.md)
+- [IRestRouteProcessor](interfaces/IRestRouteProcessor.md)
+- [ISocketRouteProcessor](interfaces/ISocketRouteProcessor.md)
+- [IWebServer](interfaces/IWebServer.md)
+- [IWebServerOptions](interfaces/IWebServerOptions.md)
+- [IHealthComponent](interfaces/IHealthComponent.md)
+- [IHealthProviderComponent](interfaces/IHealthProviderComponent.md)
+- [IInformationComponent](interfaces/IInformationComponent.md)
+- [IPlatformComponent](interfaces/IPlatformComponent.md)
+- [IServerInfo](interfaces/IServerInfo.md)
+- [ITenant](interfaces/ITenant.md)
+- [ITenantAdminComponent](interfaces/ITenantAdminComponent.md)
+
+## Type Aliases
+
+- [HealthCategory](type-aliases/HealthCategory.md)
+- [HealthStatus](type-aliases/HealthStatus.md)
+- [HttpContextIdKeys](type-aliases/HttpContextIdKeys.md)
+- [IRestRouteEntryPoint](type-aliases/IRestRouteEntryPoint.md)
+- [ISocketRouteEntryPoint](type-aliases/ISocketRouteEntryPoint.md)
+- [HttpBodyLimit](type-aliases/HttpBodyLimit.md)
+- [HealthApplicationCallback](type-aliases/HealthApplicationCallback.md)
+
+## Variables
+
+- [MimeTypeProcessorFactory](variables/MimeTypeProcessorFactory.md)
+- [RestClientProcessorFactory](variables/RestClientProcessorFactory.md)
+- [RestRouteProcessorFactory](variables/RestRouteProcessorFactory.md)
+- [SocketRouteProcessorFactory](variables/SocketRouteProcessorFactory.md)
+- [HealthCategory](variables/HealthCategory.md)
+- [HealthStatus](variables/HealthStatus.md)
+- [HttpContextIdKeys](variables/HttpContextIdKeys.md)
+- [HttpBodyLimit](variables/HttpBodyLimit.md)

package/docs/reference/interfaces/IAcceptedResponse.md

@@ -0,0 +1,25 @@
+# Interface: IAcceptedResponse
+
+The rest request ended in accepted response.
+
+## Properties
+
+### statusCode {#statuscode}
+
+> **statusCode**: `202`
+
+Response status code.
+
+***
+
+### headers {#headers}
+
+> **headers**: `object`
+
+Additional response headers.
+
+#### location
+
+> **location**: `string`
+
+The location where the resource was accepted.

package/docs/reference/interfaces/IBadRequestResponse.md

@@ -0,0 +1,19 @@
+# Interface: IBadRequestResponse
+
+The server cannot process the request, see the content for more details.
+
+## Properties
+
+### statusCode {#statuscode}
+
+> **statusCode**: `400`
+
+Response status code.
+
+***
+
+### body {#body}
+
+> **body**: `IError`
+
+The body which contains the error.

package/docs/reference/interfaces/IBaseRestClientConfig.md

@@ -0,0 +1,99 @@
+# Interface: IBaseRestClientConfig
+
+Definition for the configuration of a rest client.
+
+## Properties
+
+### endpoint {#endpoint}
+
+> **endpoint**: `string`
+
+The endpoint where the api is hosted.
+
+***
+
+### pathPrefix? {#pathprefix}
+
+> `optional` **pathPrefix?**: `string`
+
+The prefix to the routes.
+
+***
+
+### headers? {#headers}
+
+> `optional` **headers?**: `IHttpHeaders`
+
+The headers to include in requests.
+
+***
+
+### timeout? {#timeout}
+
+> `optional` **timeout?**: `number`
+
+Timeout for requests in ms.
+
+***
+
+### includeCredentials? {#includecredentials}
+
+> `optional` **includeCredentials?**: `boolean`
+
+Include credentials in the request, defaults to true.
+
+***
+
+### processorTypes? {#processortypes}
+
+> `optional` **processorTypes?**: `string`[]
+
+The types of the processors to run around each request, resolved from the `RestClientProcessorFactory`.
+
+***
+
+### customHeaders? {#customheaders}
+
+> `optional` **customHeaders?**: () => `Promise`\<`IHttpHeaders`\>
+
+Hook to provide headers asynchronously.
+
+#### Returns
+
+`Promise`\<`IHttpHeaders`\>
+
+A promise that resolves to the headers.
+
+***
+
+### customAuthHeader? {#customauthheader}
+
+> `optional` **customAuthHeader?**: () => `Promise`\<`string`\>
+
+Hook to provide an authorization header value asynchronously.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the authorization header value.
+
+***
+
+### onAuthFailure? {#onauthfailure}
+
+> `optional` **onAuthFailure?**: (`err`) => `Promise`\<`void`\>
+
+Hook to handle authorization failures asynchronously.
+
+#### Parameters
+
+##### err
+
+`IError`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the auth failure handling is complete.

package/docs/reference/interfaces/IBaseRoute.md

@@ -0,0 +1,57 @@
+# Interface: IBaseRoute
+
+Interface which defines a route.
+
+## Extended by
+
+- [`IRestRoute`](IRestRoute.md)
+- [`ISocketRoute`](ISocketRoute.md)
+
+## Properties
+
+### operationId {#operationid}
+
+> **operationId**: `string`
+
+The id of the operation.
+
+***
+
+### path {#path}
+
+> **path**: `string`
+
+The path to use for routing.
+
+***
+
+### skipAuth? {#skipauth}
+
+> `optional` **skipAuth?**: `boolean`
+
+Skips the authentication requirement for this route.
+
+***
+
+### skipTenant? {#skiptenant}
+
+> `optional` **skipTenant?**: `boolean`
+
+Skips the tenant requirement for this route.
+
+***
+
+### requiredScope? {#requiredscope}
+
+> `optional` **requiredScope?**: `string`[]
+
+The user must have one of the specified scopes to access the route.
+
+***
+
+### disableTenantOverride? {#disabletenantoverride}
+
+> `optional` **disableTenantOverride?**: `boolean`
+
+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 scope to use it.

package/docs/reference/interfaces/IBaseRouteEntryPoint.md

@@ -0,0 +1,55 @@
+# Interface: IBaseRouteEntryPoint\<T\>
+
+Route entry points are used for exposing the routes from a package.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Properties
+
+### name {#name}
+
+> **name**: `string`
+
+The name of the routes.
+
+***
+
+### defaultBaseRoute {#defaultbaseroute}
+
+> **defaultBaseRoute**: `string`
+
+The default base route name for the routes.
+
+***
+
+### tags {#tags}
+
+> **tags**: [`ITag`](ITag.md)[]
+
+The tags for the routes.
+
+***
+
+### generateRoutes {#generateroutes}
+
+> **generateRoutes**: (`baseRouteName`, `componentName`) => `T`[]
+
+The method to generate the routes.
+
+#### Parameters
+
+##### baseRouteName
+
+`string`
+
+##### componentName
+
+`string`
+
+#### Returns
+
+`T`[]

package/docs/reference/interfaces/IBaseRouteProcessor.md

@@ -0,0 +1,146 @@
+# Interface: IBaseRouteProcessor\<T, R\>
+
+The definition for a base processor for handling REST routes.
+
+## Extends
+
+- `IComponent`
+
+## Extended by
+
+- [`IRestRouteProcessor`](IRestRouteProcessor.md)
+- [`ISocketRouteProcessor`](ISocketRouteProcessor.md)
+
+## Type Parameters
+
+### T
+
+`T` = [`IBaseRoute`](IBaseRoute.md)
+
+### R
+
+`R` = [`IHttpServerRequest`](IHttpServerRequest.md)
+
+## Methods
+
+### features()? {#features}
+
+> `optional` **features**(): `string`[]
+
+Features supported by this processor.
+If a route has any of these features listed, this processor will be run for that route.
+If this is not implemented, the processor will run for all routes.
+
+#### Returns
+
+`string`[]
+
+The features supported by this processor.
+
+***
+
+### pre()? {#pre}
+
+> `optional` **pre**(`request`, `response`, `route`, `contextIds`, `processorState`, `componentTypes?`): `Promise`\<`void`\>
+
+Pre process the REST request for the specified route.
+
+#### Parameters
+
+##### request
+
+`R`
+
+The request to handle.
+
+##### response
+
+[`IHttpResponse`](IHttpResponse.md)
+
+The response data to send if any.
+
+##### route
+
+`T` \| `undefined`
+
+The route being requested, if a matching one was found.
+
+##### contextIds
+
+`IContextIds`
+
+The context IDs of the request.
+
+##### processorState
+
+The state handed through the processors.
+
+##### componentTypes?
+
+The component types for the request.
+
+###### loggingComponentType?
+
+`string`
+
+The logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Promise that resolves when the request is processed.
+
+***
+
+### post()? {#post}
+
+> `optional` **post**(`request`, `response`, `route`, `contextIds`, `processorState`, `componentTypes?`): `Promise`\<`void`\>
+
+Post process the REST request for the specified route.
+
+#### Parameters
+
+##### request
+
+`R`
+
+The request to handle.
+
+##### response
+
+[`IHttpResponse`](IHttpResponse.md)
+
+The response data to send if any.
+
+##### route
+
+`T` \| `undefined`
+
+The route being requested, if a matching one was found.
+
+##### contextIds
+
+`IContextIds`
+
+The context IDs of the request.
+
+##### processorState
+
+The state handed through the processors.
+
+##### componentTypes?
+
+The component types for the request.
+
+###### loggingComponentType?
+
+`string`
+
+The logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Promise that resolves when the request is processed.

package/docs/reference/interfaces/IBaseSocketClientConfig.md

@@ -0,0 +1,35 @@
+# Interface: IBaseSocketClientConfig
+
+Definition for the configuration of a socket service.
+
+## Properties
+
+### basePath? {#basepath}
+
+> `optional` **basePath?**: `string`
+
+Base path for the socket service, defaults to /socket.
+
+***
+
+### endpoint {#endpoint}
+
+> **endpoint**: `string`
+
+The endpoint where the api is hosted.
+
+***
+
+### pathPrefix? {#pathprefix}
+
+> `optional` **pathPrefix?**: `string`
+
+The prefix to the routes.
+
+***
+
+### headers? {#headers}
+
+> `optional` **headers?**: `IHttpHeaders`
+
+The headers to include in requests.

package/docs/reference/interfaces/IConflictResponse.md

@@ -0,0 +1,19 @@
+# Interface: IConflictResponse
+
+The request resulted in a conflicting operation, see the content for more details.
+
+## Properties
+
+### statusCode {#statuscode}
+
+> **statusCode**: `409`
+
+Response status code.
+
+***
+
+### body {#body}
+
+> **body**: `IError`
+
+The body which contains the error.