@ginger-ai/ginger-js 0.0.1

package/dist/types/device/utils/hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This code is taken from https://github.com/LinusU/murmur-128/blob/master/index.js
+ * But instead of dependencies to encode-utf8 and fmix, I've implemented them here.
+ */
+export declare function hash(key: ArrayBuffer | string, seed?: number): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/types/device/utils/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/device/utils/hash.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoLH,wBAAgB,IAAI,CAAE,GAAG,EAAG,WAAW,GAAG,MAAM,EAAE,IAAI,SAAI,GAAI,MAAM,CAkBnE"}

package/dist/types/device/utils/misc.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts an error object to a plain object that can be used with `JSON.stringify`.
+ * If you just run `JSON.stringify(error)`, you'll get `'{}'`.
+ */
+export declare function errorToObject(error: Readonly<Error>): Record<string, unknown>;
+export declare function isFunctionNative(func: (...args: unknown[]) => unknown): boolean;
+//# sourceMappingURL=misc.d.ts.map

package/dist/types/device/utils/misc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../../src/device/utils/misc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,OAAO,CAE/E"}

package/dist/types/device/utils/raceAll.d.ts

@@ -0,0 +1,9 @@
+type DelayedPromise<T> = Promise<T>;
+export declare function delay<T>(t: number, val: T): DelayedPromise<T>;
+export interface RaceResult<T> {
+    value: T;
+    elapsed?: number;
+}
+export declare function raceAll<T>(promises: Promise<T>[], timeoutTime: number, timeoutVal: T): Promise<(T | undefined)[]>;
+export {};
+//# sourceMappingURL=raceAll.d.ts.map

package/dist/types/device/utils/raceAll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raceAll.d.ts","sourceRoot":"","sources":["../../../src/device/utils/raceAll.ts"],"names":[],"mappings":"AAAA,KAAK,cAAc,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;AAEpC,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAI7D;AAGD,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAIjH"}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { generateRequestId, GingerHttpClient, HttpClient, GingerClientError, GingerError, pageVisibility } from "./core";
+export { fetchModules, buildInitialPayload } from "./device";
+export { GingerJsClient } from "./client";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAC,MAAM,QAAQ,CAAC;AACxH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ginger-ai/ginger-js",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "GingerJs JavaScript agent for Single page application (SPA)",
+  "main": "dist/ginger.cjs.js",
+  "module": "dist/ginger.esm.js",
+  "types": "dist/ginger.esm.d.ts",
+  "unpkg": "dist/ginger.umd.js",
+  "exports": {
+    ".": {
+      "import": "./dist/ginger.esm.js",
+      "require": "./dist/ginger.cjs.js",
+      "types": "./dist/ginger.esm.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "fraud detection",
+    "fingerprinting",
+    "fingerprint",
+    "browser identification",
+    "bot detection",
+    "spoof detection"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "rm -rf dist/* && rm -rf types/* && rollup -c"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.8",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "rollup": "^4.0.0",
+    "rollup-plugin-dts": "^6.2.3",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@fingerprintjs/botd": "^1.9.1",
+    "ua-parser-js": "^2.0.4"
+  }
+}

package/src/behaviour/index.ts

@@ -0,0 +1,279 @@
+import { GingerClientError, FieldMetrics, FillEnum, FillMethod, pageVisibility, Field } from "../core";
+
+interface TrackedFieldMetrics extends FieldMetrics {
+  readonly element: HTMLInputElement | HTMLTextAreaElement;
+}
+
+interface EventConfig {
+  readonly pauseThresholdMs: number;
+}
+
+const { getCount, addListener, removeListener } = pageVisibility();
+
+class EventTracker {
+  private static readonly DEFAULT_CONFIG: EventConfig = {
+    pauseThresholdMs: 1500,
+  };
+
+  private readonly config: EventConfig;
+  private isInitialized = false;
+  private readonly fields: TrackedFieldMetrics[] = [];
+  private readonly trackedFieldIds = new Set<string>();
+
+  constructor(config: Partial<EventConfig> = {}) {
+    this.config = { ...EventTracker.DEFAULT_CONFIG, ...config };
+    addListener();
+  }
+
+  /**
+   * Initialize tracking for multiple form fields
+   */
+  public initializeTracking(fields: readonly Field[]): void {
+    const newFields = fields.filter(
+      (field) => !this.trackedFieldIds.has(field.id)
+    );
+
+    newFields.forEach((field) => this.trackField(field));
+    this.isInitialized = true;
+  }
+
+  /**
+   * Get all tracked metrics data (excluding DOM elements)
+   */
+  get metrics(): FieldMetrics[] {
+    this.ensureInitialized();
+    return this.fields.map(({ element, ...field }) => field);
+  }
+
+  /**
+   * Remove tracking from specific field or all fields
+   */
+  public removeTracking(fieldId?: string): void {
+    if (fieldId) {
+      this.removeFieldTracking(fieldId);
+    } else {
+      this.removeAllTracking();
+    }
+  }
+
+  // Private implementation methods
+
+  private trackField(field: Field): void {
+    const { id, ltm } = field;
+    const element = this.getValidElement(id);
+    const fieldMetric = this.createFieldMetric(id, element, ltm);
+
+    this.fields.push(fieldMetric);
+    this.trackedFieldIds.add(id);
+
+    // Use bound method to maintain context
+    const boundHandler = this.createInputHandler(fieldMetric);
+    element.addEventListener("input", boundHandler);
+  }
+
+  private getValidElement(id: string): HTMLInputElement | HTMLTextAreaElement {
+    const element = document.getElementById(id);
+
+    if (!element) {
+      throw new GingerClientError(
+        `Element with ID "${id}" was not found in the DOM. Please ensure the ID is correctly assigned to an input element.`
+      );
+    }
+
+    if (!this.isValidInputElement(element)) {
+      throw new GingerClientError(
+        `Element with ID "${id}" must be an HTMLInputElement or HTMLTextAreaElement.`
+      );
+    }
+
+    return element;
+  }
+
+  private isValidInputElement(
+    element: Element
+  ): element is HTMLInputElement | HTMLTextAreaElement {
+    return (
+      element instanceof HTMLInputElement ||
+      element instanceof HTMLTextAreaElement
+    );
+  }
+
+  private createFieldMetric(
+    id: string,
+    element: HTMLInputElement | HTMLTextAreaElement,
+    ltm?: boolean
+  ): TrackedFieldMetrics {
+    return {
+      field_name: id,
+      started_at: 0,
+      ended_at: 0,
+      interaction_count: 0,
+      fill_method: null,
+      paste_count: 0,
+      ltm: ltm ?? false,
+      corrections_count: 0,
+      pauses: 0,
+      pauseDurations: [],
+      element,
+    };
+  }
+
+  private createInputHandler(field: TrackedFieldMetrics) {
+    return (event: Event): void => {
+      this.handleInput(field, event as InputEvent);
+    };
+  }
+
+  private handleInput(
+    currentField: TrackedFieldMetrics,
+    event: InputEvent
+  ): void {
+    const now = performance.now();
+    const lastInteractionTime = currentField.ended_at || 0;
+
+    const interactions = this.analyzeInteraction(
+      currentField,
+      event,
+      now,
+      lastInteractionTime
+    );
+
+    this.updateFieldMetrics(currentField, interactions, now);
+  }
+
+  private analyzeInteraction(
+    field: TrackedFieldMetrics,
+    event: InputEvent,
+    now: number,
+    lastInteractionTime: number
+  ) {
+    const fillMethod = this.determineFillMethod(field, event);
+
+    return {
+      fillMethod,
+      isCorrection: this.isCorrection(event),
+      isPaste: this.isPaste(fillMethod, event),
+      isPause: this.isPause(now, lastInteractionTime),
+      pauseDuration: now - lastInteractionTime,
+    };
+  }
+
+  private updateFieldMetrics(
+    field: TrackedFieldMetrics,
+    interactions: ReturnType<typeof this.analyzeInteraction>,
+    now: number
+  ): void {
+    // Initialize start time on first interaction
+    if (!field.started_at) {
+      field.started_at = now;
+    }
+
+    field.ended_at = now;
+    field.fill_method = interactions.fillMethod;
+    field.interaction_count += 1;
+
+    if (interactions.isCorrection) field.corrections_count += 1;
+    if (interactions.isPaste) field.paste_count += 1;
+    if (interactions.isPause) {
+      field.pauses += 1;
+      field.pauseDurations.push(interactions.pauseDuration);
+    }
+  }
+
+  private determineFillMethod(
+    field: TrackedFieldMetrics,
+    event: InputEvent
+  ): FillMethod {
+    const inputType = event.inputType;
+    if (!inputType) return FillEnum.paste;
+
+    const currentMethod: FillMethod =
+      inputType === "insertText"
+        ? FillEnum.typed
+        : inputType === "insertFromPaste"
+        ? FillEnum.paste
+        : FillEnum.mixed;
+
+    // If methods have been mixed, maintain "mixed" state
+    if (field.fill_method && field.fill_method !== currentMethod) {
+      return FillEnum.mixed;
+    }
+
+    return currentMethod;
+  }
+
+  private isCorrection(event: InputEvent): boolean {
+    return event.inputType === "deleteContentBackward";
+  }
+
+  private isPaste(fillMethod: FillMethod, event: InputEvent): boolean {
+    return (
+      fillMethod === FillEnum.paste || event.inputType === "insertFromPaste"
+    );
+  }
+
+  private isPause(now: number, lastInteractionTime: number): boolean {
+    if (lastInteractionTime === 0) return false;
+
+    const timeSinceLastKeystroke = now - lastInteractionTime;
+    return timeSinceLastKeystroke > this.config.pauseThresholdMs;
+  }
+
+  private removeFieldTracking(fieldId: string): void {
+    const index = this.fields.findIndex(
+      (field) => field.field_name === fieldId
+    );
+
+    if (index === -1) return;
+
+    const field = this.fields[index];
+    this.cleanupFieldTracking(field);
+
+    this.fields.splice(index, 1);
+    this.trackedFieldIds.delete(fieldId);
+  }
+
+  private removeAllTracking(): void {
+    this.fields.forEach((field) => this.cleanupFieldTracking(field));
+    this.fields.length = 0;
+    this.trackedFieldIds.clear();
+  }
+
+  private cleanupFieldTracking(field: TrackedFieldMetrics): void {
+    // Note: We can't remove the exact handler since we're using bound methods
+    // In a real implementation, you'd want to store the bound handlers
+    field.element.removeEventListener("input", this.createInputHandler(field));
+  }
+
+  private ensureInitialized(): void {
+    if (!this.isInitialized) {
+      throw new GingerClientError(
+        "Ginger.trackEvent must be initialized before data can be fetched."
+      );
+    }
+  }
+}
+
+// Singleton instance for the module
+const eventTracker = new EventTracker();
+
+// Public API exports
+export const trackInputs = (fields: readonly Field[]): void => {
+  eventTracker.initializeTracking(fields);
+};
+
+export const getTrackedFields = (): {
+  distractions_count: number;
+  fields: FieldMetrics[];
+} => {
+  return {
+    distractions_count: getCount(),
+    fields: eventTracker.metrics,
+  };
+};
+
+export const removeTracking = (fieldId?: string): void => {
+  eventTracker.removeTracking(fieldId);
+};
+
+export { EventTracker, removeListener };

package/src/client/index.ts

@@ -0,0 +1,132 @@
+import {
+  trackInputs,
+  getTrackedFields,
+  removeListener,
+} from "../behaviour";
+
+import { buildInitialPayload } from "../device";
+
+import {
+  generateRequestId,
+  GingerClientError,
+  HttpClient,
+  GingerHttpClient,
+  BehaviourPayloadResponse,
+  Configurations,
+  EVENT_TYPES,
+  EventParams,
+  Payload,
+  PayloadResponse,
+  BehaviourPayload,
+  BehaviourParams,
+  PayloadResponseData,
+  BehaviourPayloadResponseData,
+} from "../core";
+
+interface GingerClient {
+  initialize(configs: Configurations): Promise<PayloadResponse | undefined>;
+  trackEvent(params: BehaviourParams): void;
+  getTrackedData(): BehaviourPayload;
+  submitEvent(): Promise<BehaviourPayloadResponseData>;
+}
+
+export class GingerJsClient implements GingerClient {
+  private readonly requestId = generateRequestId();
+  private deviceResponse: PayloadResponseData | undefined;
+  private isInitialized: boolean = false;
+  private trackDetails: EventParams | undefined;
+  private httpClient: HttpClient;
+
+  constructor({ apikey }: Configurations) {
+    this.httpClient = new GingerHttpClient(apikey);
+  }
+
+  async initialize() {
+    try {
+      const sdkInfo = { name: '@ginger-ai/ginger-js', version: '0.0.1' };
+      const payload = await buildInitialPayload(this.requestId, sdkInfo);
+      const response = await this.httpClient.post<Payload, PayloadResponse>({
+        url: `/api/v1/devices`,
+        payload,
+      });
+
+      this.isInitialized = true;
+      this.deviceResponse = response.data;
+
+      return response;
+    } catch (error) {
+      this.isInitialized = false;
+      throw new GingerClientError(`Initialization failed: ${error}`);
+    }
+  }
+
+  trackEvent({ event_type, track_fields, request_id }: BehaviourParams): void {
+    if (!this.isInitialized) {
+      throw new GingerClientError(
+        "Unsuccessful Initialization. Cannot track behaviour."
+      );
+    }
+
+    if (!EVENT_TYPES.includes(event_type)) {
+      throw new GingerClientError(
+        `Invalid event type: ${event_type}. Allowed types are: ${EVENT_TYPES.join(
+          ", "
+        )}`
+      );
+    }
+
+    trackInputs(track_fields);
+    this.trackDetails = {
+      event_type,
+      request_id,
+      fingerprint_id: this.deviceResponse?.fingerprint_id || "",
+    };
+  }
+
+  /**
+   * Get tracked data
+   */
+  getTrackedData = () => {
+    if (!this.isInitialized) {
+      throw new GingerClientError(
+        "Unsuccessful Initialization. Cannot get tracked data."
+      );
+    }
+
+    if (!this.trackDetails) {
+      throw new GingerClientError(
+        "Tracking not initiated. Call `trackEvent` before getting tracked data."
+      );
+    }
+
+    const trackData = getTrackedFields();
+
+    return {
+      event_type: this.trackDetails.event_type,
+      request_id: this.trackDetails.request_id,
+      fingerprint_id: this.trackDetails.fingerprint_id,
+      data: { ...trackData },
+    };
+  };
+
+  /**
+   * Call submitEvent to submit tracked data
+   */
+  submitEvent = async () => {
+    const payload = this.getTrackedData();
+
+    try {
+      const response = await this.httpClient.post<
+        BehaviourPayload,
+        BehaviourPayloadResponse
+      >({ url: `/api/v1/events`, payload });
+
+      removeListener();
+      return response.data;
+    } catch (error) {
+      throw new GingerClientError(
+        `Tracked Data submission failed: ${String(error)}`
+      );
+    }
+  };
+}

package/src/core/constants.ts

@@ -0,0 +1,4 @@
+export const CONSTANTS = {
+    LIVE_URL: "https://app.getrayyan.com",
+    TEST_URL: "https://test.getrayyan.com"
+}

package/src/core/dto/bot-detector.dto.ts

@@ -0,0 +1,32 @@
+declare const BotKind: {
+  readonly Awesomium: "awesomium";
+  readonly Cef: "cef";
+  readonly CefSharp: "cefsharp";
+  readonly CoachJS: "coachjs";
+  readonly Electron: "electron";
+  readonly FMiner: "fminer";
+  readonly Geb: "geb";
+  readonly NightmareJS: "nightmarejs";
+  readonly Phantomas: "phantomas";
+  readonly PhantomJS: "phantomjs";
+  readonly Rhino: "rhino";
+  readonly Selenium: "selenium";
+  readonly Sequentum: "sequentum";
+  readonly SlimerJS: "slimerjs";
+  readonly WebDriverIO: "webdriverio";
+  readonly WebDriver: "webdriver";
+  readonly HeadlessChrome: "headless_chrome";
+  readonly Unknown: "unknown";
+  None: "none";
+};
+type BotKind = (typeof BotKind)[keyof typeof BotKind];
+
+export type BotDetectionResult =
+  | {
+      status: boolean;
+      botKind: BotKind;
+    }
+  | {
+      status: boolean;
+    }
+  | null;

package/src/core/dto/device-detector.dto.ts

@@ -0,0 +1,67 @@
+export const ALLOWED_OS = [
+  "ios",
+  "android",
+  "windows",
+  "macos",
+  "linux",
+] as const;
+export const ALLOWED_DEVICE_TYPES = ["mobile", "desktop", "tablet"] as const;
+
+export type AllowedOs = (typeof ALLOWED_OS)[number];
+export type DeviceType = (typeof ALLOWED_DEVICE_TYPES)[number] | null;
+
+export interface BrandInfo {
+  brand: string;
+  version: string;
+}
+
+export interface ClaimedDevice {
+  platform: string;
+  mobile: boolean;
+  brands: BrandInfo[];
+  guessedDeviceType: DeviceType | null;
+}
+
+export interface ScreenInfo {
+  width: number;
+  height: number;
+  pixelRatio: number;
+}
+
+export interface WebGLInfo {
+  vendor?: string;
+  renderer?: string;
+  error: string;
+}
+export interface DeviceSignals {
+  actualPlatform: string;
+  touchPoints: number;
+  screen: ScreenInfo;
+  webGL: WebGLInfo;
+  readonly userAgentString: string;
+}
+
+export interface DeviceAnalysis {
+  confidence: number;
+  spoofingConfidence: number;
+  isSpoofed: boolean;
+  detectionConflicts: string[];
+  realPlatform: AllowedOs | null;
+  realDeviceType: DeviceType;
+}
+export interface DeviceResults {
+  claimed: ClaimedDevice;
+  signals: DeviceSignals;
+  analysis: DeviceAnalysis;
+}
+
+export interface RefinedDeviceResults extends DeviceResults {
+  deviceOs: AllowedOs | null;
+  deviceType: DeviceType;
+  tampering: deviceTampering;
+}
+
+export interface deviceTampering {
+  status: boolean;
+  confidence?: number;
+}

package/src/core/dto/fingerprint.dto.ts

@@ -0,0 +1,38 @@
+export interface FingerprintComponentValue {
+  [key: string]:
+    | string
+    | string[]
+    | number
+    | boolean
+    | undefined
+    | null
+    | FingerprintComponentValue
+    | FingerprintComponentValue[];
+}
+
+export interface RawDeviceData extends FingerprintComponentValue {
+  audio?: FingerprintComponentValue;
+  fonts?: FingerprintComponentValue;
+  hardware?: FingerprintComponentValue;
+  locales?: FingerprintComponentValue;
+  permissions?: FingerprintComponentValue;
+  screen?: FingerprintComponentValue;
+  system?: FingerprintComponentValue;
+  emojiFingerprint?: FingerprintComponentValue;
+  math?: FingerprintComponentValue;
+  vendorFlavour?: FingerprintComponentValue;
+  canvas?: FingerprintComponentValue;
+  webgl?: FingerprintComponentValue;
+  plugins?: FingerprintComponentValue;
+  domBlockers?: FingerprintComponentValue;
+  forcedColors?: FingerprintComponentValue;
+  colorGamut?: FingerprintComponentValue;
+  osCpu?: FingerprintComponentValue;
+  audioLatency?: FingerprintComponentValue;
+}
+
+export interface GingerJsFp {
+  hash: string;
+  data: RawDeviceData;
+  componentsUsedForHash: Array<keyof RawDeviceData>;
+}