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

package/docs/reference/classes/ForbiddenError.md

@@ -0,0 +1,55 @@
+# Class: ForbiddenError
+
+Class to handle errors which are triggered by forbidden actions.
+
+## Extends
+
+- `BaseError`
+
+## Constructors
+
+### Constructor
+
+> **new ForbiddenError**(`source`, `message`, `properties?`, `cause?`): `ForbiddenError`
+
+Create a new instance of ForbiddenError.
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### message
+
+`string`
+
+The message as a code.
+
+##### properties?
+
+Any additional information for the error.
+
+##### cause?
+
+`unknown`
+
+The cause of the error if we have wrapped another error.
+
+#### Returns
+
+`ForbiddenError`
+
+#### Overrides
+
+`BaseError.constructor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.

package/docs/reference/classes/HttpErrorHelper.md

@@ -0,0 +1,99 @@
+# Class: HttpErrorHelper
+
+Class to help with processing http errors.
+
+## Constructors
+
+### Constructor
+
+> **new HttpErrorHelper**(): `HttpErrorHelper`
+
+#### Returns
+
+`HttpErrorHelper`
+
+## Properties
+
+### ERROR\_TYPE\_MAP {#error_type_map}
+
+> `readonly` `static` **ERROR\_TYPE\_MAP**: `object`
+
+Mapping of error types to status codes.
+
+#### Index Signature
+
+\[`id`: `string`\]: `HttpStatusCode`
+
+## Methods
+
+### processError() {#processerror}
+
+> `static` **processError**(`err`, `includeStack?`): `object`
+
+Process the errors from the routes.
+
+#### Parameters
+
+##### err
+
+`unknown`
+
+The error to process.
+
+##### includeStack?
+
+`boolean`
+
+Should the stack be included in the error.
+
+#### Returns
+
+`object`
+
+The status code and additional error data.
+
+##### error
+
+> **error**: `IError`
+
+##### httpStatusCode
+
+> **httpStatusCode**: `HttpStatusCode`
+
+***
+
+### buildResponse() {#buildresponse}
+
+> `static` **buildResponse**(`response`, `error`, `statusCode`, `includeStack`): `void`
+
+Build an error response.
+
+#### Parameters
+
+##### response
+
+[`IHttpResponse`](../interfaces/IHttpResponse.md)
+
+The response to build the error into.
+
+##### error
+
+`IError`
+
+The error to build the response for.
+
+##### statusCode
+
+`HttpStatusCode`
+
+The status code to use for the error.
+
+##### includeStack
+
+`boolean`
+
+Should the stack be included in the error.
+
+#### Returns
+
+`void`

package/docs/reference/classes/HttpHeaderHelper.md

@@ -0,0 +1,182 @@
+# Class: HttpHeaderHelper
+
+Class to help with handling http headers.
+
+## Constructors
+
+### Constructor
+
+> **new HttpHeaderHelper**(): `HttpHeaderHelper`
+
+#### Returns
+
+`HttpHeaderHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### buildCursor() {#buildcursor}
+
+> `static` **buildCursor**(`headers`, `url`, `publicOrigin`, `cursor`): asserts headers is IHttpHeaders & \{ link: string \| undefined \}
+
+Set the Link header with a next cursor relation when a cursor is present.
+
+#### Parameters
+
+##### headers
+
+`IHttpHeaders`
+
+The response headers to mutate.
+
+##### url
+
+`string`
+
+The request URL used as the base for the link.
+
+##### publicOrigin
+
+`string` \| `undefined`
+
+The public origin to substitute into the URL, if any.
+
+##### cursor
+
+`string` \| `undefined`
+
+The cursor value; when undefined or empty the header is not set.
+
+#### Returns
+
+asserts headers is IHttpHeaders & \{ link: string \| undefined \}
+
+***
+
+### buildId() {#buildid}
+
+> `static` **buildId**(`headers`, `id`, `urlTemplate?`): `asserts headers is IHttpHeaders & { location: string }`
+
+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.
+
+#### Parameters
+
+##### headers
+
+`IHttpHeaders`
+
+The response headers to mutate.
+
+##### id
+
+`string`
+
+The resource ID to encode and place.
+
+##### urlTemplate?
+
+`string`
+
+The optional URL template (absolute or relative).
+
+#### Returns
+
+`asserts headers is IHttpHeaders & { location: string }`
+
+***
+
+### buildJsonContentType() {#buildjsoncontenttype}
+
+> `static` **buildJsonContentType**(`headers`, `requestHeaders?`): asserts headers is IHttpHeaders & \{ content-type: "application/json" \| "application/ld+json" \}
+
+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.
+
+#### Parameters
+
+##### headers
+
+`IHttpHeaders`
+
+The response headers to mutate.
+
+##### requestHeaders?
+
+`IHttpHeaders`
+
+The request headers to inspect for the Accept value.
+
+#### Returns
+
+asserts headers is IHttpHeaders & \{ content-type: "application/json" \| "application/ld+json" \}
+
+***
+
+### extractCursor() {#extractcursor}
+
+> `static` **extractCursor**(`headers?`): `string` \| `undefined`
+
+Extract the cursor from the Link header's next relation.
+
+#### Parameters
+
+##### headers?
+
+`IHttpHeaders`
+
+The response headers to extract the cursor from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The cursor value or undefined if not present.
+
+***
+
+### extractId() {#extractid}
+
+> `static` **extractId**(`headers?`, `templateUrl?`): `string`
+
+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.
+
+#### Parameters
+
+##### headers?
+
+`IHttpHeaders`
+
+The response headers containing the Location header.
+
+##### templateUrl?
+
+`string`
+
+Optional URL template containing the ':id' placeholder, e.g. "/path1/:id/path2".
+
+#### Returns
+
+`string`
+
+The extracted ID string.
+
+#### Throws
+
+GeneralError If the Location header is missing or the ID cannot be extracted.

package/docs/reference/classes/HttpParameterHelper.md

@@ -0,0 +1,125 @@
+# Class: HttpParameterHelper
+
+Class to help with handling http parameters.
+
+## Constructors
+
+### Constructor
+
+> **new HttpParameterHelper**(): `HttpParameterHelper`
+
+#### Returns
+
+`HttpParameterHelper`
+
+## Methods
+
+### arrayFromString() {#arrayfromstring}
+
+> `static` **arrayFromString**\<`T`\>(`values?`): `T`[] \| `undefined`
+
+Convert list query to array.
+
+#### Type Parameters
+
+##### T
+
+`T` = `string`
+
+#### Parameters
+
+##### values?
+
+`string`
+
+The values query string.
+
+#### Returns
+
+`T`[] \| `undefined`
+
+The array of values.
+
+***
+
+### arrayToString() {#arraytostring}
+
+> `static` **arrayToString**\<`T`\>(`values?`): `string` \| `undefined`
+
+Convert array of values to query string.
+
+#### Type Parameters
+
+##### T
+
+`T` = `string`
+
+#### Parameters
+
+##### values?
+
+`T`[]
+
+The values to combine string.
+
+#### Returns
+
+`string` \| `undefined`
+
+The combined.
+
+***
+
+### objectFromString() {#objectfromstring}
+
+> `static` **objectFromString**\<`T`\>(`value?`): `T` \| `undefined`
+
+Convert object string to object.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### value?
+
+`string`
+
+The value query string.
+
+#### Returns
+
+`T` \| `undefined`
+
+The object.
+
+***
+
+### objectToString() {#objecttostring}
+
+> `static` **objectToString**\<`T`\>(`value?`): `string` \| `undefined`
+
+Convert object to query string.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### value?
+
+`T`
+
+The value to convert to a string.
+
+#### Returns
+
+`string` \| `undefined`
+
+The converted object.

package/docs/reference/classes/HttpUrlHelper.md

@@ -0,0 +1,262 @@
+# Class: HttpUrlHelper
+
+Class to help with handling http URLs.
+
+## Constructors
+
+### Constructor
+
+> **new HttpUrlHelper**(): `HttpUrlHelper`
+
+#### Returns
+
+`HttpUrlHelper`
+
+## Methods
+
+### extractOrigin() {#extractorigin}
+
+> `static` **extractOrigin**(`url`): `string` \| `undefined`
+
+Extract the origin from the url which includes protocol,host,port.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the origin from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted origin.
+
+#### See
+
+https://developer.mozilla.org/en-US/docs/Web/API/URL/origin
+
+***
+
+### extractPath() {#extractpath}
+
+> `static` **extractPath**(`url`): `string` \| `undefined`
+
+Extract the path from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the path from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted path.
+
+#### See
+
+https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname
+
+***
+
+### extractSearch() {#extractsearch}
+
+> `static` **extractSearch**(`url`): `string` \| `undefined`
+
+Extract the search from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the search from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted search.
+
+#### See
+
+https://developer.mozilla.org/en-US/docs/Web/API/URL/search
+
+***
+
+### extractPathAndSearch() {#extractpathandsearch}
+
+> `static` **extractPathAndSearch**(`url`): `string` \| `undefined`
+
+Extract the path and search from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to extract the path and search from.
+
+#### Returns
+
+`string` \| `undefined`
+
+The extracted path and search.
+
+***
+
+### combineOriginPath() {#combineoriginpath}
+
+> `static` **combineOriginPath**(`origin?`, `path?`): `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.
+
+#### Parameters
+
+##### origin?
+
+`string`
+
+The optional origin (e.g. "https://example.com").
+
+##### path?
+
+`string`
+
+The optional path or URL template (e.g. "/api/items" or "api/items").
+
+#### Returns
+
+`string` \| `undefined`
+
+The combined string, or undefined when both are absent.
+
+***
+
+### encodeUriPathSegment() {#encodeuripathsegment}
+
+> `static` **encodeUriPathSegment**(`segment`): `string`
+
+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.
+
+#### Parameters
+
+##### segment
+
+`string`
+
+The raw path segment value to encode.
+
+#### Returns
+
+`string`
+
+The percent-encoded path segment.
+
+#### See
+
+https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+
+***
+
+### replaceOrigin() {#replaceorigin}
+
+> `static` **replaceOrigin**(`url`, `newOrigin?`): `string`
+
+Replace the origin in the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to replace the origin in.
+
+##### newOrigin?
+
+`string`
+
+The new origin to use.
+
+#### Returns
+
+`string`
+
+The url with the replaced origin.
+
+***
+
+### addQueryStringParam() {#addquerystringparam}
+
+> `static` **addQueryStringParam**(`url`, `key`, `value`): `string`
+
+Add a query string parameter to the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to add the query string parameter to.
+
+##### key
+
+`string`
+
+The key of the query string parameter.
+
+##### value
+
+`string`
+
+The value of the query string parameter.
+
+#### Returns
+
+`string`
+
+The url with the added query string parameter.
+
+***
+
+### getQueryStringParam() {#getquerystringparam}
+
+> `static` **getQueryStringParam**(`url`, `key`): `string` \| `undefined`
+
+Get a query string parameter from the url.
+
+#### Parameters
+
+##### url
+
+`string`
+
+The url to get the query string parameter from.
+
+##### key
+
+`string`
+
+The key of the query string parameter.
+
+#### Returns
+
+`string` \| `undefined`
+
+The value of the query string parameter.