@genesislcap/foundation-user 14.137.0

package/dist/foundation-user.d.ts

@@ -0,0 +1,374 @@
+import { InterfaceSymbol } from '@microsoft/fast-foundation';
+import { Listener } from '@genesislcap/foundation-utils';
+import { Logger } from '@genesislcap/foundation-logger';
+import { Observer } from '@genesislcap/foundation-utils';
+
+/**
+ * Default User implementation.
+ * @public
+ */
+export declare class DefaultUser implements User {
+    /** @internal */
+    protected config: UserConfig;
+    /** {@inheritDoc UserPathHistory.pathHistory} */
+    pathHistory: string[];
+    /** {@inheritDoc UserActionHistory.actionHistory} */
+    actionHistory: unknown[];
+    /** {@inheritDoc User.isAuthenticated} */
+    isAuthenticated: boolean;
+    /** {@inheritDoc User.userKVs} */
+    userKVs: {
+        [key: string]: any;
+    };
+    /** {@inheritDoc User.details} */
+    details: SetUserProperties['details'];
+    /** {@inheritDoc User.permission} */
+    permission: string[];
+    /** {@inheritDoc User.profile} */
+    profile: string[];
+    /** {@inheritDoc User.sourceRef} */
+    sourceRef: string;
+    /** {@inheritDoc User.userName} */
+    userName: string;
+    /** {@inheritDoc User.rawProperties} */
+    rawProperties: Partial<SetUserProperties>;
+    /** {@inheritDoc User.set} */
+    set(properties: Partial<SetUserProperties>): User;
+    /** {@inheritDoc User.unset} */
+    unset(): User;
+    /** @internal */
+    protected userNameChanged(): void;
+    /** {@inheritDoc User.username} */
+    get username(): string;
+    /** {@inheritDoc User.isAnonymous} */
+    get isAnonymous(): boolean;
+    /** {@inheritDoc User.isAdmin} */
+    isAdmin(): boolean;
+    /** {@inheritDoc User.isBanned} */
+    isBanned(): boolean;
+    /** {@inheritDoc User.hasPermission} */
+    hasPermission(permission: string | string[]): boolean;
+    /** {@inheritDoc User.hasProfile} */
+    hasProfile(profile: string | string[]): boolean;
+    /** {@inheritDoc UserPathHistory.trackPath} */
+    trackPath(): string;
+    /** {@inheritDoc UserPathHistory.clearPaths} */
+    clearPaths(): void;
+    /** {@inheritDoc UserPathHistory.lastPath} */
+    lastPath(): string;
+    /** {@inheritDoc UserActionHistory.trackAction} */
+    trackAction<TDetails = unknown>(details: TDetails): void;
+    /** {@inheritDoc UserActionHistory.clearActions} */
+    clearActions(): void;
+    /** {@inheritDoc UserActionHistory.lastAction} */
+    lastAction(): unknown;
+    /** {@inheritDoc User.clearTrackingHistory} */
+    clearTrackingHistory(): void;
+    /** @internal */
+    protected hasKey(keys: string[], key: string | string[]): boolean;
+    /** @internal */
+    protected authenticationChangeListeners: Observer<UserAuthenticationChangeEvent>;
+    /** {@inheritDoc User.addAuthenticationChangeListener} */
+    addAuthenticationChangeListener(listener: Listener<UserAuthenticationChangeEvent>): () => void;
+    /** @internal */
+    protected isAuthenticatedChanged(): void;
+}
+
+/**
+ * Default UserConfig DI implementation.
+ * @public
+ */
+export declare const defaultUserConfig: UserConfig;
+
+/**
+ * Gets User from the DI container.
+ *
+ * @remarks
+ * A utility method for host applications that are not using decorators or the DI container.
+ *
+ * @example
+ * ```ts
+ * import { getUser, User } from '@genesislcap/foundation-user';
+ * ...
+ * private user: User = getUser();
+ * ```
+ *
+ * @public
+ */
+export declare function getUser(): User;
+
+/**
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * SetUserProperties is a partial match of `LoginAck` from `@genesislcap/foundation-auth`.
+ *
+ * @public
+ */
+export declare interface SetUserProperties extends Partial<UserQueueProperties> {
+    readonly sourceRef: string;
+    readonly userName: string;
+    readonly userKVs: UserKVsProperty;
+    readonly details: UserDetailsProperty;
+    readonly permission: string[];
+    readonly profile: string[];
+    readonly [key: string]: any;
+}
+
+/**
+ * User interface.
+ *
+ * @remarks
+ * The user singleton, which always exists in either an anonymous or authenticated mode.
+ *
+ * @privateRemarks
+ * Provides `username` and `userName` for backwards compatability.
+ *
+ * @example
+ * ```ts
+ * import { User } from '@genesislcap/foundation-user';
+ * ...
+ * @User private user: User
+ * ```
+ *
+ * @public
+ */
+export declare interface User extends UserPathHistory, UserActionHistory {
+    readonly isAuthenticated: boolean;
+    readonly isAnonymous: boolean;
+    readonly userKVs: {
+        [key: string]: any;
+    };
+    readonly details: SetUserProperties['details'];
+    readonly permission: string[];
+    readonly profile: string[];
+    readonly sourceRef: string;
+    readonly userName: string;
+    readonly username: string;
+    /**
+     * A structuredClone of the raw unmanaged properties used to set the user.
+     *
+     * @remarks
+     * This offers developers an escape hatch to the raw properties. If you feel there's a gap in the User interface based
+     * on your application requirements, please raise a request for such properties to be moved onto the interface.
+     */
+    readonly rawProperties: Partial<SetUserProperties>;
+    /**
+     * @param properties - The UserProperties used to populate the User.
+     */
+    set(properties: Partial<SetUserProperties>): User;
+    unset(): User;
+    isAdmin(): boolean;
+    isBanned(): boolean;
+    /**
+     * @param permission - A permission string or an array of permission strings to check.
+     */
+    hasPermission(permission: string | string[]): boolean;
+    /**
+     * @param profile - A profile string or an array of profile strings to check.
+     */
+    hasProfile(profile: string | string[]): boolean;
+    /**
+     * @example
+     * ```ts
+     * import type { UserAuthenticationChangeEvent } from '@genesislcap/foundation-user';
+     * ...
+     * const unsubscribe = this.user.addAuthenticationChangeListener((event: UserAuthenticationChangeEvent) => {
+     *   console.log('User authenticated?', event.detail);
+     * });
+     * ```
+     *
+     * @param listener - A listener function.
+     */
+    addAuthenticationChangeListener(listener: Listener<UserAuthenticationChangeEvent>): () => void;
+    clearTrackingHistory(): void;
+}
+
+/**
+ * User DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const User: InterfaceSymbol<User>;
+
+/**
+ * UserActionHistory.
+ *
+ * @remarks
+ * APIs to track a user's action history.
+ *
+ * @privateRemarks
+ * Integrate with foundation analytics? Users could then simply call `user.trackAction` and we could engage analytics.
+ * We should move analytics out of comms first.
+ *
+ * @public
+ */
+export declare interface UserActionHistory {
+    /**
+     * Array of actions that have been tracked.
+     */
+    readonly actionHistory: unknown[];
+    /**
+     * Track an action.
+     */
+    trackAction<TDetails = unknown>(details: TDetails): void;
+    /**
+     * Clears action history.
+     */
+    clearActions(): void;
+    /**
+     * @returns The last stored action.
+     */
+    lastAction(): unknown;
+}
+
+/**
+ * UserAuthenticationChangeEvent.
+ *
+ * @remarks
+ * Detail will either be `true` or `false` to indicate authentication status.
+ *
+ * @public
+ */
+export declare type UserAuthenticationChangeEvent = CustomEvent<boolean>;
+
+/**
+ * UserAuthenticationChangeType.
+ * @public
+ */
+export declare const UserAuthenticationChangeType = "user-authentication-change";
+
+/**
+ * UserConfig DI interface.
+ *
+ * @public
+ */
+export declare interface UserConfig {
+    /**
+     * Exclude certain actions from tracking.
+     *
+     * See {@link UserPathHistory}
+     */
+    trackActionExclusions: unknown[];
+    /**
+     * Exclude certain paths from tracking.
+     *
+     * See {@link UserActionHistory}
+     */
+    trackPathExclusions: string[];
+    /**
+     * User property setter.
+     *
+     * @remarks
+     * The user is typically set from the result of a LoginAck.
+     */
+    setUser(user: WriteableUser, properties: Partial<SetUserProperties>): User;
+    /**
+     * User property un-setter.
+     */
+    unsetUser(user: WriteableUser): User;
+}
+
+/**
+ * UserConfig DI key.
+ *
+ * @internal
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ */
+export declare const UserConfig: InterfaceSymbol<UserConfig>;
+
+/**
+ * @public
+ */
+export declare interface UserDetailsProductProperty {
+    readonly name: string;
+    readonly version: string;
+    readonly [key: string]: any;
+}
+
+/**
+ * @public
+ */
+export declare interface UserDetailsProperty {
+    readonly system: UserDetailsSystemProperty;
+    readonly product: UserDetailsProductProperty[];
+    readonly heartbeatIntervalSecs: number;
+    readonly failedLoginAttempts: number;
+    readonly rejectedLoginAttempts: number;
+    readonly lastLoginDatetime: number;
+    readonly daysToPasswordExpiry: number;
+    readonly [key: string]: any;
+}
+
+/**
+ * @public
+ */
+export declare interface UserDetailsSystemProperty {
+    readonly date: string;
+    readonly [key: string]: any;
+}
+
+/**
+ * @public
+ */
+export declare interface UserKVsProperty {
+    readonly [key: string]: any;
+}
+
+/**
+ * UserPathHistory.
+ *
+ * @remarks
+ * APIs to track a user's path history. Includes the pathname, search and hash only.
+ * This is not intended proxy or replace the History API.
+ *
+ * @privateRemarks
+ * Integrate with foundation analytics? Users could then simply call `user.trackPath` and we could engage analytics.
+ * We should move analytics out of comms first.
+ *
+ * @public
+ */
+export declare interface UserPathHistory {
+    /**
+     * Array of paths that have been tracked.
+     */
+    readonly pathHistory: string[];
+    /**
+     * Track current path.
+     */
+    trackPath(): string;
+    /**
+     * Clears path history.
+     */
+    clearPaths(): void;
+    /**
+     * May be used to return to a target path after authentication.
+     * @returns The last stored path.
+     */
+    lastPath(): string | undefined;
+}
+
+/**
+ * @public
+ */
+export declare interface UserQueueProperties {
+    readonly updateQueue: string;
+    readonly zeroMqProxyModeEnabled: boolean;
+    readonly zeroMqProxyInboundPort: number;
+    readonly zeroMqProxyOutboundPort: number;
+}
+
+/**
+ * @internal
+ */
+declare type WriteableUser = {
+    -readonly [P in keyof User]: User[P];
+};
+
+export { }

package/docs/.gitattributes

@@ -0,0 +1,2 @@
+*.md -diff
+*.md linguist-generated

package/docs/api/foundation-user.defaultuser.actionhistory.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [actionHistory](./foundation-user.defaultuser.actionhistory.md)
+
+## DefaultUser.actionHistory property
+
+Array of actions that have been tracked.
+
+**Signature:**
+
+```typescript
+actionHistory: unknown[];
+```

package/docs/api/foundation-user.defaultuser.addauthenticationchangelistener.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [addAuthenticationChangeListener](./foundation-user.defaultuser.addauthenticationchangelistener.md)
+
+## DefaultUser.addAuthenticationChangeListener() method
+
+**Signature:**
+
+```typescript
+addAuthenticationChangeListener(listener: Listener<UserAuthenticationChangeEvent>): () => void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  listener | Listener&lt;[UserAuthenticationChangeEvent](./foundation-user.userauthenticationchangeevent.md)<!-- -->&gt; | A listener function. |
+
+**Returns:**
+
+() =&gt; void
+

package/docs/api/foundation-user.defaultuser.clearactions.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [clearActions](./foundation-user.defaultuser.clearactions.md)
+
+## DefaultUser.clearActions() method
+
+Clears action history.
+
+**Signature:**
+
+```typescript
+clearActions(): void;
+```
+**Returns:**
+
+void
+

package/docs/api/foundation-user.defaultuser.clearpaths.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [clearPaths](./foundation-user.defaultuser.clearpaths.md)
+
+## DefaultUser.clearPaths() method
+
+Clears path history.
+
+**Signature:**
+
+```typescript
+clearPaths(): void;
+```
+**Returns:**
+
+void
+

package/docs/api/foundation-user.defaultuser.cleartrackinghistory.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [clearTrackingHistory](./foundation-user.defaultuser.cleartrackinghistory.md)
+
+## DefaultUser.clearTrackingHistory() method
+
+
+**Signature:**
+
+```typescript
+clearTrackingHistory(): void;
+```
+**Returns:**
+
+void
+

package/docs/api/foundation-user.defaultuser.details.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [details](./foundation-user.defaultuser.details.md)
+
+## DefaultUser.details property
+
+
+**Signature:**
+
+```typescript
+details: SetUserProperties['details'];
+```

package/docs/api/foundation-user.defaultuser.haspermission.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [hasPermission](./foundation-user.defaultuser.haspermission.md)
+
+## DefaultUser.hasPermission() method
+
+**Signature:**
+
+```typescript
+hasPermission(permission: string | string[]): boolean;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  permission | string \| string\[\] | A permission string or an array of permission strings to check. |
+
+**Returns:**
+
+boolean
+

package/docs/api/foundation-user.defaultuser.hasprofile.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [hasProfile](./foundation-user.defaultuser.hasprofile.md)
+
+## DefaultUser.hasProfile() method
+
+**Signature:**
+
+```typescript
+hasProfile(profile: string | string[]): boolean;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  profile | string \| string\[\] | A profile string or an array of profile strings to check. |
+
+**Returns:**
+
+boolean
+

package/docs/api/foundation-user.defaultuser.isadmin.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [isAdmin](./foundation-user.defaultuser.isadmin.md)
+
+## DefaultUser.isAdmin() method
+
+
+**Signature:**
+
+```typescript
+isAdmin(): boolean;
+```
+**Returns:**
+
+boolean
+

package/docs/api/foundation-user.defaultuser.isanonymous.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [isAnonymous](./foundation-user.defaultuser.isanonymous.md)
+
+## DefaultUser.isAnonymous property
+
+
+**Signature:**
+
+```typescript
+get isAnonymous(): boolean;
+```

package/docs/api/foundation-user.defaultuser.isauthenticated.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [isAuthenticated](./foundation-user.defaultuser.isauthenticated.md)
+
+## DefaultUser.isAuthenticated property
+
+
+**Signature:**
+
+```typescript
+isAuthenticated: boolean;
+```

package/docs/api/foundation-user.defaultuser.isbanned.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [isBanned](./foundation-user.defaultuser.isbanned.md)
+
+## DefaultUser.isBanned() method
+
+
+**Signature:**
+
+```typescript
+isBanned(): boolean;
+```
+**Returns:**
+
+boolean
+

package/docs/api/foundation-user.defaultuser.lastaction.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [lastAction](./foundation-user.defaultuser.lastaction.md)
+
+## DefaultUser.lastAction() method
+
+**Signature:**
+
+```typescript
+lastAction(): unknown;
+```
+**Returns:**
+
+unknown
+
+The last stored action.
+

package/docs/api/foundation-user.defaultuser.lastpath.md

@@ -0,0 +1,19 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md) &gt; [lastPath](./foundation-user.defaultuser.lastpath.md)
+
+## DefaultUser.lastPath() method
+
+May be used to return to a target path after authentication.
+
+**Signature:**
+
+```typescript
+lastPath(): string;
+```
+**Returns:**
+
+string
+
+The last stored path.
+

package/docs/api/foundation-user.defaultuser.md

@@ -0,0 +1,51 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-user](./foundation-user.md) &gt; [DefaultUser](./foundation-user.defaultuser.md)
+
+## DefaultUser class
+
+Default User implementation.
+
+**Signature:**
+
+```typescript
+export declare class DefaultUser implements User 
+```
+**Implements:** [User](./foundation-user.user.md)
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [actionHistory](./foundation-user.defaultuser.actionhistory.md) |  | unknown\[\] | Array of actions that have been tracked. |
+|  [details](./foundation-user.defaultuser.details.md) |  | [SetUserProperties](./foundation-user.setuserproperties.md)<!-- -->\['details'\] |  |
+|  [isAnonymous](./foundation-user.defaultuser.isanonymous.md) | <code>readonly</code> | boolean |  |
+|  [isAuthenticated](./foundation-user.defaultuser.isauthenticated.md) |  | boolean |  |
+|  [pathHistory](./foundation-user.defaultuser.pathhistory.md) |  | string\[\] | Array of paths that have been tracked. |
+|  [permission](./foundation-user.defaultuser.permission.md) |  | string\[\] |  |
+|  [profile](./foundation-user.defaultuser.profile.md) |  | string\[\] |  |
+|  [rawProperties](./foundation-user.defaultuser.rawproperties.md) |  | Partial&lt;[SetUserProperties](./foundation-user.setuserproperties.md)<!-- -->&gt; | A structuredClone of the raw unmanaged properties used to set the user. |
+|  [sourceRef](./foundation-user.defaultuser.sourceref.md) |  | string |  |
+|  [userKVs](./foundation-user.defaultuser.userkvs.md) |  | { \[key: string\]: any; } |  |
+|  [username](./foundation-user.defaultuser.username.md) | <code>readonly</code> | string |  |
+|  [userName](./foundation-user.defaultuser.username.md) |  | string |  |
+
+## Methods
+
+|  Method | Modifiers | Description |
+|  --- | --- | --- |
+|  [addAuthenticationChangeListener(listener)](./foundation-user.defaultuser.addauthenticationchangelistener.md) |  |  |
+|  [clearActions()](./foundation-user.defaultuser.clearactions.md) |  | Clears action history. |
+|  [clearPaths()](./foundation-user.defaultuser.clearpaths.md) |  | Clears path history. |
+|  [clearTrackingHistory()](./foundation-user.defaultuser.cleartrackinghistory.md) |  |  |
+|  [hasPermission(permission)](./foundation-user.defaultuser.haspermission.md) |  |  |
+|  [hasProfile(profile)](./foundation-user.defaultuser.hasprofile.md) |  |  |
+|  [isAdmin()](./foundation-user.defaultuser.isadmin.md) |  |  |
+|  [isBanned()](./foundation-user.defaultuser.isbanned.md) |  |  |
+|  [lastAction()](./foundation-user.defaultuser.lastaction.md) |  |  |
+|  [lastPath()](./foundation-user.defaultuser.lastpath.md) |  | May be used to return to a target path after authentication. |
+|  [set(properties)](./foundation-user.defaultuser.set.md) |  |  |
+|  [trackAction(details)](./foundation-user.defaultuser.trackaction.md) |  | Track an action. |
+|  [trackPath()](./foundation-user.defaultuser.trackpath.md) |  | Track current path. |
+|  [unset()](./foundation-user.defaultuser.unset.md) |  |  |
+