@simplr-ai/vue 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,385 @@
+import { InjectionKey, App, ComputedRef, Ref, MaybeRefOrGetter, DefineComponent, Directive } from 'vue';
+import { SimplrFraud, SimplrFlags, SimplrProfiles, SimplrRUM, SimplrAI, SimplrFraudConfig, SimplrFlagsConfig, SimplrProfilesConfig, SimplrRUMConfig, AIDelegationConfig, CollectedSignals, DeviceSignals, BehaviorSignals, FlagDefinition, EvalContext, IdentifyOptions, ProfileIdentifyResult, ProfileOrderInput, ProfileOrderFraudResult, ProfileRiskResult, RUMLogLevel, RUMActionType, 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, RUMActionType, RUMEvent, RUMEventType, RUMLogLevel, SimplrAI, SimplrFlags, SimplrFlagsConfig, SimplrFraud, SimplrFraudConfig, SimplrProfiles, SimplrProfilesConfig, SimplrRUM, SimplrRUMConfig, TouchMetrics, ValidationResult, clearDeviceId, createFingerprintHash, createSimplrAI, createSimplrProfiles, getDeviceId, murmurHash3, sha256, simplrFlags, simplrRUM } from '@simplr-ai/js';
+
+/**
+ * The bundle of configured core SDK instances provided by the Simplr Vue plugin.
+ * Every instance is the real `@simplr-ai/js` object — this adapter never
+ * reimplements behaviour, it only wires the core surface into Vue primitives.
+ */
+interface SimplrContext {
+    /** Core fraud client: device fingerprint + behavioral biometrics + collect(). */
+    fraud: SimplrFraud;
+    /** Feature flags client (local eval + murmurhash bucketing). May be undefined if not configured. */
+    flags?: SimplrFlags;
+    /** Anonymous profiles + order fraud scoring client. May be undefined if not configured. */
+    profiles?: SimplrProfiles;
+    /** Real User Monitoring client (singleton). May be undefined if not configured. */
+    rum?: SimplrRUM;
+    /** AI delegation (OAuth-like) client. May be undefined if not configured. */
+    ai?: SimplrAI;
+}
+/** Vue injection key for the full Simplr context bundle. */
+declare const SimplrInjectionKey: InjectionKey<SimplrContext>;
+declare module "@vue/runtime-core" {
+    interface ComponentCustomProperties {
+        $simplr: SimplrContext;
+    }
+}
+
+interface CreateSimplrConfig {
+    /**
+     * Public API key (`pk_*`). Used as the default key for every sub-client
+     * unless that sub-client supplies its own key in its config block.
+     */
+    apiKey?: string;
+    /** API base URL override (passed to flags + profiles). */
+    baseUrl?: string;
+    /** Core fraud / device-signal config (or `false` to skip — fraud is on by default). */
+    fraud?: SimplrFraudConfig;
+    /**
+     * Feature flags config. Pass `true` to enable with defaults, an object to
+     * customise, or omit to skip. `initialize()` is called automatically.
+     */
+    flags?: Partial<SimplrFlagsConfig> | boolean;
+    /** Profiles config. Pass `true` to enable with the shared key/baseUrl, or an object. */
+    profiles?: Partial<SimplrProfilesConfig> | boolean;
+    /** RUM config — requires at least `applicationId`. Omit to skip RUM. */
+    rum?: SimplrRUMConfig;
+    /** AI delegation config. Pass `true` to enable with the shared key, or an object. */
+    ai?: Partial<AIDelegationConfig> | boolean;
+}
+/**
+ * The Simplr Vue plugin. Returned by {@link createSimplr}; install with
+ * `app.use(simplr)`. It builds the configured core SDK instances and provides
+ * them through Vue's `provide`/`inject` so every composable can reach them.
+ */
+interface SimplrPlugin {
+    /** Vue install hook — registered when you call `app.use(plugin)`. */
+    install: (app: App) => void;
+    /** The constructed context — handy for direct access / SSR / testing. */
+    context: SimplrContext;
+}
+/**
+ * Create an installable Simplr plugin that wires the full `@simplr-ai/js`
+ * surface (fraud, flags, profiles, RUM, AI delegation) into Vue.
+ *
+ * ```ts
+ * import { createSimplr } from "@simplr-ai/vue";
+ * app.use(createSimplr({
+ *   apiKey: "pk_live_…",
+ *   flags: true,
+ *   profiles: true,
+ *   rum: { apiKey: "pk_live_…", applicationId: "my-app" },
+ *   ai: true,
+ * }));
+ * ```
+ */
+declare function createSimplr(config?: CreateSimplrConfig): SimplrPlugin;
+
+/**
+ * Low-level accessor for the full provided Simplr context bundle.
+ * Throws a helpful error if the plugin was never installed.
+ */
+declare function useSimplrContext(): SimplrContext;
+
+interface UseSimplrReturn {
+    /** The underlying core fraud client. */
+    simplr: SimplrFraud;
+    /** Whether the SDK has finished initialization and is ready to collect. */
+    isReady: ComputedRef<boolean>;
+    /** Collect all signals (device fingerprint + behavioral biometrics). */
+    collect: () => Promise<CollectedSignals>;
+    /** Collect device fingerprint signals only. */
+    collectDeviceSignals: () => Promise<DeviceSignals>;
+    /** Collect behavioral biometric signals only (sync). */
+    collectBehaviorSignals: () => BehaviorSignals;
+    /** Reset all collected behavioral data. */
+    reset: () => void;
+    /** Get input tracking handlers/attrs for a named field. */
+    trackInput: SimplrFraud["trackInput"];
+    /** Start biometric tracking. */
+    startTracking: () => void;
+    /** Stop biometric tracking. */
+    stopTracking: () => void;
+}
+/**
+ * Access the core Simplr fraud client and its `collect()` device/behavior
+ * signal API. Thin wrapper over `@simplr-ai/js`'s `SimplrFraud`.
+ *
+ * Covers: [device fingerprint] [behavioral biometrics] [input validation helpers].
+ */
+declare function useSimplr(): UseSimplrReturn;
+
+interface UseDeviceSignalsOptions {
+    /** Collect immediately on mount (default: true). */
+    immediate?: boolean;
+}
+interface UseDeviceSignalsReturn {
+    /** The collected device fingerprint signals (null until first collect). */
+    signals: Ref<DeviceSignals | null>;
+    /** Whether a collection is in flight. */
+    loading: Ref<boolean>;
+    /** Error from the last collection, if any. */
+    error: Ref<Error | null>;
+    /** Re-collect the device signals. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Reactive device fingerprint collection. Mirrors the React
+ * `useDeviceFingerprint` hook.
+ *
+ * Covers: [device fingerprint].
+ */
+declare function useDeviceSignals(options?: UseDeviceSignalsOptions): UseDeviceSignalsReturn;
+
+interface UseFeatureFlagReturn {
+    /** Reactive boolean — re-evaluates as flags load/refresh and as ctx changes. */
+    enabled: ComputedRef<boolean>;
+    /** Whether the flags client has loaded at least once. */
+    isReady: Ref<boolean>;
+}
+/**
+ * Reactively evaluate a single feature flag. Re-evaluates when the flag set
+ * finishes loading / refreshes, and when the (optional) eval context changes.
+ *
+ * Covers: [feature flags local eval].
+ */
+declare function useFeatureFlag(key: MaybeRefOrGetter<string>, ctx?: MaybeRefOrGetter<EvalContext | undefined>): UseFeatureFlagReturn;
+interface UseFeatureFlagsReturn {
+    /** Reactive map of every flag key → enabled boolean. */
+    flags: ComputedRef<Record<string, boolean>>;
+    /** Raw flag definitions snapshot. */
+    definitions: ComputedRef<Record<string, FlagDefinition>>;
+    /** Imperative evaluation honoring the shared context. */
+    isEnabled: (key: string, ctx?: EvalContext) => boolean;
+    /** Whether the flags client has loaded at least once. */
+    isReady: Ref<boolean>;
+    /** Force a refresh from the API. */
+    refresh: () => Promise<void>;
+    /** Set the default user id used for bucketing/targeting. */
+    setUser: (userId: string) => void;
+}
+/**
+ * Reactively evaluate the full feature-flag set as a `{ key: boolean }` map.
+ *
+ * Covers: [feature flags local eval].
+ */
+declare function useFeatureFlags(ctx?: MaybeRefOrGetter<EvalContext | undefined>): UseFeatureFlagsReturn;
+
+interface UseProfilesReturn {
+    /** The underlying core profiles client. */
+    profiles: SimplrProfiles;
+    /** Loading state of the most recent operation. */
+    loading: Ref<boolean>;
+    /** Error from the most recent operation. */
+    error: Ref<Error | null>;
+    /** Identify a user — creates/updates an anonymous profile, links the device. */
+    identify: (externalId: string, options?: IdentifyOptions) => Promise<ProfileIdentifyResult>;
+    /** Submit an order for real-time fraud scoring. */
+    submitOrder: (order: ProfileOrderInput) => Promise<ProfileOrderFraudResult>;
+    /** Fetch the risk profile for a user. */
+    getProfileRisk: (externalId: string) => Promise<ProfileRiskResult>;
+    /** Report a profile as fraud or legitimate. */
+    reportOutcome: (externalId: string, outcome: "fraud" | "legitimate") => Promise<void>;
+}
+/**
+ * Anonymous user profiles + order fraud scoring. Thin wrapper over the core
+ * `SimplrProfiles`; device fingerprint auto-attach is already wired by the
+ * plugin via `setDeviceSignalCollector`.
+ *
+ * Covers: [profiles/identify] [order scoring /v1/orders].
+ */
+declare function useProfiles(): UseProfilesReturn;
+
+/**
+ * Access the RUM instance. Falls back to the core singleton (`simplrRUM`) when
+ * the plugin did not configure RUM, so RUM composables work standalone too.
+ */
+declare function useRum(): SimplrRUM;
+/**
+ * Track a page/screen view when the component mounts (and re-track if the name
+ * changes). Mirrors the React `useTrackView` hook.
+ *
+ * Covers: [RUM full].
+ */
+declare function useTrackView(name: MaybeRefOrGetter<string>): void;
+/**
+ * Returns an action-tracking function. Mirrors React `useTrackAction`.
+ *
+ * Covers: [RUM full].
+ */
+declare function useTrackAction(): (name: string, type: RUMActionType, attributes?: Record<string, unknown>) => void;
+/**
+ * Returns an error-tracking function. Mirrors React `useTrackError`.
+ *
+ * Covers: [RUM full].
+ */
+declare function useTrackError(): (error: Error, context?: Record<string, unknown>) => void;
+/**
+ * Leveled logging helpers backed by RUM. Mirrors React `useRUMLogger`.
+ *
+ * Covers: [RUM full].
+ */
+declare function useRumLogger(): Record<RUMLogLevel, (message: string, context?: Record<string, unknown>) => void>;
+/**
+ * Set / clear the RUM user. Mirrors React `useRUMUser`.
+ *
+ * Covers: [RUM full].
+ */
+declare function useRumUser(): {
+    setUser: (userId: string, attributes?: Record<string, unknown>) => void;
+    clearUser: () => void;
+};
+/**
+ * Add / remove global RUM attributes. Mirrors React `useRUMAttributes`.
+ *
+ * Covers: [RUM full].
+ */
+declare function useRumAttributes(): {
+    addAttribute: (key: string, value: unknown) => void;
+    removeAttribute: (key: string) => void;
+};
+/**
+ * Wrap an async operation so its duration is tracked as a RUM action and any
+ * thrown error is reported. Mirrors React `useTrackAsync`.
+ *
+ * Covers: [RUM full].
+ */
+declare function useTrackAsync<T>(operationName: string): (asyncFn: () => Promise<T>) => Promise<T>;
+/**
+ * Install a global Vue `errorHandler` that forwards uncaught component errors
+ * to RUM. Call from a plugin/app setup, e.g. `app.use(rumErrorHandler)` is not
+ * needed — instead `installRumErrorHandler(app)`.
+ */
+declare function flushRumOnUnmount(): void;
+
+type ConnectOptions = Parameters<SimplrAI["connect"]>[0];
+type ConnectResult = Awaited<ReturnType<SimplrAI["connect"]>>;
+type ValidateOptions = {
+    fingerprintHash?: string;
+    aiProvider?: string;
+    action?: string;
+};
+interface UseAIDelegationReturn {
+    /** The underlying core AI client. */
+    ai: SimplrAI;
+    /** Loading state of the most recent operation. */
+    loading: Ref<boolean>;
+    /** Error from the most recent operation. */
+    error: Ref<Error | null>;
+    /** Open the OAuth-like AI Connect gateway (popup/redirect). */
+    connect: (options: ConnectOptions) => Promise<ConnectResult>;
+    /** Create a new AI delegation token. */
+    createDelegation: (options: CreateDelegationOptions) => Promise<DelegationResult>;
+    /** Validate an AI delegation token. */
+    validate: (token: string, options?: ValidateOptions) => Promise<ValidationResult>;
+    /** Revoke a single delegation. */
+    revoke: (delegationId: string, reason?: string) => Promise<void>;
+    /** List delegations (optionally scoped to a user). */
+    list: (userId?: string) => Promise<DelegationInfo[]>;
+    /** Get a single delegation by id. */
+    get: (delegationId: string) => Promise<DelegationInfo>;
+    /** Get delegation statistics. */
+    stats: () => Promise<DelegationStats>;
+    /** Revoke all delegations for a user (e.g. on logout). */
+    revokeAllForUser: (userId: string, reason?: string) => Promise<number>;
+}
+/**
+ * AI delegation (OAuth-like AI authentication). Mirrors React `useAIDelegation`.
+ *
+ * Covers: [AI delegation].
+ */
+declare function useAIDelegation(config?: AIDelegationConfig): UseAIDelegationReturn;
+interface UseDelegationsReturn {
+    /** Reactive list of delegations for the user. */
+    delegations: Ref<DelegationInfo[]>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    /** Re-fetch the list. */
+    refresh: () => Promise<void>;
+    /** Revoke a delegation then refresh the list. */
+    revoke: (delegationId: string, reason?: string) => Promise<void>;
+}
+/**
+ * Manage a reactive list of a user's delegations. Mirrors React `useDelegations`.
+ *
+ * Covers: [AI delegation].
+ */
+declare function useDelegations(config?: AIDelegationConfig, userId?: string): UseDelegationsReturn;
+
+/**
+ * `<SimplrProtectedForm>` — collects device + behavioral signals on submit and
+ * emits them via `@submit` (signals, event) plus `@error` (error).
+ */
+declare const SimplrProtectedForm: DefineComponent<
+  Record<string, never>,
+  Record<string, never>,
+  unknown
+>;
+
+/**
+ * `<SimplrProtectedInput>` — an input that auto-attaches keystroke tracking
+ * handlers and a `data-simplr-field` marker. Props: `field`, `modelValue`.
+ */
+declare const SimplrProtectedInput: DefineComponent<{
+  field: string;
+  modelValue?: string;
+}>;
+
+/** `<RumView name="...">` — tracks a RUM view on mount. */
+declare const RumView: DefineComponent<{ name: string }>;
+
+/**
+ * `<RumErrorBoundary>` — catches descendant errors via onErrorCaptured, reports
+ * them to RUM, and renders the `#fallback` slot. Emits `@error` (error, info).
+ */
+declare const RumErrorBoundary: DefineComponent<
+  Record<string, never>,
+  Record<string, never>,
+  unknown
+>;
+
+/**
+ * `v-simplr-protect="fieldName"` — attaches the core fraud client's keystroke
+ * tracking handlers to an input element and tags it with `data-simplr-field`.
+ *
+ * The bound value is the field name. The bound element MUST receive the active
+ * fraud client through the directive's `arg`/context — to keep the directive
+ * dependency-free of injection, it pulls handlers off the `data-simplr` payload
+ * placed by `<SimplrProtectedForm>` / `<SimplrProtectedInput>`, or, if a
+ * `trackInput` factory is provided via the binding value object, uses that.
+ *
+ * Usage forms:
+ *   v-simplr-protect="'email'"
+ *   v-simplr-protect="{ field: 'email', trackInput }"
+ *
+ * Covers: [behavioral biometrics] [input validation helpers].
+ */
+declare const vSimplrProtect: Directive<HTMLElement, ProtectBinding>;
+type TrackInputFactory = (field: string) => {
+    onKeyDown: (e: KeyboardEvent) => void;
+    onKeyUp: (e: KeyboardEvent) => void;
+    onPaste: () => void;
+    "data-simplr-field": string;
+};
+type ProtectBinding = string | {
+    field: string;
+    trackInput?: TrackInputFactory;
+};
+
+/**
+ * Install a global Vue `app.config.errorHandler` that forwards every uncaught
+ * component error to RUM via `trackError`. Chains to any previously-installed
+ * handler.
+ *
+ * ```ts
+ * import { installRumErrorHandler } from "@simplr-ai/vue";
+ * installRumErrorHandler(app);
+ * ```
+ *
+ * Covers: [RUM full].
+ */
+declare function installRumErrorHandler(app: App, rum?: SimplrRUM): void;
+
+export { type CreateSimplrConfig, type ProtectBinding, RumErrorBoundary, RumView, type SimplrContext, SimplrInjectionKey, type SimplrPlugin, SimplrProtectedForm, SimplrProtectedInput, type TrackInputFactory, type UseAIDelegationReturn, type UseDelegationsReturn, type UseDeviceSignalsOptions, type UseDeviceSignalsReturn, type UseFeatureFlagReturn, type UseFeatureFlagsReturn, type UseProfilesReturn, type UseSimplrReturn, createSimplr, flushRumOnUnmount, installRumErrorHandler, useAIDelegation, useDelegations, useDeviceSignals, useFeatureFlag, useFeatureFlags, useProfiles, useRum, useRumAttributes, useRumLogger, useRumUser, useSimplr, useSimplrContext, useTrackAction, useTrackAsync, useTrackError, useTrackView, vSimplrProtect };