@treasuredata/web-sdk 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Core type definitions for Treasure Data Web SDK
+ */
+import type { PersonalizationFetchConfig } from '../plugins/personalization';
+import type { AddRecordOptions } from '../plugins/record';
+import type { PersonalizationPayload } from '../plugins/page-personalize/offers';
+import type { ApplyPersonalizationOptions } from '../plugins/page-personalize';
+export type JSONValue = string | number | boolean | null | {
+    [key: string]: JSONValue;
+} | JSONValue[];
+export interface TrackEvent {
+    /** Database table name */
+    table: string;
+    /** Event data payload */
+    data: Record<string, JSONValue>;
+    /** Success callback */
+    success?: ((response: TrackResponse) => void) | undefined;
+    /** Error callback */
+    error?: ((error: TDError) => void) | undefined;
+}
+export interface PersonalizationOptions {
+    endpoint: string;
+    token: string;
+    database?: string;
+}
+export interface TrackResponse {
+    success: boolean;
+    message?: string;
+    [key: string]: JSONValue | undefined;
+}
+export interface TDError extends Error {
+    code?: string;
+    status?: number;
+    details?: Record<string, JSONValue>;
+}
+export interface TDConfig {
+    /** API write key */
+    writeKey: string;
+    /** Database name */
+    database: string;
+    /** API endpoint host */
+    host?: string;
+    /** Development mode flag */
+    development?: boolean;
+    /** Global ID cookie name */
+    globalIdCookie?: string;
+    /** Logging flag */
+    logging?: boolean;
+    /** API pathname */
+    pathname?: string;
+    /** Request type */
+    requestType?: string;
+    /** JSONP timeout in milliseconds */
+    jsonpTimeout?: number;
+    /** Start in signed mode */
+    startInSignedMode?: boolean;
+    /** Use server-side cookie */
+    useServerSideCookie?: boolean;
+    /** Server-side cookie domain function */
+    sscDomain?: string | (() => string);
+    /** Server-side cookie server function */
+    sscServer?: (cookieDomain: string) => string;
+    /** Store consent by localStorage */
+    storeConsentByLocalStorage?: boolean;
+    /** Full endpoint URL (computed) */
+    endpoint?: string;
+    /** Global values storage */
+    globals?: Record<string, Record<string, JSONValue>>;
+    /** Cookie storage configuration */
+    storage?: StorageConfiguration;
+    /** CDP host for personalization API (default: 'cdp.in.treasuredata.com') */
+    cdpHost?: string;
+    /** Personalization config; when set, every tracked event also fetches personalization */
+    personalization?: PersonalizationOptions;
+    /** Client ID for tracking */
+    clientId?: string | number;
+}
+export interface StorageConfiguration {
+    name: string;
+    domain: string;
+    path?: string;
+    expires: number;
+}
+export interface Logger {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+export interface TreasureCore {
+    config: TDConfig;
+    log: Logger;
+}
+export interface TreasurePlugin<T = any> {
+    name: string;
+    setup: (core: TreasureCore, sdk: TreasureSDK) => T;
+}
+export interface TreasureSDK extends TreasureCore {
+    use: <T>(plugin: TreasurePlugin<T>) => TreasureSDK & T;
+    /** Get the configured write key */
+    getWriteKey(): string;
+    /** Set the write key */
+    setWriteKey(writeKey: string): void;
+    inSignedMode(): boolean;
+    isGlobalIdEnabled(): boolean;
+    setSignedMode(): void;
+    setAnonymousMode(keepIdentifier?: boolean): void;
+    blockEvents(): void;
+    unblockEvents(): void;
+    areEventsBlocked(): boolean;
+    getUUID(): string;
+    resetUUID(suggestedStorage?: StorageConfiguration, suggestedClientId?: string): void;
+    set(table: string | Record<string, JSONValue>, property?: string | Record<string, JSONValue>, value?: JSONValue): void;
+    get(table?: string, key?: string): JSONValue;
+    removeCachedGlobalID(): void;
+    removeServerCookie(): void;
+    addRecord(table: string, record: Record<string, JSONValue>, success?: (response: TrackResponse) => void, error?: (error: TDError) => void, options?: AddRecordOptions): void;
+    trackEvent(table?: string, record?: Record<string, JSONValue>, success?: (result: TrackResponse) => void, failure?: (error: TDError) => void): void;
+    trackPageview(table?: string, success?: (result: TrackResponse) => void, failure?: (error: TDError) => void, options?: {
+        payload?: Record<string, JSONValue>;
+    }): void;
+    getTrackValues(): Record<string, JSONValue>;
+    getPersonalizationConfig(): PersonalizationOptions | undefined;
+    setPersonalizationConfig(options?: PersonalizationOptions): void;
+    trackClicks(options?: {
+        tableName?: string;
+        element?: string | HTMLElement;
+    }): void;
+    collectUTMParameters(): Record<string, JSONValue>;
+    getUTMParameters(): Record<string, JSONValue>;
+    fetchUserSegments(options: {
+        audienceToken: string | string[];
+        keys?: Record<string, JSONValue>;
+    }, successCallback?: (segments: {
+        key: Record<string, JSONValue>;
+        values: string[];
+        attributes: Record<string, JSONValue>;
+    }[]) => void, errorCallback?: (error: Error) => void): void;
+    fetchUserSegments(audienceToken: string | string[], successCallback?: (segments: {
+        key: Record<string, JSONValue>;
+        values: string[];
+        attributes: Record<string, JSONValue>;
+    }[]) => void, errorCallback?: (error: Error) => void): void;
+    fetchPersonalization(config: {
+        endpoint: string;
+        database: string;
+        table: string;
+        token: string;
+    }, data?: Record<string, JSONValue> | null, successCallback?: (response: Record<string, JSONValue>) => void, errorCallback?: (error: Error) => void): void;
+    applyPersonalization(payload: PersonalizationPayload, options?: ApplyPersonalizationOptions): void;
+    personalizePage(config: PersonalizationFetchConfig, data?: Record<string, JSONValue> | null, successCallback?: (payload: PersonalizationPayload) => void, errorCallback?: (error: Error) => void): void;
+    collectTags(options?: {
+        table?: string;
+        success?: (response: TrackResponse) => void;
+        error?: (error: TDError) => void;
+    }): void;
+    fetchServerCookie(success?: (serverSideId: string) => void, error?: (error: string | Error) => void, forceFetch?: boolean): void;
+    fetchGlobalID(success?: (globalId: string | null) => void, error?: (error: unknown) => void, forceFetch?: boolean, options?: {
+        path?: string;
+        domain?: string;
+        secure?: boolean;
+        maxAge?: number | string | Date;
+        sameSite?: 'None' | 'Lax' | 'Strict';
+    }): void;
+}
+export interface ElementData {
+    tag: string;
+    tree: string;
+    alt?: string;
+    class?: string;
+    href?: string;
+    id?: string;
+    name?: string;
+    role?: string;
+    title?: string;
+    type?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/element.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DOM element utility functions for click tracking
+ */
+export declare function getEventTarget(event: Event): Element;
+export declare function addEventListener(el: Element | Document, type: string, fn: (event: Event) => void): () => void;
+/**
+ * ORIGINAL SOURCE: https://github.com/getsentry/raven-js/
+ * Given a child DOM element, returns a query-selector statement describing that
+ * and its ancestors
+ * e.g. [HTMLElement] => body > div > input#foo.btn[name=baz]
+ */
+export declare function htmlTreeAsString(elem: Element | null): string;
+/**
+ * ORIGINAL SOURCE: https://github.com/getsentry/raven-js/
+ * Returns a simple, query-selector representation of a DOM element
+ * e.g. [HTMLElement] => input#foo.btn[name=baz]
+ */
+export declare function htmlElementAsString(elem: Element | null): string;
+export declare function hasAttribute(element: Element, attrName: string): boolean;
+//# sourceMappingURL=element.d.ts.map

package/dist/utils/lodash.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lightweight lodash-like utility functions
+ * Modern TypeScript implementations without external dependencies
+ */
+export declare function forEach<T>(collection: T[] | Record<string, T>, callback: (value: T, key: string | number) => void): void;
+export declare function isNumber(value: unknown): value is number;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isString(value: unknown): value is string;
+export declare function isArray(value: unknown): value is unknown[];
+export declare function isFunction(value: unknown): value is Function;
+export declare function isEmpty(value: unknown): boolean;
+export declare function keys(obj: Record<string, unknown>): string[];
+export declare function assign<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+export declare function forIn<T>(obj: Record<string, T>, callback: (value: T, key: string) => void): void;
+export declare function omit<T extends Record<string, unknown>>(obj: T, ...keysToOmit: (keyof T)[]): Partial<T>;
+export declare function cloneDeep<T>(value: T): T;
+export declare function noop(): void;
+//# sourceMappingURL=lodash.d.ts.map

package/dist/utils/misc.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Miscellaneous utility functions
+ */
+export declare function disposable(action: () => void): () => void;
+export declare function invariant(condition: unknown, text: string): asserts condition;
+export declare function fetchWithTimeout(url: string, milliseconds: number, options?: RequestInit): Promise<Response>;
+export declare function isLocalStorageAccessible(): boolean;
+export declare function camelCase(str?: string): string | undefined;
+export declare const adlHeaders: {
+    readonly 'Content-Type': "application/vnd.treasuredata.v1+json";
+    readonly Accept: "application/vnd.treasuredata.v1+json";
+};
+export declare const globalIdAdlHeaders: {
+    readonly 'Content-Type': "application/vnd.treasuredata.v1.js+json";
+    readonly Accept: "application/vnd.treasuredata.v1.js+json";
+};
+//# sourceMappingURL=misc.d.ts.map

package/dist/utils/set-cookie.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Set cookie on highest allowed domain utility
+ */
+export interface CookieConfig {
+    domain: string;
+    path?: string;
+    expires: number;
+    customDomain?: boolean;
+}
+/**
+ * Set cookie on highest allowed domain
+ */
+export declare function setCookie(storage: CookieConfig, name: string, value?: string): void;
+//# sourceMappingURL=set-cookie.d.ts.map

package/dist/utils/uuid.d.ts

@@ -0,0 +1,14 @@
+/**
+ * UUID Generation Utility
+ * Generates RFC4122 compliant UUIDs for client identification
+ */
+/**
+ * Generate a UUID v4 (random)
+ * Based on RFC4122 specification
+ */
+export declare function generateUUID(): string;
+/**
+ * Validate if a string is a valid UUID
+ */
+export declare function isValidUUID(uuid: string): boolean;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/utils/xhr.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Modern Fetch API utility functions
+ * Using AbortController for all timeout handling (baseline browser support)
+ */
+declare const FETCH_CREDENTIALS: {
+    readonly 'same-origin': "same-origin";
+    readonly include: "include";
+    readonly omit: "omit";
+};
+interface RequestOptions {
+    headers?: Record<string, string>;
+    credentials?: keyof typeof FETCH_CREDENTIALS;
+    signal?: AbortSignal;
+}
+/**
+ * POST request using fetch API
+ */
+declare function post(url: string, body: any, options?: RequestOptions): Promise<any>;
+/**
+ * GET request using fetch API
+ */
+declare function get(url: string, options?: RequestOptions): Promise<any>;
+/**
+ * Add timeout to any promise using AbortController
+ */
+declare function withTimeout<T>(promiseFactory: (signal: AbortSignal) => Promise<T>, milliseconds: number, timeoutMessage?: string): Promise<T>;
+/**
+ * POST request with timeout using AbortController
+ */
+declare function postWithTimeout(url: string, body: any, milliseconds: number, options?: RequestOptions): Promise<any>;
+/**
+ * GET request with timeout using AbortController
+ */
+declare function getWithTimeout(url: string, milliseconds: number, options?: RequestOptions): Promise<any>;
+/**
+ * Generic timeout utility for any promise-returning function
+ *
+ * @example
+ * const result = await timeoutPromise(
+ *   () => fetch('/api/data'),
+ *   5000,
+ *   'API call timed out'
+ * )
+ */
+declare function timeoutPromise<T>(promiseFactory: () => Promise<T>, milliseconds: number, timeoutMessage?: string): Promise<T>;
+/**
+ * Modern fetch-only API with AbortController timeout handling
+ */
+export declare const api: {
+    post: typeof post;
+    get: typeof get;
+    postWithTimeout: typeof postWithTimeout;
+    getWithTimeout: typeof getWithTimeout;
+    withTimeout: typeof withTimeout;
+    timeoutPromise: typeof timeoutPromise;
+};
+export {};
+//# sourceMappingURL=xhr.d.ts.map

package/dist/vendor/js-cookies.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cookie utility functions
+ * TypeScript implementation of js-cookies functionality
+ */
+export interface CookieOptions {
+    expires?: number | string | Date;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export declare const cookie: {
+    getItem(sKey: string): string | null;
+    setItem(sKey: string, sValue: string, vEnd?: number | string | Date, sPath?: string, sDomain?: string, bSecure?: boolean, sameSite?: "Strict" | "Lax" | "None"): boolean;
+    removeItem(sKey: string, sPath?: string, sDomain?: string): boolean;
+    hasItem(sKey: string): boolean;
+    keys(): string[];
+};
+//# sourceMappingURL=js-cookies.d.ts.map

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@treasuredata/web-sdk",
+  "version": "1.0.0",
+  "description": "Modern TypeScript SDK for Treasure Data - Browser event tracking library",
+  "main": "dist/td-sdk.cjs",
+  "module": "dist/td-sdk.esm.js",
+  "browser": "dist/td-sdk.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/td-sdk.esm.js",
+      "require": "./dist/td-sdk.cjs",
+      "browser": "./dist/td-sdk.js",
+      "default": "./dist/td-sdk.esm.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "./bin/build.sh",
+    "build:vite": "vite build && vite build --config vite.iife.config.ts",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "build:dev": "vite build --mode development",
+    "dev": "vite",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts,.js",
+    "lint:fix": "eslint src/ --ext .ts,.js --fix",
+    "format": "prettier --write \"src/**/*.{ts,js}\" \"test/**/*.{ts,js}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js}\" \"test/**/*.{ts,js}\"",
+    "hooks:install": "git config core.hooksPath .githooks && chmod +x .githooks/pre-commit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm run build:types && node ./scripts/strip-maps-for-publish.cjs",
+    "deploy": "./bin/deploy.sh",
+    "deploy:prod": "./bin/deploy.sh --prod",
+    "deploy:force": "./bin/deploy.sh --force",
+    "deploy:prod:force": "./bin/deploy.sh --force --prod --wait",
+    "upload": "./bin/upload-version.sh",
+    "upload:force": "./bin/upload-version.sh --force",
+    "activate": "./bin/activate-version.sh",
+    "invalidate": "./bin/invalidate-release.sh"
+  },
+  "keywords": [
+    "treasure-data",
+    "analytics",
+    "tracking",
+    "typescript",
+    "browser",
+    "web-sdk"
+  ],
+  "author": "Treasure Data",
+  "license": "Apache-2.0",
+  "browserslist": [
+    "extends browserslist-config-baseline"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
+    "@vitest/coverage-v8": "^2.1.9",
+    "@vitest/ui": "^2.1.9",
+    "browserslist-config-baseline": "^0.5.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "happy-dom": "^20.9.0",
+    "prettier": "^3.8.3",
+    "terser": "^5.46.2",
+    "typescript": "^6.0.3",
+    "vite": "^5.4.21",
+    "vitest": "^2.1.9"
+  },
+  "dependencies": {
+    "comlink": "^4.4.2"
+  }
+}