@twin.org/api-auth-entity-storage-rest-client 0.0.3-next.4 → 0.0.3-next.41

package/docs/examples.md

@@ -1 +1,111 @@
-# @twin.org/api-auth-entity-storage-rest-client - Examples
+# Auth Entity Storage Rest Client Examples
+
+Use these snippets to integrate sign-in and user administration flows from browser or server-side TypeScript applications.
+
+## EntityStorageAuthenticationAdminRestClient
+
+```typescript
+import { EntityStorageAuthenticationAdminRestClient } from '@twin.org/api-auth-entity-storage-rest-client';
+
+const adminClient = new EntityStorageAuthenticationAdminRestClient({
+  endpoint: 'https://api.example.org',
+  pathPrefix: 'v1'
+});
+
+console.log(adminClient.className()); // EntityStorageAuthenticationAdminRestClient
+
+await adminClient.create({
+  email: 'ops@example.org',
+  password: 'StrongPassword123',
+  userIdentity: 'did:example:ops',
+  organizationIdentity: 'did:example:core',
+  scope: ['admin']
+});
+
+await adminClient.update({
+  email: 'ops@example.org',
+  userIdentity: 'did:example:ops:team',
+  scope: ['admin', 'support']
+});
+
+await adminClient.updatePassword('ops@example.org', 'StrongPassword124', 'StrongPassword123');
+const adminUser = await adminClient.get('ops@example.org');
+console.log(adminUser.email); // ops@example.org
+```
+
+```typescript
+import { EntityStorageAuthenticationAdminRestClient } from '@twin.org/api-auth-entity-storage-rest-client';
+
+const adminClient = new EntityStorageAuthenticationAdminRestClient({
+  endpoint: 'https://api.example.org',
+  pathPrefix: 'v1'
+});
+
+const byEmail = await adminClient.get('ops@example.org');
+const byIdentity = await adminClient.getByIdentity('ops-team@example.org');
+await adminClient.remove('ops@example.org');
+
+console.log(byEmail.email); // ops@example.org
+console.log(byIdentity.userIdentity); // did:example:ops:team
+```
+
+## EntityStorageAuthenticationRestClient
+
+```typescript
+import { EntityStorageAuthenticationRestClient } from '@twin.org/api-auth-entity-storage-rest-client';
+
+const authClient = new EntityStorageAuthenticationRestClient({
+  endpoint: 'https://api.example.org',
+  pathPrefix: 'v1',
+  cookieName: 'access_token'
+});
+
+console.log(authClient.className()); // EntityStorageAuthenticationRestClient
+
+const loginResponse = await authClient.login('alice@example.org', 'correct-horse-battery-staple');
+
+await authClient.updatePassword('correct-horse-battery-staple', 'correct-horse-battery-staple-2');
+
+const refreshResponse = await authClient.refresh(loginResponse.token);
+
+await authClient.logout(refreshResponse.token);
+console.log(refreshResponse.expiry > 0); // true
+```
+
+## EntityStorageAuthenticationAuditRestClient
+
+```typescript
+import { EntityStorageAuthenticationAuditRestClient } from '@twin.org/api-auth-entity-storage-rest-client';
+
+const auditClient = new EntityStorageAuthenticationAuditRestClient({
+  endpoint: 'https://api.example.org',
+  pathPrefix: 'v1'
+});
+
+console.log(auditClient.className()); // EntityStorageAuthenticationAuditRestClient
+
+const auditEntryId = await auditClient.create({
+  event: 'login-success',
+  actorId: 'did:example:user:alice',
+  organizationId: 'did:example:org:core',
+  tenantId: 'did:example:tenant:alpha',
+  data: {
+    channel: 'web'
+  }
+});
+
+const auditResult = await auditClient.query(
+  {
+    actorId: 'did:example:user:alice',
+    event: 'login-success',
+    startDate: '2026-04-01T00:00:00.000Z',
+    endDate: '2026-04-30T23:59:59.999Z'
+  },
+  undefined,
+  25
+);
+
+console.log(auditEntryId); // /authentication/audit/018f2f67bb9d4a0caad8386f56df85ce
+console.log(auditResult.entries.length); // 1
+console.log(auditResult.cursor); // eyJpZCI6IjAxOGYyZjY3YmI5ZDRhMGNhYWQ4Mzg2ZjU2ZGY4NWNlIn0=
+```

package/docs/reference/classes/EntityStorageAuthenticationAdminRestClient.md

@@ -0,0 +1,295 @@
+# Class: EntityStorageAuthenticationAdminRestClient
+
+The client to connect to the authentication admin service.
+
+## Extends
+
+- `BaseRestClient`
+
+## Implements
+
+- `IAuthenticationAdminComponent`
+
+## Constructors
+
+### Constructor
+
+> **new EntityStorageAuthenticationAdminRestClient**(`config`): `EntityStorageAuthenticationAdminRestClient`
+
+Create a new instance of EntityStorageAuthenticationAdminRestClient.
+
+#### Parameters
+
+##### config
+
+`IBaseRestClientConfig`
+
+The configuration for the client.
+
+#### Returns
+
+`EntityStorageAuthenticationAdminRestClient`
+
+#### Overrides
+
+`BaseRestClient.constructor`
+
+## 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
+
+`IAuthenticationAdminComponent.className`
+
+***
+
+### create() {#create}
+
+> **create**(`user`): `Promise`\<`void`\>
+
+Create a login for the user.
+
+#### Parameters
+
+##### user
+
+`IAuthenticationUser` & `object`
+
+The user to create.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.create`
+
+***
+
+### update() {#update}
+
+> **update**(`user`): `Promise`\<`void`\>
+
+Update a login for the user.
+
+#### Parameters
+
+##### user
+
+`Partial`\<`IAuthenticationUser`\>
+
+The user to update.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.update`
+
+***
+
+### get() {#get}
+
+> **get**(`email`): `Promise`\<`IAuthenticationUser`\>
+
+Get a user by email.
+
+#### Parameters
+
+##### email
+
+`string`
+
+The email address of the user to get.
+
+#### Returns
+
+`Promise`\<`IAuthenticationUser`\>
+
+The user details.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.get`
+
+***
+
+### getByIdentity() {#getbyidentity}
+
+> **getByIdentity**(`identity`): `Promise`\<`IAuthenticationUser`\>
+
+Get a user by identity.
+
+#### Parameters
+
+##### identity
+
+`string`
+
+The identity of the user to get.
+
+#### Returns
+
+`Promise`\<`IAuthenticationUser`\>
+
+The user details.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.getByIdentity`
+
+***
+
+### remove() {#remove}
+
+> **remove**(`email`): `Promise`\<`void`\>
+
+Remove a user.
+
+#### Parameters
+
+##### email
+
+`string`
+
+The email address of the user to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.remove`
+
+***
+
+### updatePassword() {#updatepassword}
+
+> **updatePassword**(`email`, `newPassword`, `currentPassword?`): `Promise`\<`void`\>
+
+Update the user's password.
+
+#### Parameters
+
+##### email
+
+`string`
+
+The email address of the user to update.
+
+##### newPassword
+
+`string`
+
+The new password for the user.
+
+##### currentPassword?
+
+`string`
+
+The current password, optional, if supplied will check against existing.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IAuthenticationAdminComponent.updatePassword`
+
+***
+
+### getEndpointWithPrefix() {#getendpointwithprefix}
+
+> **getEndpointWithPrefix**(): `string`
+
+Get the endpoint with the prefix for the namespace.
+
+#### Returns
+
+`string`
+
+The endpoint with namespace prefix attached.
+
+#### Inherited from
+
+`BaseRestClient.getEndpointWithPrefix`
+
+***
+
+### fetch() {#fetch}
+
+> **fetch**\<`T`, `U`\>(`route`, `method`, `request?`): `Promise`\<`U`\>
+
+Perform a request in json format.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `IHttpRequest`\<`any`\>
+
+##### U
+
+`U` *extends* `IHttpResponse`\<`any`\>
+
+#### Parameters
+
+##### route
+
+`string`
+
+The route of the request.
+
+##### method
+
+`HttpMethod`
+
+The http method.
+
+##### request?
+
+`T`
+
+Request to send to the endpoint.
+
+#### Returns
+
+`Promise`\<`U`\>
+
+The response.
+
+#### Inherited from
+
+`BaseRestClient.fetch`

package/docs/reference/classes/EntityStorageAuthenticationAuditRestClient.md

@@ -0,0 +1,231 @@
+# Class: EntityStorageAuthenticationAuditRestClient
+
+The client to connect to the authentication audit service.
+
+## Extends
+
+- `BaseRestClient`
+
+## Implements
+
+- `IAuthenticationAuditComponent`
+
+## Constructors
+
+### Constructor
+
+> **new EntityStorageAuthenticationAuditRestClient**(`config`): `EntityStorageAuthenticationAuditRestClient`
+
+Create a new instance of EntityStorageAuthenticationAuditRestClient.
+
+#### Parameters
+
+##### config
+
+`IBaseRestClientConfig`
+
+The configuration for the client.
+
+#### Returns
+
+`EntityStorageAuthenticationAuditRestClient`
+
+#### Overrides
+
+`BaseRestClient.constructor`
+
+## 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
+
+`IAuthenticationAuditComponent.className`
+
+***
+
+### create() {#create}
+
+> **create**(`entry`): `Promise`\<`string`\>
+
+Create a new audit entry.
+
+#### Parameters
+
+##### entry
+
+`Omit`\<`IAuthenticationAuditEntry`, `"id"` \| `"dateCreated"`\>
+
+The audit entry to be logged.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The unique identifier of the created audit entry.
+
+#### Implementation of
+
+`IAuthenticationAuditComponent.create`
+
+***
+
+### query() {#query}
+
+> **query**(`options?`, `cursor?`, `limit?`): `Promise`\<\{ `entries`: `IAuthenticationAuditEntry`[]; `cursor?`: `string`; \}\>
+
+Query the audit entries.
+
+#### Parameters
+
+##### options?
+
+The query options.
+
+###### actorId?
+
+`string`
+
+The actor identifier to filter the audit entries, optional.
+
+###### organizationId?
+
+`string`
+
+The organization identifier to filter the audit entries, optional.
+
+###### tenantId?
+
+`string`
+
+The tenant identifier to filter the audit entries, optional.
+
+###### nodeId?
+
+`string`
+
+The node identifier to filter the audit entries, optional.
+
+###### event?
+
+`string`
+
+The audit event to filter the audit entries, optional.
+
+###### startDate?
+
+`string`
+
+The start date to filter the audit entries, optional.
+
+###### endDate?
+
+`string`
+
+The end date to filter the audit entries, optional.
+
+##### cursor?
+
+`string`
+
+The cursor for pagination.
+
+##### limit?
+
+`number`
+
+The maximum number of entries to return.
+
+#### Returns
+
+`Promise`\<\{ `entries`: `IAuthenticationAuditEntry`[]; `cursor?`: `string`; \}\>
+
+The audit entries.
+
+#### Implementation of
+
+`IAuthenticationAuditComponent.query`
+
+***
+
+### getEndpointWithPrefix() {#getendpointwithprefix}
+
+> **getEndpointWithPrefix**(): `string`
+
+Get the endpoint with the prefix for the namespace.
+
+#### Returns
+
+`string`
+
+The endpoint with namespace prefix attached.
+
+#### Inherited from
+
+`BaseRestClient.getEndpointWithPrefix`
+
+***
+
+### fetch() {#fetch}
+
+> **fetch**\<`T`, `U`\>(`route`, `method`, `request?`): `Promise`\<`U`\>
+
+Perform a request in json format.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `IHttpRequest`\<`any`\>
+
+##### U
+
+`U` *extends* `IHttpResponse`\<`any`\>
+
+#### Parameters
+
+##### route
+
+`string`
+
+The route of the request.
+
+##### method
+
+`HttpMethod`
+
+The http method.
+
+##### request?
+
+`T`
+
+Request to send to the endpoint.
+
+#### Returns
+
+`Promise`\<`U`\>
+
+The response.
+
+#### Inherited from
+
+`BaseRestClient.fetch`