@genesislcap/foundation-filters 9.0.1-alpha-b5c5eb7.0

package/dist/foundation-filters.d.ts

@@ -0,0 +1,707 @@
+import { Auth } from '@genesislcap/foundation-comms';
+import { Container } from '@microsoft/fast-foundation';
+import { InterfaceSymbol } from '@microsoft/fast-foundation';
+import { Logger } from '@genesislcap/foundation-utils';
+import { User } from '@genesislcap/foundation-comms';
+
+/**
+ * ClientFilter interface.
+ *
+ * @remarks
+ * Simplifies access to runtime data / state contained within the DI container.
+ *
+ * @typeParam P - The filter parameter type.
+ *
+ * @public
+ */
+export declare interface ClientFilter<P = any> {
+    /**
+     * @param parameters - The filter parameters.
+     *
+     * @returns The filter outcome.
+     *
+     * @privateRemarks
+     * Not sure if there's a need for an async api here.
+     */
+    filter(parameters: P): boolean;
+}
+
+/**
+ * @public
+ */
+export declare const ClientFilterName: {
+    readonly nodeEnv: "nodeEnv";
+    readonly percentage: "percentage";
+    readonly timeWindow: "timeWindow";
+    readonly urlTargeting: "urlTargeting";
+    readonly userAgent: "userAgent";
+    readonly userTargeting: "userTargeting";
+};
+
+/**
+ * @public
+ */
+export declare type ClientFilterName = (typeof ClientFilterName)[keyof typeof ClientFilterName];
+
+/**
+ * ClientFilterRunner DI interface.
+ *
+ * @public
+ */
+export declare interface ClientFilterRunner {
+    run(filters: ClientFilterSchemas[], container?: Container): boolean;
+}
+
+/**
+ * ClientFilterRunner DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const ClientFilterRunner: InterfaceSymbol<ClientFilterRunner>;
+
+/**
+ * ClientFilterSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @typeParam N - The filter name type.
+ * @typeParam P - The filter parameters type.
+ *
+ * @public
+ */
+export declare type ClientFilterSchema<N extends ClientFilterName, P> = {
+    readonly name: N;
+    readonly parameters: P;
+};
+
+/**
+ * ClientFilterSchemas type.
+ *
+ * @public
+ */
+export declare type ClientFilterSchemas = NodeEnvSchema | PercentageSchema | TimeWindowSchema | URLTargetingSchema | UserAgentSchema | UserTargetingSchema;
+
+/**
+ * Default ClientFilterRunner DI implementation.
+ * @public
+ */
+export declare class DefaultClientFilterRunner implements ClientFilterRunner {
+    container: Container;
+    run(filters: ClientFilterSchemas[], container?: Container): boolean;
+}
+
+/**
+ * Default NodeEnv DI implementation.
+ * @public
+ */
+export declare class DefaultNodeEnv implements NodeEnv {
+    /** {@inheritDoc ClientFilter.filter} */
+    filter(params: NodeEnvParams): boolean;
+    /** {@inheritDoc NodeEnv.isDevelopment} */
+    get isDevelopment(): boolean;
+    /** {@inheritDoc NodeEnv.isTesting} */
+    get isTesting(): boolean;
+    /** {@inheritDoc NodeEnv.isProduction} */
+    get isProduction(): boolean;
+}
+
+/**
+ * Default Percentage DI implementation.
+ * @public
+ */
+export declare class DefaultPercentage implements Percentage {
+    /** {@inheritDoc ClientFilter.filter} */
+    filter(params: PercentageParams): boolean;
+}
+
+/**
+ * Default TimeWindow DI implementation.
+ * @public
+ */
+export declare class DefaultTimeWindow implements TimeWindow {
+    /** {@inheritDoc ClientFilter.filter} */
+    filter(params: TimeWindowParams): boolean;
+}
+
+/**
+ * Default URLTargeting DI implementation.
+ * @public
+ */
+export declare class DefaultURLTargeting implements URLTargeting {
+    /** {@inheritDoc ClientFilter.filter} */
+    filter(params: URLTargetingParams): boolean;
+    /** {@inheritDoc URLTargeting.isSecure} */
+    isSecure(url: any): boolean;
+}
+
+/**
+ * Default UserAgent DI implementation.
+ * @public
+ */
+export declare class DefaultUserAgent implements UserAgent {
+    /** {@inheritDoc ClientFilter.filter} */
+    filter(params: UserAgentParams): boolean;
+    /** {@inheritDoc UserAgent.isSafari} */
+    get isSafari(): boolean;
+}
+
+/**
+ * Default UserTargeting DI implementation.
+ * @public
+ */
+export declare class DefaultUserTargeting implements UserTargeting {
+    auth: Auth;
+    constructor(auth: Auth);
+    /** {@inheritDoc ClientFilter.filter} */
+    filter(params: UserTargetingParams): boolean;
+    /** {@inheritDoc UserTargeting.hasAdminProfile} */
+    get hasAdminProfile(): boolean;
+    /** {@inheritDoc UserTargeting.isLoggedIn} */
+    get isLoggedIn(): boolean;
+}
+
+/**
+ * Filer lookup by name.
+ *
+ * @public
+ */
+export declare function getFilterByName(name: ClientFilterName, container: Container): NodeEnv | Percentage | TimeWindow | URLTargeting | UserAgent | UserTargeting;
+
+/**
+ * Client filter logger
+ *
+ * @remarks
+ * Exposed so that the logging level within this package can be tailored differently to the default level when needed.
+ *
+ * @example
+ * ```ts
+ * import { LogLevel } from '@genesislcap/foundation-utils';
+ * import { logger as clientFilterLogger } from '@genesislcap/foundation-filters';
+ * clientFilterLogger.level = LogLevel.Error;
+ * ```
+ *
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * NodeEnv client filter DI interface.
+ * @public
+ */
+export declare interface NodeEnv extends ClientFilter<NodeEnvParams> {
+    /**
+     * @remarks
+     * Running in development mode.
+     */
+    readonly isDevelopment: boolean;
+    /**
+     * @remarks
+     * Running in test mode.
+     */
+    readonly isTesting: boolean;
+    /**
+     * @remarks
+     * Running in production mode.
+     */
+    readonly isProduction: boolean;
+}
+
+/**
+ * NodeEnv DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const NodeEnv: InterfaceSymbol<NodeEnv>;
+
+/**
+ * NodeEnv client filter function.
+ * @remarks
+ * This will return true when the current node env matches target parameters.
+ * @param envs - Environments to target.
+ * @public
+ */
+export declare function nodeEnvFilter(envs: string[]): boolean;
+
+/**
+ * NodeEnvParams
+ *
+ * @example
+ * ```json
+ * {
+ *    "envs": ["development", "testing"],
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type NodeEnvParams = {
+    /**
+     * Envs to target.
+     */
+    readonly envs: string[];
+};
+
+/**
+ * NodeEnvSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @public
+ */
+export declare type NodeEnvSchema = ClientFilterSchema<typeof ClientFilterName.nodeEnv, NodeEnvParams>;
+
+/**
+ * Percentage client filter DI interface.
+ *
+ * @remarks
+ * Simplifies access to runtime data / state contained within the DI container.
+ *
+ * @public
+ * @privateRemarks
+ * Created for consistency with other filters that required DI container access.
+ */
+export declare interface Percentage extends ClientFilter<PercentageParams> {
+}
+
+/**
+ * Percentage DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const Percentage: InterfaceSymbol<Percentage>;
+
+/**
+ * Percentage client filter function.
+ * @remarks
+ * This will return true a certain percentage of the time.
+ * @param percent - The percent of the time to pass, a numeric value between 0 and 1.
+ * @param random - Math.random() generated floating-point.
+ * @public
+ */
+export declare function percentageFilter(percent: number, random?: number): boolean;
+
+/**
+ * PercentageParams
+ *
+ * @remarks
+ * Percent should be a numeric value between 0 and 1.
+ *
+ * @example
+ * ```json
+ * {
+ *    "percent": 0.5
+ * }
+ * ```
+ *
+ * @example
+ * In a rare case where you need to control the random floating-point creation, you can do so externally and provide it.
+ * ```json
+ * {
+ *    "percent": 0.34
+ *    "random": 0.08901819974272063
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type PercentageParams = {
+    readonly percent: number;
+    /**
+     * @remarks
+     * Provided for fine-grain control over the random floating-point
+     */
+    readonly random?: number;
+};
+
+/**
+ * PercentageSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @public
+ */
+export declare type PercentageSchema = ClientFilterSchema<typeof ClientFilterName.percentage, PercentageParams>;
+
+/**
+ * Client filter runner function.
+ * @remarks
+ * This will return true when all the filters in the array pass.
+ * @param filters - An array of client filters to run.
+ * @param container - The DI container.
+ * @public
+ * @privateRemarks
+ * As a runner working off static input, we can't know or source the runtime dependencies of each filter. As such we use
+ * the DI version of each which have those encapsulated.
+ */
+export declare function runner(filters: ClientFilterSchemas[], container: Container): boolean;
+
+/**
+ * TimeWindow client filter DI interface.
+ *
+ * @remarks
+ * Simplifies access to runtime data / state contained within the DI container.
+ *
+ * @public
+ */
+export declare interface TimeWindow extends ClientFilter<TimeWindowParams> {
+}
+
+/**
+ * TimeWindow DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const TimeWindow: InterfaceSymbol<TimeWindow>;
+
+/**
+ * TimeWindow client filter function.
+ * @remarks
+ * This will return true between a certain time window. Start and end can be provided in any format recognized by the
+ * Date.parse() method.
+ *
+ * @param start - The start of the time window.
+ * @param end - The end of the time window.
+ * @public
+ */
+export declare function timeWindowFilter(start?: string, end?: string): boolean;
+
+/**
+ * TimeWindowParams
+ *
+ * @remarks
+ * Both params can be provided in any format recognized by the Date.parse() method.
+ *
+ * @example
+ * ```json
+ * {
+ *   "start": "Sun Sep 25 2022 16:51:55 GMT+0000",
+ *   "end": "Fri Nov 25 2022 17:51:55 GMT+0000"
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * {
+ *   "start": "2022-10-01",
+ *   "end": "2022-12-01"
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * {
+ *   "end": "Dec 31, 2022"
+ * }
+ * ```
+ *
+ * @example
+ * ```json
+ * {
+ *   "start": "2023-01-01T00:00:00.000+00:00"
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type TimeWindowParams = {
+    readonly start?: string;
+    readonly end?: string;
+};
+
+/**
+ * TimeWindowSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @public
+ */
+export declare type TimeWindowSchema = ClientFilterSchema<typeof ClientFilterName.timeWindow, TimeWindowParams>;
+
+/**
+ * URLTargeting client filter DI interface.
+ *
+ * @public
+ */
+export declare interface URLTargeting extends ClientFilter<URLTargetingParams> {
+    /**
+     * @remarks
+     * Check if a url is secure.
+     *
+     * @param url - A url.
+     */
+    isSecure(url: string): boolean;
+}
+
+/**
+ * URLTargeting DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const URLTargeting: InterfaceSymbol<URLTargeting>;
+
+/**
+ * URLTargeting client filter function.
+ * @remarks
+ * This will return true when the current URL matches on ANY of the parameters. If you wish to match on multiple
+ * parameters, consider chaining an array of urlTargeting filters together.
+ * @param url - A url.
+ * @param pattern - A regex.
+ * @param schemes - Schemes/protocols to target.
+ * @param hosts - Hosts to target.
+ * @param paths - Paths to target.
+ * @public
+ * @privateRemarks
+ * The pattern regex can cover everything here, but some devs will likely welcome the explicit arguments.
+ */
+export declare function urlTargetingFilter(url: string, pattern?: RegExp, schemes?: string[], hosts?: string[], paths?: string[]): boolean;
+
+/**
+ * URLTargetingParams
+ *
+ * @example
+ * ```json
+ * {
+ *    "schemes": ["https"],
+ *    "hosts": ["neptx.genesislab.global", "neptune-uat2-axes-server2"]
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type URLTargetingParams = {
+    /**
+     * A url.
+     */
+    readonly url?: string;
+    /**
+     * A regex.
+     */
+    readonly pattern?: RegExp;
+    /**
+     * Schemes/protocols to target.
+     */
+    readonly schemes?: string[];
+    /**
+     * Hosts to target.
+     */
+    readonly hosts?: string[];
+    /**
+     * Paths to target.
+     */
+    readonly paths?: string[];
+};
+
+/**
+ * URLTargetingSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @public
+ */
+export declare type URLTargetingSchema = ClientFilterSchema<typeof ClientFilterName.urlTargeting, URLTargetingParams>;
+
+/**
+ * UserAgent client filter DI interface.
+ *
+ * @remarks
+ * Simplifies access to runtime data / state contained within the DI container.
+ *
+ * @public
+ * @privateRemarks
+ * Created for consistency with other filters that required DI container access.
+ */
+export declare interface UserAgent extends ClientFilter<UserAgentParams> {
+    /**
+     * @remarks
+     * Is the user-agent safari.
+     *
+     * @privateRemarks
+     * Added as an example, see comment in implementation.
+     */
+    readonly isSafari: boolean;
+}
+
+/**
+ * UserAgent DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const UserAgent: InterfaceSymbol<UserAgent>;
+
+/**
+ * UserAgent client filter function.
+ *
+ * @remarks
+ * See {@link https://github.com/faisalman/ua-parser-js} for more information.
+ *
+ * @param browsers - Browser names to target.
+ * @param devices - Device types to target.
+ * @param oss - Operating system names to target.
+ * @param ua - User-agent string (required in nodejs environment).
+ * @public
+ */
+export declare function userAgentFilter(browsers?: string[], devices?: string[], oss?: string[], ua?: string): boolean;
+
+/**
+ * UserAgentParams
+ *
+ * @example
+ * ```json
+ * {
+ *    "browsers": ["Safari", "Firefox", "Chrome", "Chromium"],
+ *    "devices": ["mobile", "tablet"],
+ *    "oss": ["Mac OS", "Linux"]
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type UserAgentParams = {
+    /**
+     * Browser names to target.
+     */
+    readonly browsers?: string[];
+    /**
+     * Device types to target.
+     */
+    readonly devices?: string[];
+    /**
+     * Operating system names to target.
+     */
+    readonly oss?: string[];
+    /**
+     * @remarks
+     * Provided for fine-grain control over the user-agent string in browser, and nodejs usage.
+     */
+    readonly ua?: string;
+};
+
+/**
+ * UserAgentSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @public
+ */
+export declare type UserAgentSchema = ClientFilterSchema<typeof ClientFilterName.userAgent, UserAgentParams>;
+
+/**
+ * UserTargeting client filter DI interface.
+ *
+ * @remarks
+ * Simplifies access to runtime data / state contained within the DI container.
+ *
+ * @public
+ */
+export declare interface UserTargeting extends ClientFilter<UserTargetingParams> {
+    /**
+     * @remarks
+     * Has the user got the 'ADMIN' profile assigned.
+     *
+     * @privateRemarks
+     * Added as an example, see comment in implementation.
+     */
+    readonly hasAdminProfile: boolean;
+    /**
+     * @remarks
+     * Has the user logged in, regardless of their identity.
+     */
+    readonly isLoggedIn: boolean;
+}
+
+/**
+ * UserTargeting DI key.
+ *
+ * @privateRemarks
+ * Marked as internal to stop api-extractor becoming confused cross-linking tokens with the same name.
+ *
+ * @internal
+ */
+export declare const UserTargeting: InterfaceSymbol<UserTargeting>;
+
+/**
+ * UserTargeting client filter function.
+ * @remarks
+ * This will return true when the current user matches on ANY of the parameters. If you wish to match on multiple
+ * parameters, consider chaining an array of userTargeting filters together.
+ * @param user - A user object.
+ * @param usernames - Usernames to target.
+ * @param profiles - Profiles to target.
+ * @param permissions - Permissions to target.
+ * @public
+ * @privateRemarks
+ * We could provide another parameter to indicate a complete match is required?
+ */
+export declare function userTargetingFilter(user: User, usernames?: string[], profiles?: string[], permissions?: string[]): boolean;
+
+/**
+ * UserTargetingParams
+ *
+ * @example
+ * ```json
+ * {
+ *    "usernames": ["JohnDoe"],
+ *    "profiles": ["ADMIN", "READ_WRITE_DEALER"],
+ *    "permissions": ["ExportClientDashboard"]
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type UserTargetingParams = {
+    /**
+     * Usernames to target.
+     */
+    readonly usernames?: string[];
+    /**
+     * Profiles to target.
+     *
+     * @remarks
+     * Profiles are assigned to users, and users may have multiple profiles assigned to them.
+     */
+    readonly profiles?: string[];
+    /**
+     * Permissions to target.
+     *
+     * @remarks
+     * Permissions are assigned to profiles, NEVER to users directly.
+     * The user permissions array will contain everything from the assigned profiles for fine-grained control.
+     */
+    readonly permissions?: string[];
+};
+
+/**
+ * UserTargetingSchema type.
+ *
+ * @remarks
+ * JSON schema type.
+ *
+ * @public
+ */
+export declare type UserTargetingSchema = ClientFilterSchema<typeof ClientFilterName.userTargeting, UserTargetingParams>;
+
+export { }