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

package/docs/examples.md

@@ -0,0 +1,81 @@
+# Tenant Processor Examples
+
+These snippets show tenant lifecycle management and request context routing for multi-tenant deployments.
+
+## TenantAdminService
+
+```typescript
+import { TenantAdminService } from '@3sixty/api-tenant-processor';
+
+const tenantAdmin = new TenantAdminService();
+
+console.log(tenantAdmin.className()); // TenantAdminService
+
+const createdTenantId = await tenantAdmin.create({
+  label: 'North Region',
+  apiKey: '0123456789abcdef0123456789abcdef',
+  publicOrigin: 'https://north.example.org'
+});
+
+await tenantAdmin.update({
+  id: createdTenantId,
+  label: 'North Region EU'
+});
+
+const byKey = await tenantAdmin.getByApiKey('0123456789abcdef0123456789abcdef');
+console.log(byKey.id.length); // 32
+```
+
+```typescript
+import { TenantAdminService } from '@3sixty/api-tenant-processor';
+
+const tenantAdmin = new TenantAdminService();
+
+const byId = await tenantAdmin.get('0123456789abcdef0123456789abcdef');
+const byOrigin = await tenantAdmin.getByPublicOrigin('https://north.example.org');
+const page = await tenantAdmin.query({ isNodeTenant: false }, '', 10);
+
+await tenantAdmin.remove(byId.id);
+
+console.log(byOrigin.label); // North Region EU
+console.log(page.tenants.length); // 1
+```
+
+## TenantIdContextIdHandler
+
+```typescript
+import { TenantIdContextIdHandler } from '@3sixty/api-tenant-processor';
+
+const handler = new TenantIdContextIdHandler();
+
+console.log(handler.className()); // TenantIdContextIdHandler
+console.log(handler.short('0123456789abcdef0123456789abcdef')); // ASNFZ4mrze8BI0VniavN7w
+
+handler.guard('0123456789abcdef0123456789abcdef');
+```
+
+## TenantProcessor
+
+```typescript
+import { TenantProcessor } from '@3sixty/api-tenant-processor';
+
+const tenantProcessor = new TenantProcessor();
+
+console.log(tenantProcessor.className()); // TenantProcessor
+
+const request = {
+  method: 'get',
+  url: '/info',
+  headers: {
+    'x-api-key': '0123456789abcdef0123456789abcdef'
+  },
+  query: {}
+};
+
+const response = {};
+const contextIds = {};
+const processorState: { [id: string]: unknown } = {};
+
+await tenantProcessor.pre(request, response, { skipTenant: false }, contextIds, processorState);
+console.log(typeof contextIds.tenant); // string
+```

package/docs/reference/classes/SingleTenantProcessor.md

@@ -0,0 +1,128 @@
+# Class: SingleTenantProcessor
+
+Injects the single-tenant organization ID into every request context and validates any organization query parameter.
+
+## Implements
+
+- `IBaseRouteProcessor`
+
+## Constructors
+
+### Constructor
+
+> **new SingleTenantProcessor**(`options?`): `SingleTenantProcessor`
+
+Create a new instance of SingleTenantProcessor.
+
+#### Parameters
+
+##### options?
+
+[`ISingleTenantProcessorConstructorOptions`](../interfaces/ISingleTenantProcessorConstructorOptions.md)
+
+Options for the processor.
+
+#### Returns
+
+`SingleTenantProcessor`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`IBaseRouteProcessor.className`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+Cache the node organization ID from the engine context so it can be injected into each
+per-request context without requiring a separate ContextIdProcessor for Organization.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the node organization ID has been cached.
+
+#### Implementation of
+
+`IBaseRouteProcessor.start`
+
+***
+
+### pre() {#pre}
+
+> **pre**(`request`, `response`, `route`, `contextIds`, `processorState`): `Promise`\<`void`\>
+
+Pre process the REST request for the specified route.
+
+#### Parameters
+
+##### request
+
+`IHttpServerRequest`
+
+The incoming request.
+
+##### response
+
+`IHttpResponse`
+
+The outgoing response.
+
+##### route
+
+`IBaseRoute` \| `undefined`
+
+The route to process.
+
+##### contextIds
+
+`IContextIds`
+
+The context IDs of the request.
+
+##### processorState
+
+The state handed through the processors.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the organization ID has been injected and any query parameter validated.
+
+#### Implementation of
+
+`IBaseRouteProcessor.pre`

package/docs/reference/classes/Tenant.md

@@ -0,0 +1,77 @@
+# Class: Tenant
+
+Class defining the storage for node tenants.
+
+## Constructors
+
+### Constructor
+
+> **new Tenant**(): `Tenant`
+
+#### Returns
+
+`Tenant`
+
+## Properties
+
+### id {#id}
+
+> **id**: `string`
+
+The unique identifier for the tenant.
+
+***
+
+### apiKey {#apikey}
+
+> **apiKey**: `string`
+
+The api key for the tenant.
+
+***
+
+### label {#label}
+
+> **label**: `string`
+
+The label of the tenant.
+
+***
+
+### dateCreated {#datecreated}
+
+> **dateCreated**: `string`
+
+The date the tenant was created.
+
+***
+
+### dateModified {#datemodified}
+
+> **dateModified**: `string`
+
+The date the tenant was modified.
+
+***
+
+### publicOrigin? {#publicorigin}
+
+> `optional` **publicOrigin?**: `string`
+
+The origin available to the public for accessing the API.
+
+***
+
+### organizationId {#organizationid}
+
+> **organizationId**: `string`
+
+The organization id for the tenant.
+
+***
+
+### organizationIdLegacy? {#organizationidlegacy}
+
+> `optional` **organizationIdLegacy?**: `string`[]
+
+Optional list of organization aliases that can be used for legacy lookups, indexed format.

package/docs/reference/classes/TenantAdminService.md

@@ -0,0 +1,393 @@
+# Class: TenantAdminService
+
+Service for performing tenant administration operations.
+
+## Implements
+
+- `ITenantAdminComponent`
+- `IHealthProviderComponent`
+
+## Constructors
+
+### Constructor
+
+> **new TenantAdminService**(`options?`): `TenantAdminService`
+
+Create a new instance of TenantAdminService.
+
+#### Parameters
+
+##### options?
+
+[`ITenantAdminServiceConstructorOptions`](../interfaces/ITenantAdminServiceConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`TenantAdminService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`ITenantAdminComponent.className`
+
+***
+
+### stop() {#stop}
+
+> **stop**(): `Promise`\<`void`\>
+
+Stop the service and release the tenant cache.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the service has stopped.
+
+#### Implementation of
+
+`ITenantAdminComponent.stop`
+
+***
+
+### get() {#get}
+
+> **get**(`tenantId`): `Promise`\<`ITenant`\>
+
+Get a tenant by its id.
+
+#### Parameters
+
+##### tenantId
+
+`string`
+
+The id of the tenant.
+
+#### Returns
+
+`Promise`\<`ITenant`\>
+
+The tenant.
+
+#### Throws
+
+Error if the tenant is not found.
+
+#### Implementation of
+
+`ITenantAdminComponent.get`
+
+***
+
+### getByApiKey() {#getbyapikey}
+
+> **getByApiKey**(`apiKey`): `Promise`\<`ITenant`\>
+
+Get a tenant by its api key.
+
+#### Parameters
+
+##### apiKey
+
+`string`
+
+The api key of the tenant.
+
+#### Returns
+
+`Promise`\<`ITenant`\>
+
+The tenant.
+
+#### Throws
+
+Error if the tenant is not found.
+
+#### Implementation of
+
+`ITenantAdminComponent.getByApiKey`
+
+***
+
+### getByPublicOrigin() {#getbypublicorigin}
+
+> **getByPublicOrigin**(`publicOrigin`): `Promise`\<`ITenant`\>
+
+Get a tenant by its public origin.
+
+#### Parameters
+
+##### publicOrigin
+
+`string`
+
+The origin of the tenant.
+
+#### Returns
+
+`Promise`\<`ITenant`\>
+
+The tenant.
+
+#### Throws
+
+Error if the tenant is not found.
+
+#### Implementation of
+
+`ITenantAdminComponent.getByPublicOrigin`
+
+***
+
+### getTenantByOrganizationId() {#gettenantbyorganizationid}
+
+> **getTenantByOrganizationId**(`organizationId`, `includeLegacy?`): `Promise`\<`ITenant`\>
+
+Get a tenant by its organization id, optionally searching legacy ids.
+
+#### Parameters
+
+##### organizationId
+
+`string`
+
+The organization id of the tenant.
+
+##### includeLegacy?
+
+`boolean`
+
+Whether to also search the legacy organization id array.
+
+#### Returns
+
+`Promise`\<`ITenant`\>
+
+The tenant.
+
+#### Throws
+
+Error if the tenant is not found.
+
+#### Implementation of
+
+`ITenantAdminComponent.getTenantByOrganizationId`
+
+***
+
+### create() {#create}
+
+> **create**(`tenant`): `Promise`\<`string`\>
+
+Create a tenant.
+
+#### Parameters
+
+##### tenant
+
+`Omit`\<`ITenant`, `"id"` \| `"dateCreated"` \| `"dateModified"`\> & `object`
+
+The tenant to store.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The tenant id.
+
+#### Implementation of
+
+`ITenantAdminComponent.create`
+
+***
+
+### update() {#update}
+
+> **update**(`tenant`): `Promise`\<`void`\>
+
+Update a tenant.
+
+#### Parameters
+
+##### tenant
+
+`Partial`\<`Omit`\<`ITenant`, `"dateCreated"` \| `"dateModified"`\>\>
+
+The tenant to update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the tenant has been updated.
+
+#### Implementation of
+
+`ITenantAdminComponent.update`
+
+***
+
+### remove() {#remove}
+
+> **remove**(`tenantId`): `Promise`\<`void`\>
+
+Remove a tenant by its id.
+
+#### Parameters
+
+##### tenantId
+
+`string`
+
+The id of the tenant.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`ITenantAdminComponent.remove`
+
+***
+
+### query() {#query}
+
+> **query**(`conditions?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `tenants`: `ITenant`[]; `cursor?`: `string`; \}\>
+
+Query tenants with pagination.
+
+#### Parameters
+
+##### conditions?
+
+`EntityCondition`\<`ITenant`\>
+
+The conditions to filter the tenants.
+
+##### properties?
+
+keyof `ITenant`[]
+
+The properties to include in the returned tenants.
+
+##### cursor?
+
+`string`
+
+The cursor to start from.
+
+##### limit?
+
+`number`
+
+The maximum number of tenants to return.
+
+#### Returns
+
+`Promise`\<\{ `tenants`: `ITenant`[]; `cursor?`: `string`; \}\>
+
+The tenants and the next cursor if more tenants are available.
+
+#### Implementation of
+
+`ITenantAdminComponent.query`
+
+***
+
+### healthApplicationInit() {#healthapplicationinit}
+
+> **healthApplicationInit**(`contextIds`): `Promise`\<`void`\>
+
+Provision a temporary tenant for the application health cycle.
+
+#### Parameters
+
+##### contextIds
+
+`IContextIds`
+
+Accumulated context IDs; receives the provisional tenant ID.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when provisioning is complete.
+
+#### Implementation of
+
+`IHealthProviderComponent.healthApplicationInit`
+
+***
+
+### healthApplication() {#healthapplication}
+
+> **healthApplication**(`callback`): `Promise`\<`IHealth`[] \| `undefined`\>
+
+Verify the provisioned tenant can be retrieved.
+The tenant ID is read from the active context set by the init pass.
+
+#### Parameters
+
+##### callback
+
+`HealthApplicationCallback`
+
+The callback to invoke when a deferred health result is ready.
+
+#### Returns
+
+`Promise`\<`IHealth`[] \| `undefined`\>
+
+The health entries for this component.
+
+#### Implementation of
+
+`IHealthProviderComponent.healthApplication`
+
+***
+
+### healthApplicationTeardown() {#healthapplicationteardown}
+
+> **healthApplicationTeardown**(): `Promise`\<`void`\>
+
+Remove the temporary tenant provisioned during init.
+The tenant ID is read from the active context set by the init pass.
+Does nothing when no tenant ID is present.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when teardown is complete.
+
+#### Implementation of
+
+`IHealthProviderComponent.healthApplicationTeardown`