@telemetry-tracker/core 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { SDK_VERSION } from "./version.js";
+export { SDK_VERSION };
+export declare function getAnonymousId(): string;
+export type TelemetryConfig = {
+    ingestUrl: string;
+    app: string;
+    /** Project API key (`tt_live_<publicId>_<secret>`). Required in production ingest. */
+    apiKey?: string;
+    platform?: string;
+    environment?: string;
+    release?: string;
+    /** Flush interval in ms. Default 5000. Set 0 to disable batching. */
+    batchInterval?: number;
+    /** Max queue size before flush. Default 10. */
+    batchSize?: number;
+};
+export declare function getSessionId(): string | null;
+/** End the current session and clear the in-memory session id. */
+export declare function endSession(): void;
+export declare function init(c: TelemetryConfig): void;
+export declare function identify(id: string | null): void;
+/** Headers for ingest POST requests (Authorization + Content-Type). */
+export declare function buildIngestHeaders(cfg: Pick<TelemetryConfig, "apiKey">): Record<string, string>;
+export declare function trackEvent(name: string, properties?: Record<string, unknown>): void;
+export declare function trackError(error: Error | {
+    message: string;
+    stack?: string;
+}, context?: Record<string, unknown>): void;
+export declare function screen(name: string): void;
+export declare function getUserId(): string | null;
+export declare function getConfigOrNull(): TelemetryConfig | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,CAAC;AAiBvB,wBAAgB,cAAc,IAAI,MAAM,CAkBvC;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA6GF,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED,kEAAkE;AAClE,wBAAgB,UAAU,IAAI,IAAI,CAOjC;AA4CD,wBAAgB,IAAI,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAgB7C;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEhD;AAYD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO/F;AA4DD,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI,CAqBN;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAcN;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,eAAe,IAAI,eAAe,GAAG,IAAI,CAExD"}

package/dist/index.js

@@ -0,0 +1,324 @@
+const REPORTED = Symbol.for("telemetry.reported");
+import { SDK_VERSION } from "./version.js";
+export { SDK_VERSION };
+const ANON_STORAGE_KEY = "tacko_telemetry_anon_id";
+let anonymousId = null;
+function generateUUID() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export function getAnonymousId() {
+    if (anonymousId)
+        return anonymousId;
+    if (typeof localStorage !== "undefined") {
+        try {
+            const stored = localStorage.getItem(ANON_STORAGE_KEY);
+            if (stored) {
+                anonymousId = stored;
+                return anonymousId;
+            }
+        }
+        catch (_) { }
+    }
+    anonymousId = generateUUID();
+    if (typeof localStorage !== "undefined") {
+        try {
+            localStorage.setItem(ANON_STORAGE_KEY, anonymousId);
+        }
+        catch (_) { }
+    }
+    return anonymousId;
+}
+let config = null;
+let userId = null;
+let browserHandlersInstalled = false;
+let sessionLifecycleInstalled = false;
+let sessionId = null;
+let sessionStartedAt = null;
+const DEFAULT_BATCH_INTERVAL = 5000;
+const DEFAULT_BATCH_SIZE = 10;
+const eventQueue = [];
+let flushTimer = null;
+function ensureUrlFromCfg(cfg, path) {
+    const base = cfg.ingestUrl.replace(/\/$/, "");
+    return `${base}${path}`;
+}
+function buildSessionPayload(cfg, endedAt) {
+    return {
+        session_id: sessionId,
+        app: cfg.app,
+        platform: cfg.platform ?? undefined,
+        environment: cfg.environment ?? undefined,
+        user_id: userId ?? undefined,
+        anonymous_id: getAnonymousId(),
+        sdk_version: SDK_VERSION,
+        started_at: sessionStartedAt?.toISOString(),
+        ended_at: endedAt?.toISOString(),
+    };
+}
+async function postSession(cfg, endedAt) {
+    if (!sessionId)
+        return;
+    try {
+        const res = await fetch(ensureUrlFromCfg(cfg, "/ingest/session"), {
+            method: "POST",
+            headers: buildIngestHeaders(cfg),
+            body: JSON.stringify(buildSessionPayload(cfg, endedAt)),
+        });
+        if (!res.ok) {
+            console.warn("[telemetry] session ingest failed:", res.status, await res.text());
+        }
+    }
+    catch (e) {
+        console.warn("[telemetry] session send error:", e);
+    }
+}
+function postSessionKeepalive(endedAt) {
+    const cfg = getConfigOrNull();
+    if (!cfg || !sessionId)
+        return;
+    try {
+        void fetch(ensureUrlFromCfg(cfg, "/ingest/session"), {
+            method: "POST",
+            headers: buildIngestHeaders(cfg),
+            body: JSON.stringify(buildSessionPayload(cfg, endedAt)),
+            keepalive: true,
+        });
+    }
+    catch (_) { }
+}
+/** End the current session via keepalive POST and clear in-memory session state. */
+function closeSessionKeepalive(endedAt) {
+    if (!sessionId)
+        return;
+    postSessionKeepalive(endedAt);
+    sessionId = null;
+    sessionStartedAt = null;
+}
+function startSession() {
+    sessionId = generateUUID();
+    sessionStartedAt = new Date();
+    const cfg = getConfigOrNull();
+    if (cfg) {
+        void postSession(cfg);
+    }
+}
+function installBrowserSessionLifecycle() {
+    if (sessionLifecycleInstalled)
+        return;
+    if (typeof window === "undefined" ||
+        typeof window.addEventListener !== "function" ||
+        typeof document === "undefined")
+        return;
+    sessionLifecycleInstalled = true;
+    window.addEventListener("pagehide", (event) => {
+        if (event.persisted)
+            return;
+        closeSessionKeepalive(new Date());
+    });
+    window.addEventListener("pageshow", (event) => {
+        if (event.persisted)
+            return;
+        if (!sessionId) {
+            startSession();
+        }
+    });
+}
+export function getSessionId() {
+    return sessionId;
+}
+/** End the current session and clear the in-memory session id. */
+export function endSession() {
+    const cfg = getConfigOrNull();
+    if (!cfg || !sessionId)
+        return;
+    const ended = new Date();
+    void postSession(cfg, ended);
+    sessionId = null;
+    sessionStartedAt = null;
+}
+/** Only install in real browser environments; skip in React Native / Node even if `window` is polyfilled. */
+function installBrowserErrorHandlers() {
+    if (browserHandlersInstalled)
+        return;
+    if (typeof window === "undefined" ||
+        typeof window.addEventListener !== "function")
+        return;
+    browserHandlersInstalled = true;
+    window.onerror = (message, source, lineno, colno, error) => {
+        const cfg = getConfigOrNull();
+        if (!cfg)
+            return false;
+        const err = error && error instanceof Error
+            ? error
+            : new Error(typeof message === "string" ? message : String(message));
+        trackError(err, {
+            source: "window.onerror",
+            filename: source,
+            lineno,
+            colno,
+        });
+        return false; // let other handlers run
+    };
+    window.addEventListener("unhandledrejection", (event) => {
+        const cfg = getConfigOrNull();
+        if (!cfg)
+            return;
+        const reason = event.reason;
+        const err = reason instanceof Error ? reason : new Error(reason != null ? String(reason) : "Unhandled rejection");
+        trackError(err, { source: "unhandledrejection" });
+    });
+}
+export function init(c) {
+    if (sessionId) {
+        endSession();
+    }
+    config = { ...c };
+    warnIfMissingApiKey(config);
+    getAnonymousId(); // ensure anonymous id exists and is persisted (browser) or set in memory (Node)
+    const interval = c.batchInterval ?? DEFAULT_BATCH_INTERVAL;
+    if (interval > 0 && typeof setInterval !== "undefined") {
+        flushTimer = setInterval(flushEvents, interval);
+        const t = flushTimer;
+        if (typeof t.unref === "function")
+            t.unref();
+    }
+    installBrowserErrorHandlers();
+    startSession();
+    installBrowserSessionLifecycle();
+}
+export function identify(id) {
+    userId = id;
+}
+function getConfig() {
+    if (!config)
+        throw new Error("telemetry-core: init() must be called first");
+    return config;
+}
+function ensureUrl(url) {
+    const base = getConfig().ingestUrl.replace(/\/$/, "");
+    return `${base}${url}`;
+}
+/** Headers for ingest POST requests (Authorization + Content-Type). */
+export function buildIngestHeaders(cfg) {
+    const headers = { "Content-Type": "application/json" };
+    const key = cfg.apiKey?.trim();
+    if (key) {
+        headers.Authorization = `Bearer ${key}`;
+    }
+    return headers;
+}
+function warnIfMissingApiKey(cfg) {
+    if (cfg.apiKey?.trim())
+        return;
+    const env = cfg.environment?.toLowerCase();
+    if (env === "development" || env === "dev" || env === "test")
+        return;
+    console.warn("[telemetry] apiKey is not set — ingest requests will fail unless the server allows unauthenticated ingest.");
+}
+async function send(path, body) {
+    const cfg = getConfig();
+    try {
+        const res = await fetch(ensureUrl(path), {
+            method: "POST",
+            headers: buildIngestHeaders(cfg),
+            body: JSON.stringify({
+                ...body,
+                app: cfg.app,
+                platform: cfg.platform ?? undefined,
+                environment: cfg.environment ?? undefined,
+                release: cfg.release ?? undefined,
+                anonymous_id: getAnonymousId(),
+                sdk_version: SDK_VERSION,
+            }),
+        });
+        if (!res.ok) {
+            console.warn("[telemetry] ingest failed:", res.status, await res.text());
+        }
+    }
+    catch (e) {
+        console.warn("[telemetry] send error:", e);
+    }
+}
+function flushEvents() {
+    const cfg = getConfigOrNull();
+    if (!cfg || eventQueue.length === 0)
+        return;
+    const batch = eventQueue.splice(0, eventQueue.length);
+    const base = cfg.ingestUrl.replace(/\/$/, "");
+    const anonId = getAnonymousId();
+    const events = batch.map((e) => ({
+        app: cfg.app,
+        platform: cfg.platform,
+        environment: cfg.environment,
+        release: cfg.release,
+        name: e.name,
+        user_id: e.user_id ?? undefined,
+        session_id: e.session_id,
+        anonymous_id: anonId,
+        sdk_version: SDK_VERSION,
+        properties: e.properties,
+    }));
+    fetch(`${base}/ingest/batch`, {
+        method: "POST",
+        headers: buildIngestHeaders(cfg),
+        body: JSON.stringify({ events }),
+    }).catch((e) => console.warn("[telemetry] batch send error:", e));
+}
+export function trackEvent(name, properties) {
+    const cfg = getConfigOrNull();
+    const interval = cfg?.batchInterval ?? DEFAULT_BATCH_INTERVAL;
+    const batchSize = cfg?.batchSize ?? DEFAULT_BATCH_SIZE;
+    const item = {
+        name,
+        user_id: userId,
+        session_id: sessionId ?? undefined,
+        properties: properties ?? undefined,
+    };
+    if (interval > 0 && typeof setInterval !== "undefined") {
+        eventQueue.push(item);
+        if (eventQueue.length >= batchSize)
+            flushEvents();
+    }
+    else {
+        send("/ingest/event", {
+            name: item.name,
+            user_id: item.user_id ?? undefined,
+            session_id: item.session_id,
+            properties: item.properties,
+        }).catch(() => { });
+    }
+}
+export function trackError(error, context) {
+    if (!getConfigOrNull())
+        return;
+    const err = error instanceof Error ? error : { message: error.message, stack: error.stack };
+    if (err && typeof err === "object" && err[REPORTED])
+        return;
+    const message = err instanceof Error ? err.message : err.message;
+    const stack = err instanceof Error ? err.stack : err.stack;
+    if (err instanceof Error)
+        err[REPORTED] = true;
+    send("/ingest/error", {
+        message,
+        stack: stack ?? undefined,
+        context: context ?? undefined,
+        user_id: userId ?? undefined,
+        session_id: sessionId ?? undefined,
+    }).catch(() => { });
+}
+export function screen(name) {
+    trackEvent("$screen", { name });
+}
+export function getUserId() {
+    return userId;
+}
+export function getConfigOrNull() {
+    return config;
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Injected at build time from package.json. Do not edit manually. */
+export declare const SDK_VERSION = "1.3.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Injected at build time from package.json. Do not edit manually. */
+export const SDK_VERSION = "1.3.0";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@telemetry-tracker/core",
+  "version": "1.3.0",
+  "description": "Lightweight telemetry client: events, errors, sessions. Framework-agnostic core.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Telemetry-Tracker/telemetry-tracker.git",
+    "directory": "packages/telemetry-core"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "telemetry",
+    "analytics",
+    "events",
+    "errors",
+    "tracking"
+  ],
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.6"
+  },
+  "scripts": {
+    "build": "node scripts/inject-version.cjs && rm -rf dist && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  }
+}