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

package/docs/examples.md

@@ -0,0 +1,200 @@
+# Models Examples
+
+These snippets show practical helpers for URL manipulation, request parameter conversion, consistent error responses, and secure parameter encryption.
+
+## HttpUrlHelper
+
+```typescript
+import { HttpUrlHelper } from '@3sixty/api-models';
+
+const fullUrl = 'https://tenant.example.org/orders?page=2';
+
+console.log(HttpUrlHelper.extractOrigin(fullUrl)); // https://tenant.example.org
+console.log(HttpUrlHelper.extractPath(fullUrl)); // /orders
+console.log(HttpUrlHelper.extractSearch(fullUrl)); // ?page=2
+console.log(HttpUrlHelper.extractPathAndSearch(fullUrl)); // /orders?page=2
+```
+
+```typescript
+import { HttpUrlHelper } from '@3sixty/api-models';
+
+const combined = HttpUrlHelper.combineParts('https://tenant.example.org/', '/api/v1/orders');
+const replaced = HttpUrlHelper.replaceOrigin(combined ?? '', 'https://edge.example.org');
+
+console.log(combined); // https://tenant.example.org/api/v1/orders
+console.log(replaced); // https://edge.example.org/api/v1/orders
+```
+
+## HttpParameterHelper
+
+```typescript
+import { HttpParameterHelper } from '@3sixty/api-models';
+
+const ids = HttpParameterHelper.arrayFromString('id-1,id-2,id-3');
+const idsAsString = HttpParameterHelper.arrayToString(ids);
+
+const filterObject = HttpParameterHelper.objectFromString('{"status":"active"}');
+const filterString = HttpParameterHelper.objectToString(filterObject);
+
+console.log(ids.length); // 3
+console.log(idsAsString); // id-1,id-2,id-3
+console.log(filterString); // {"status":"active"}
+```
+
+## HttpErrorHelper
+
+```typescript
+import { HttpErrorHelper } from '@3sixty/api-models';
+
+try {
+  throw new Error('Invalid request');
+} catch (err) {
+  const mapped = HttpErrorHelper.processError(err, false);
+  const response: {
+    body?: unknown;
+    statusCode?: number;
+    headers?: { [id: string]: string };
+  } = {};
+  HttpErrorHelper.buildResponse(response, mapped.error, mapped.httpStatusCode);
+
+  console.log(response.statusCode); // 500
+  console.log(mapped.error.message); // Error: Invalid request
+}
+```
+
+## IHostingComponent
+
+When working with the hosting component, you can encrypt and decrypt query parameters for secure transmission. The encryption mechanism automatically handles salt generation to prevent rainbow table attacks.
+
+```typescript
+import type { IComponent, IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent extends IComponent {
+  addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+  getDecryptedParamsFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<IHttpRequestQuery>;
+  encryptParam(paramValue: string): Promise<string>;
+  decryptParam(encryptedValue: string): Promise<string>;
+}
+
+// Get the hosting component from the component factory
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt parameters and add them to a URL
+const baseUrl = 'https://api.example.com/callback';
+const encrypted = await hosting.addEncryptedParamsToUrl(baseUrl, {
+  token: 'secret-token-123',
+  userId: 'user-456'
+});
+console.log(encrypted); // https://api.example.com/callback?x-enc-token=...&x-enc-userId=...
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  addEncryptedParamsToUrl(url: string, params: IHttpRequestQuery): Promise<string>;
+  getDecryptedParamsFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<IHttpRequestQuery>;
+  encryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+  decryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Decrypt specific parameters from a query object
+const queryParams: IHttpRequestQuery = {
+  'x-enc-token': 'CngBAgMEBQYH...',
+  'x-enc-userId': 'CxgICSoLDAwN...',
+  status: 'active'
+};
+
+const decrypted = await hosting.getDecryptedParamsFromQueryParams(queryParams, ['token', 'userId']);
+console.log(decrypted); // { token: 'secret-token-123', userId: 'user-456' }
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  addTenantTokenToUrl(url: string, tenantId: string): Promise<string>;
+  getTenantTokenFromQueryParams(
+    queryParams: IHttpRequestQuery | undefined
+  ): Promise<string | undefined>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Add encrypted tenant token to a URL
+const redirectUrl = 'https://tenant.example.com/dashboard';
+const urlWithTenant = await hosting.addTenantTokenToUrl(
+  redirectUrl,
+  'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
+);
+console.log(urlWithTenant); // https://tenant.example.com/dashboard?x-enc-tenant-token=...
+```
+
+```typescript
+import type { IHttpRequestQuery } from '@3sixty/api-models';
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  encryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+  decryptQueryParams(
+    httpRequestQuery: IHttpRequestQuery | undefined,
+    keys: string[]
+  ): Promise<void>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt specific query parameters in place
+const query: IHttpRequestQuery = {
+  token: 'secret-123',
+  apiKey: 'key-456',
+  status: 'active'
+};
+
+await hosting.encryptQueryParams(query, ['token', 'apiKey']);
+console.log(query); // { 'x-enc-token': '...', 'x-enc-apiKey': '...', status: 'active' }
+
+// Decrypt the parameters back to their original keys
+await hosting.decryptQueryParams(query, ['token', 'apiKey']);
+console.log(query); // { token: 'secret-123', apiKey: 'key-456', status: 'active' }
+```
+
+```typescript
+import { ComponentFactory } from '@3sixty/core';
+
+interface IHostingComponent {
+  encryptParam(paramValue: string): Promise<string>;
+  decryptParam(encryptedValue: string): Promise<string>;
+}
+
+const hosting = ComponentFactory.get<IHostingComponent>('hosting');
+
+// Encrypt a single parameter value
+const plainText = 'confidential-data';
+const encrypted = await hosting.encryptParam(plainText);
+console.log(encrypted); // CngBAgMEBQYHCAkKCwwNDg8QERAh...
+
+// Decrypt the parameter value
+const decrypted = await hosting.decryptParam(encrypted);
+console.log(decrypted); // confidential-data
+```

package/docs/reference/classes/ForbiddenError.md

@@ -0,0 +1,57 @@
+# 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?
+
+\{\[`id`: `string`\]: `unknown`; \}
+
+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}
+
+`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-1}
+
+`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-2}
+
+`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-3}
+
+`T` = `unknown`
+
+#### Parameters
+
+##### value?
+
+`T`
+
+The value to convert to a string.
+
+#### Returns
+
+`string` \| `undefined`
+
+The converted object.