@simplr-ai/angular 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+import { InjectionToken, OnDestroy, EventEmitter, OnInit, ModuleWithProviders, EnvironmentProviders, ErrorHandler } from '@angular/core';
+import { SimplrFraudConfig, SimplrFlagsConfig, SimplrProfilesConfig, SimplrRUMConfig, AIDelegationConfig, SimplrFraud, DeviceSignals, BehaviorSignals, CollectedSignals, SimplrRUM, RUMActionType, RUMActionTarget, RUMErrorData, RUMLogLevel, SimplrFlags, FlagDefinition, EvalContext, SimplrProfiles, IdentifyOptions, ProfileIdentifyResult, ProfileOrderInput, ProfileOrderFraudResult, ProfileRiskResult, SimplrAI, CreateDelegationOptions, DelegationResult, ValidationResult, DelegationInfo, DelegationStats } from '@simplr-ai/js';
+export { AIDelegationConfig, BehaviorSignals, BindingMode, CollectedSignals, CreateDelegationOptions, DelegationInfo, DelegationResult, DelegationStats, DeviceSignals, EvalContext, FlagDefinition, FlagRule, IdentifyOptions, KeystrokeMetrics, MouseMetrics, ProfileIdentifyResult, ProfileOrderFraudResult, ProfileOrderInput, ProfileRiskResult, RUMActionTarget, RUMActionType, RUMErrorData, RUMEvent, RUMEventType, RUMLogLevel, SimplrAI, SimplrFlags, SimplrFlagsConfig, SimplrFraud, SimplrFraudConfig, SimplrProfiles, SimplrProfilesConfig, SimplrRUM, SimplrRUMConfig, TouchMetrics, ValidationResult, clearDeviceId, createSimplrAI, createSimplrProfiles, getDeviceId, murmurHash3, sha256 } from '@simplr-ai/js';
+import { Observable, BehaviorSubject } from 'rxjs';
+
+/**
+ * Unified configuration for the Simplr Angular adapter. A single config object
+ * configures every feature surface: fraud/biometrics, feature flags, profiles,
+ * RUM and AI delegation. All keys are optional except `apiKey` (your public
+ * `pk_*` key) which most features require.
+ */
+interface SimplrConfig {
+    /** Public API key (`pk_live_…` / `pk_test_…`). Safe for the client. */
+    apiKey: string;
+    /** Override the API base URL (default `https://api.simplr.sh`). */
+    baseUrl?: string;
+    /** Options forwarded to the core `SimplrFraud` device/biometrics collector. */
+    fraud?: Omit<SimplrFraudConfig, "apiKey">;
+    /** Options forwarded to the core `SimplrFlags` feature-flag engine. */
+    flags?: Partial<Omit<SimplrFlagsConfig, "apiKey">>;
+    /**
+     * Options forwarded to the core `SimplrProfiles` SDK.
+     * Falls back to the top-level `apiKey`/`baseUrl`.
+     */
+    profiles?: Partial<Omit<SimplrProfilesConfig, "apiKey">>;
+    /**
+     * Options forwarded to the core `SimplrRUM` SDK. `applicationId` is required
+     * by the core when RUM is initialized.
+     */
+    rum?: Partial<SimplrRUMConfig>;
+    /** Options forwarded to the core `SimplrAI` delegation client. */
+    ai?: Partial<Omit<AIDelegationConfig, "apiKey">>;
+}
+/**
+ * DI token holding the resolved {@link SimplrConfig}. Provided by
+ * `provideSimplr()` or `SimplrModule.forRoot()`.
+ */
+declare const SIMPLR_CONFIG: InjectionToken<SimplrConfig>;
+
+/**
+ * Wraps the core `SimplrFraud` instance: device fingerprinting + behavioral
+ * biometrics + signal collection used for `/v1/check` fraud/identity checks.
+ *
+ * The constructor accepts the resolved {@link SimplrConfig} directly so it can be
+ * unit-tested without Angular's DI runtime: `new SimplrService(config)`.
+ */
+declare class SimplrService implements OnDestroy {
+    /** The underlying core SDK instance. Exposed for advanced/escape-hatch use. */
+    readonly core: SimplrFraud;
+    private readonly config?;
+    constructor(config?: SimplrConfig);
+    /** Whether the SDK has been initialized and is ready to collect. */
+    get isReady(): boolean;
+    /** Initialize the SDK and start biometric tracking (no-op if auto-started). */
+    initialize(): void;
+    /** Start behavioral biometric tracking. */
+    startTracking(): void;
+    /** Stop behavioral biometric tracking. */
+    stopTracking(): void;
+    /** Reset all collected behavioral data. */
+    reset(): void;
+    /** Event handlers + `data-simplr-field` attr to wire up an input for keystroke biometrics. */
+    trackInput(fieldName: string): {
+        onKeyDown: (e: KeyboardEvent) => void;
+        onKeyUp: (e: KeyboardEvent) => void;
+        onPaste: () => void;
+        "data-simplr-field": string;
+    };
+    /** Collect the full device fingerprint only (Promise). */
+    getDeviceSignals(): Promise<DeviceSignals>;
+    /** Collect the full device fingerprint only (Observable). */
+    getDeviceSignals$(): Observable<DeviceSignals>;
+    /** Collect behavioral signals synchronously. */
+    getBehaviorSignals(): BehaviorSignals;
+    /** Collect device + behavior signals (Promise). */
+    collect(): Promise<CollectedSignals>;
+    /** Collect device + behavior signals (Observable). */
+    collect$(): Observable<CollectedSignals>;
+    /**
+     * Convenience: run a fraud/identity check against `/v1/check`. Collects fresh
+     * device + behavior signals and posts them with the configured public key.
+     * Returns the unwrapped `content` from the response envelope.
+     */
+    check(input?: Record<string, unknown>): Promise<unknown>;
+    /** Observable variant of {@link check}. */
+    check$(input?: Record<string, unknown>): Observable<unknown>;
+    ngOnDestroy(): void;
+}
+
+/**
+ * `[simplrProtect]` — attach Simplr device + behavioral signals to a form on
+ * submit. On the form's `submit` event it collects fresh signals and emits them
+ * via `(simplrSignals)`. By default it prevents the native submit so callers
+ * can finish their request with the signals attached; set
+ * `[simplrPreventDefault]="false"` to opt out.
+ *
+ * ```html
+ * <form simplrProtect (simplrSignals)="onSignals($event)"> … </form>
+ * ```
+ */
+declare class SimplrProtectDirective {
+    private readonly simplr;
+    /** Prevent the native form submit while signals are collected (default true). */
+    simplrPreventDefault: boolean;
+    /** Emits the collected device + behavior signals on submit. */
+    simplrSignals: EventEmitter<CollectedSignals>;
+    /** Emits if signal collection fails. */
+    simplrError: EventEmitter<unknown>;
+    constructor(simplr: SimplrService);
+    onSubmit(event: Event): Promise<void>;
+}
+
+/**
+ * Wraps the core `SimplrRUM` Real User Monitoring SDK. Exposes the full method
+ * surface (setUser/clearUser/attributes/trackView/trackAction/trackError/log/
+ * flush/getSessionId/getViewId) plus an auto-view-tracking helper used by the
+ * `[simplrRumView]` directive.
+ *
+ * Unit-testable without Angular DI: `new SimplrRumService(config)`.
+ */
+declare class SimplrRumService implements OnDestroy {
+    /** The underlying core RUM singleton. */
+    readonly core: SimplrRUM;
+    private readonly config?;
+    constructor(config?: SimplrConfig);
+    /**
+     * Initialize RUM. `applicationId` is required by the core. Pulls apiKey/baseUrl
+     * from the unified config when not supplied in overrides.
+     */
+    initialize(overrides?: Partial<SimplrRUMConfig>): void;
+    /** Whether RUM has been initialized. */
+    isInitialized(): boolean;
+    /** Associate the current session with a user. */
+    setUser(userId: string, attributes?: Record<string, unknown>): void;
+    /** Clear the current session's user. */
+    clearUser(): void;
+    /** Add a global attribute attached to every event. */
+    addAttribute(key: string, value: unknown): void;
+    /** Remove a previously added global attribute. */
+    removeAttribute(key: string): void;
+    /** Track a page/screen view. */
+    trackView(name: string, attributes?: Record<string, unknown>): void;
+    /** Track a user action. */
+    trackAction(name: string, type: RUMActionType, options?: {
+        target?: Partial<RUMActionTarget>;
+        attributes?: Record<string, unknown>;
+    }): void;
+    /** Track an error. */
+    trackError(error: Error | RUMErrorData, context?: Record<string, unknown>): void;
+    /** Emit a structured log message. */
+    log(level: RUMLogLevel, message: string, context?: Record<string, unknown>): void;
+    /** End the current RUM session and flush. */
+    stopSession(): void;
+    /** Force-flush the event batch. */
+    flush(): Promise<void>;
+    /** Current session id (or null). */
+    getSessionId(): string | null;
+    /** Current view id (or null). */
+    getViewId(): string | null;
+    ngOnDestroy(): void;
+}
+
+/**
+ * `[simplrRumView]` — declaratively track a RUM view when the host element
+ * initializes. The view name is the directive's bound value; an optional
+ * attributes object can be supplied.
+ *
+ * ```html
+ * <section [simplrRumView]="'Checkout'" [simplrRumViewAttributes]="{ step: 2 }"></section>
+ * ```
+ */
+declare class SimplrRumViewDirective implements OnInit {
+    private readonly rum;
+    /** The view name to report. */
+    viewName: string;
+    /** Optional attributes attached to the view event. */
+    simplrRumViewAttributes?: Record<string, unknown>;
+    constructor(rum: SimplrRumService);
+    ngOnInit(): void;
+}
+
+/**
+ * `<simplr-protected-form>` — a standalone form wrapper that collects Simplr
+ * device + behavioral signals on submit and emits them via
+ * `(submitWithSignals)`. Project your form fields as content.
+ *
+ * ```html
+ * <simplr-protected-form (submitWithSignals)="submit($event)">
+ *   <input name="email" /> <button type="submit">Pay</button>
+ * </simplr-protected-form>
+ * ```
+ */
+declare class SimplrProtectedFormComponent {
+    private readonly simplr;
+    /** Prevent native submit while signals are collected (default true). */
+    preventDefault: boolean;
+    /** Emits the collected device + behavior signals together with the event. */
+    submitWithSignals: EventEmitter<{
+        signals: CollectedSignals;
+        event: Event;
+    }>;
+    /** Emits if signal collection fails. */
+    collectError: EventEmitter<unknown>;
+    constructor(simplr: SimplrService);
+    onSubmit(event: Event): Promise<void>;
+}
+
+/** Extra options for {@link provideSimplr} / {@link SimplrModule.forRoot}. */
+interface ProvideSimplrOptions {
+    /**
+     * When true, registers {@link SimplrErrorHandler} as Angular's `ErrorHandler`
+     * so uncaught errors are piped into RUM. Default false.
+     */
+    errorHandler?: boolean;
+}
+/**
+ * Standalone provider for the Simplr Angular adapter. Use in `bootstrapApplication`:
+ *
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideSimplr({ apiKey: "pk_live_…" })],
+ * });
+ * ```
+ */
+declare function provideSimplr(config: SimplrConfig, options?: ProvideSimplrOptions): EnvironmentProviders;
+/** Standalone declarables (directives + component) for ergonomic imports. */
+declare const SIMPLR_DIRECTIVES: readonly [typeof SimplrProtectDirective, typeof SimplrRumViewDirective, typeof SimplrProtectedFormComponent];
+/**
+ * NgModule for module-based Angular apps. Import `SimplrModule.forRoot(config)`
+ * once in your root module; the directives/component are re-exported for use in
+ * templates.
+ */
+declare class SimplrModule {
+    static forRoot(config: SimplrConfig, options?: ProvideSimplrOptions): ModuleWithProviders<SimplrModule>;
+}
+
+/**
+ * Wraps the core `SimplrFlags` engine (feature flags with deterministic
+ * per-user rollout + targeting, evaluated locally). Adds an RxJS surface:
+ * `flags$` emits the full flag map whenever flags refresh, and
+ * `observeFlag(key, ctx?)` emits a boolean that re-evaluates on every refresh.
+ *
+ * Unit-testable without Angular DI: `new SimplrFlagsService(config)`.
+ */
+declare class SimplrFlagsService implements OnDestroy {
+    /** The underlying core SDK instance. */
+    readonly core: SimplrFlags;
+    /** Emits the full `{ key -> FlagDefinition }` map on every refresh. */
+    readonly flags$: BehaviorSubject<Record<string, FlagDefinition>>;
+    private readonly config?;
+    private refreshTimer;
+    private autoInitDone;
+    constructor(config?: SimplrConfig);
+    /**
+     * Initialize the flag engine. Loads flags from `/v1/flags`, seeds `flags$`,
+     * and starts an internal refresh loop that re-emits `flags$` on each cycle.
+     */
+    initialize(overrides?: Partial<SimplrFlagsConfig>): Promise<void>;
+    /** Set the default user id used for flag evaluation/bucketing. */
+    setUser(userId: string): void;
+    /** Manually refresh flags from the server and re-emit `flags$`. */
+    refresh(): Promise<void>;
+    /** Manually refresh flags as an Observable. */
+    refresh$(): Observable<void>;
+    /** Evaluate a flag synchronously (local eval, murmurhash bucketing). */
+    isEnabled(key: string, ctx?: EvalContext): boolean;
+    /**
+     * Observe a single flag as a boolean stream. Re-evaluates and emits whenever
+     * `flags$` changes (i.e. on every refresh), deduping consecutive equal values.
+     */
+    observeFlag(key: string, ctx?: EvalContext): Observable<boolean>;
+    /** Whether the engine has loaded its initial flag set. */
+    isReady(): boolean;
+    /** Snapshot of all currently-known flag definitions. */
+    getAll(): Record<string, FlagDefinition>;
+    private emit;
+    ngOnDestroy(): void;
+}
+
+/**
+ * Wraps the core `SimplrProfiles` SDK: anonymous user profile management and
+ * order fraud scoring. Methods are exposed as Promises and `*$` Observable
+ * variants. Device fingerprints are auto-collected via a wired-in `SimplrFraud`
+ * collector, matching the browser core behavior.
+ *
+ * Unit-testable without Angular DI: `new SimplrProfilesService(config)`.
+ */
+declare class SimplrProfilesService {
+    /** The underlying core SDK instance. */
+    readonly core: SimplrProfiles;
+    constructor(config?: SimplrConfig);
+    /** Identify a user — creates/updates an anonymous profile, links the device. */
+    identify(externalId: string, options?: IdentifyOptions): Promise<ProfileIdentifyResult>;
+    /** Observable variant of {@link identify}. */
+    identify$(externalId: string, options?: IdentifyOptions): Observable<ProfileIdentifyResult>;
+    /** Submit an order for real-time fraud scoring (`/v1/orders`). */
+    submitOrder(order: ProfileOrderInput): Promise<ProfileOrderFraudResult>;
+    /** Observable variant of {@link submitOrder}. */
+    submitOrder$(order: ProfileOrderInput): Observable<ProfileOrderFraudResult>;
+    /** Get the risk profile for a user (`GET /v1/profiles/{externalId}`). */
+    getProfileRisk(externalId: string): Promise<ProfileRiskResult>;
+    /** Observable variant of {@link getProfileRisk}. */
+    getProfileRisk$(externalId: string): Observable<ProfileRiskResult>;
+    /** Report a profile outcome as `fraud` or `legitimate`. */
+    reportOutcome(externalId: string, outcome: "fraud" | "legitimate"): Promise<void>;
+    /** Observable variant of {@link reportOutcome}. */
+    reportOutcome$(externalId: string, outcome: "fraud" | "legitimate"): Observable<void>;
+}
+
+type ConnectOptions = Parameters<SimplrAI["connect"]>[0];
+type ConnectResult = Awaited<ReturnType<SimplrAI["connect"]>>;
+type ValidateOptions = Parameters<SimplrAI["validate"]>[1];
+/**
+ * Wraps the core `SimplrAI` delegation client (OAuth-like AI authentication).
+ * Full surface — connect/createDelegation/validate/revoke/list/get/stats/
+ * revokeAllForUser — exposed as Promises and `*$` Observable variants.
+ *
+ * Unit-testable without Angular DI: `new SimplrAIService(config)`.
+ */
+declare class SimplrAIService {
+    /** The underlying core SDK instance. */
+    readonly core: SimplrAI;
+    constructor(config?: SimplrConfig);
+    /** Open the AI Connect gateway (popup/redirect) for users to connect their AI. */
+    connect(options: ConnectOptions): Promise<ConnectResult>;
+    /** Observable variant of {@link connect}. */
+    connect$(options: ConnectOptions): Observable<ConnectResult>;
+    /** Create a new AI delegation token for a user. */
+    createDelegation(options: CreateDelegationOptions): Promise<DelegationResult>;
+    /** Observable variant of {@link createDelegation}. */
+    createDelegation$(options: CreateDelegationOptions): Observable<DelegationResult>;
+    /** Validate a delegation token. */
+    validate(token: string, options?: ValidateOptions): Promise<ValidationResult>;
+    /** Observable variant of {@link validate}. */
+    validate$(token: string, options?: ValidateOptions): Observable<ValidationResult>;
+    /** Revoke a single delegation. */
+    revoke(delegationId: string, reason?: string): Promise<void>;
+    /** Observable variant of {@link revoke}. */
+    revoke$(delegationId: string, reason?: string): Observable<void>;
+    /** List delegations (optionally filtered by user). */
+    list(userId?: string): Promise<DelegationInfo[]>;
+    /** Observable variant of {@link list}. */
+    list$(userId?: string): Observable<DelegationInfo[]>;
+    /** Get a single delegation. */
+    get(delegationId: string): Promise<DelegationInfo>;
+    /** Observable variant of {@link get}. */
+    get$(delegationId: string): Observable<DelegationInfo>;
+    /** Get aggregate delegation statistics. */
+    stats(): Promise<DelegationStats>;
+    /** Observable variant of {@link stats}. */
+    stats$(): Observable<DelegationStats>;
+    /** Revoke all delegations for a user (useful on logout). Returns the count revoked. */
+    revokeAllForUser(userId: string, reason?: string): Promise<number>;
+    /** Observable variant of {@link revokeAllForUser}. */
+    revokeAllForUser$(userId: string, reason?: string): Observable<number>;
+}
+
+/**
+ * Optional Angular `ErrorHandler` that pipes uncaught application errors into
+ * Simplr RUM via {@link SimplrRumService.trackError} before re-logging them.
+ *
+ * Wire it up by adding `{ provide: ErrorHandler, useClass: SimplrErrorHandler }`
+ * to your providers (or pass `errorHandler: true` to `provideSimplr()`).
+ */
+declare class SimplrErrorHandler implements ErrorHandler {
+    private readonly rum?;
+    constructor(rum?: SimplrRumService | undefined);
+    handleError(error: unknown): void;
+}
+
+export { type ProvideSimplrOptions, SIMPLR_CONFIG, SIMPLR_DIRECTIVES, SimplrAIService, type SimplrConfig, SimplrErrorHandler, SimplrFlagsService, SimplrModule, SimplrProfilesService, SimplrProtectDirective, SimplrProtectedFormComponent, SimplrRumService, SimplrRumViewDirective, SimplrService, provideSimplr };