@3sixty/api-auth-entity-storage-rest-client 0.0.0-stage → 0.20.0-next.0

package/dist/types/entityStorageAuthenticationAdminRestClient.d.ts

@@ -0,0 +1,62 @@
+import type { IAuthenticationAdminComponent, IAuthenticationUser } from "@3sixty/api-auth-entity-storage-models";
+import { BaseRestClient } from "@3sixty/api-core";
+import type { IBaseRestClientConfig } from "@3sixty/api-models";
+/**
+ * The client to connect to the authentication admin service.
+ */
+export declare class EntityStorageAuthenticationAdminRestClient extends BaseRestClient implements IAuthenticationAdminComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthenticationAdminRestClient.
+     * @param config The configuration for the client.
+     */
+    constructor(config: IBaseRestClientConfig);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a login for the user.
+     * @param user The user to create.
+     * @returns Nothing.
+     */
+    create(user: IAuthenticationUser & {
+        password: string;
+    }): Promise<void>;
+    /**
+     * Update a login for the user.
+     * @param user The user to update.
+     * @returns Nothing.
+     */
+    update(user: Partial<IAuthenticationUser>): Promise<void>;
+    /**
+     * Get a user by email.
+     * @param email The email address of the user to get.
+     * @returns The user details.
+     */
+    get(email: string): Promise<IAuthenticationUser>;
+    /**
+     * Get a user by identity.
+     * @param identity The identity of the user to get.
+     * @returns The user details.
+     */
+    getByIdentity(identity: string): Promise<IAuthenticationUser>;
+    /**
+     * Remove a user.
+     * @param email The email address of the user to remove.
+     * @returns Nothing.
+     */
+    remove(email: string): Promise<void>;
+    /**
+     * Update the user's password.
+     * @param email The email address of the user to update.
+     * @param newPassword The new password for the user.
+     * @param currentPassword The current password, optional, if supplied will check against existing.
+     * @returns Nothing.
+     */
+    updatePassword(email: string, newPassword: string, currentPassword?: string): Promise<void>;
+}

package/dist/types/entityStorageAuthenticationAuditRestClient.d.ts

@@ -0,0 +1,73 @@
+import type { AuthAuditEvent, IAuthenticationAuditComponent, IAuthenticationAuditEntry } from "@3sixty/api-auth-entity-storage-models";
+import { BaseRestClient } from "@3sixty/api-core";
+import type { IBaseRestClientConfig } from "@3sixty/api-models";
+/**
+ * The client to connect to the authentication audit service.
+ */
+export declare class EntityStorageAuthenticationAuditRestClient extends BaseRestClient implements IAuthenticationAuditComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthenticationAuditRestClient.
+     * @param config The configuration for the client.
+     */
+    constructor(config: IBaseRestClientConfig);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a new audit entry.
+     * @param entry The audit entry to be logged.
+     * @returns The unique identifier of the created audit entry.
+     */
+    create(entry: Omit<IAuthenticationAuditEntry, "id" | "dateCreated">): Promise<string>;
+    /**
+     * Get an audit entry by id.
+     * @param id The unique identifier of the audit entry.
+     * @returns The audit entry.
+     */
+    get(id: string): Promise<IAuthenticationAuditEntry>;
+    /**
+     * Update an audit entry.
+     * @param id The unique identifier of the audit entry to update.
+     * @param entry The fields to update on the audit entry.
+     * @returns A promise that resolves when the audit entry has been updated.
+     */
+    update(id: string, entry: Partial<Omit<IAuthenticationAuditEntry, "id" | "dateCreated">>): Promise<void>;
+    /**
+     * Remove an audit entry.
+     * @param id The unique identifier of the audit entry to remove.
+     * @returns A promise that resolves when the audit entry has been removed.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Query the audit entries.
+     * @param options The query options.
+     * @param options.actorId The actor identifier to filter the audit entries, optional.
+     * @param options.organizationId The organization identifier to filter the audit entries, optional.
+     * @param options.tenantId The tenant identifier to filter the audit entries, optional.
+     * @param options.nodeId The node identifier to filter the audit entries, optional.
+     * @param options.event The audit event to filter the audit entries, optional.
+     * @param options.startDate The start date to filter the audit entries, optional.
+     * @param options.endDate The end date to filter the audit entries, optional.
+     * @param cursor The cursor for pagination.
+     * @param limit The maximum number of entries to return.
+     * @returns The audit entries.
+     */
+    query(options?: {
+        actorId?: string;
+        organizationId?: string;
+        tenantId?: string;
+        nodeId?: string;
+        event?: AuthAuditEvent | string;
+        startDate?: string;
+        endDate?: string;
+    }, cursor?: string, limit?: number): Promise<{
+        entries: IAuthenticationAuditEntry[];
+        cursor?: string;
+    }>;
+}

package/dist/types/entityStorageAuthenticationRestClient.d.ts

@@ -0,0 +1,54 @@
+import type { IAuthenticationComponent } from "@3sixty/api-auth-entity-storage-models";
+import { BaseRestClient } from "@3sixty/api-core";
+import type { IEntityStorageAuthenticationRestClientConstructorOptions } from "./models/entityStorageAuthenticationRestClientConstructorOptions.js";
+/**
+ * The client to connect to the authentication service.
+ */
+export declare class EntityStorageAuthenticationRestClient extends BaseRestClient implements IAuthenticationComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of EntityStorageAuthenticationRestClient.
+     * @param config The configuration for the client.
+     */
+    constructor(config: IEntityStorageAuthenticationRestClientConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Perform a login for the user.
+     * @param email The email address for the user.
+     * @param password The password for the user.
+     * @returns The authentication token for the user, if it uses a mechanism with public access.
+     */
+    login(email: string, password: string): Promise<{
+        token?: string;
+        expiry: number;
+    }>;
+    /**
+     * Logout the current user.
+     * @param token The token to logout, if it uses a mechanism with public access.
+     * @returns A promise that resolves when the logout request has completed.
+     */
+    logout(token?: string): Promise<void>;
+    /**
+     * Refresh the token.
+     * @param token The token to refresh, if it uses a mechanism with public access.
+     * @returns The refreshed token, if it uses a mechanism with public access.
+     */
+    refresh(token?: string): Promise<{
+        token?: string;
+        expiry: number;
+    }>;
+    /**
+     * Update the user's password.
+     * @param currentPassword The current password for the user.
+     * @param newPassword The new password for the user.
+     * @returns A promise that resolves when the password has been updated on the server.
+     */
+    updatePassword(currentPassword: string, newPassword: string): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./entityStorageAuthenticationAdminRestClient.js";
+export * from "./entityStorageAuthenticationAuditRestClient.js";
+export * from "./entityStorageAuthenticationRestClient.js";
+export * from "./models/entityStorageAuthenticationRestClientConstructorOptions.js";

package/dist/types/models/entityStorageAuthenticationRestClientConstructorOptions.d.ts

@@ -0,0 +1,11 @@
+import type { IBaseRestClientConfig } from "@3sixty/api-models";
+/**
+ * Options for the Entity Storage Authentication REST client constructor.
+ */
+export interface IEntityStorageAuthenticationRestClientConstructorOptions extends IBaseRestClientConfig {
+    /**
+     * The name of the cookie to use for storing the auth token.
+     * @default access_token
+     */
+    cookieName?: string;
+}

package/docs/examples.md

@@ -0,0 +1,111 @@
+# 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 '@3sixty/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 '@3sixty/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 '@3sixty/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 '@3sixty/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,323 @@
+# 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`
+
+***
+
+### getPathPrefix() {#getpathprefix}
+
+> **getPathPrefix**(): `string`
+
+Get the path prefix as a URL path string provided in the constructor.
+
+#### Returns
+
+`string`
+
+The path prefix.
+
+#### Inherited from
+
+`BaseRestClient.getPathPrefix`
+
+***
+
+### fetch() {#fetch}
+
+> **fetch**\<`T`, `U`\>(`route`, `method`, `request?`, `options?`): `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.
+
+##### options?
+
+Optional override options for the request.
+
+###### overridePrefix?
+
+`string`
+
+Optional override prefix to use for this request instead of the default prefix.
+
+#### Returns
+
+`Promise`\<`U`\>
+
+The response.
+
+#### Inherited from
+
+`BaseRestClient.fetch`