rsclick-log-sdk-web 0.1.0

package/README.md

@@ -0,0 +1,181 @@
+# `rsclick-log-sdk-web`
+
+用于 `rs-click-log` MVP 的轻量 Web 埋点 SDK。
+
+目标：
+
+- 在浏览器端生成并持久化 `anonymous_id`
+- 自动维护 30 分钟 `session_id`
+- 调用后端 `POST /track/collect` 上报事件
+- 默认初始化后自动发送 `$page_view`
+- 登录态识别仅影响后续事件
+
+## 目录
+
+```text
+fronts/sdk-web
+├── src
+├── examples
+├── tests
+└── package.json
+```
+
+## 开发命令
+
+```bash
+cd fronts/sdk-web
+bun test
+npx -p typescript tsc --noEmit -p tsconfig.json
+bun run build
+```
+
+Vue 示例：
+
+```bash
+cd fronts/sdk-web/examples/vue
+npm install
+npm run dev
+```
+
+## 输出产物
+
+- `dist/index.js`: ESM 构建产物
+- `dist/index.global.js`: 浏览器全局 bundle，暴露 `window.TrackingAnalyticsSDK`
+- `dist/index.d.ts`: ESM 入口类型声明
+
+## 初始化示例
+
+```ts
+import { init } from "rsclick-log-sdk-web";
+
+await init({
+    writeKey: "trk_live_xxx",
+    endpoint: "https://your-api.example.com/track/collect",
+});
+```
+
+关闭默认 `$page_view`：
+
+```ts
+import { init } from "rsclick-log-sdk-web";
+
+await init({
+    writeKey: "trk_live_xxx",
+    endpoint: "https://your-api.example.com/track/collect",
+    autoPageview: false,
+});
+```
+
+## 事件示例
+
+```ts
+import { track } from "rsclick-log-sdk-web";
+
+await track("click_signup_button", {
+    properties: {
+        button_name: "立即注册",
+        page_section: "hero",
+    },
+});
+```
+
+主动发送页面浏览事件：
+
+```ts
+import { page } from "rsclick-log-sdk-web";
+
+await page({
+    properties: {
+        from: "manual-refresh",
+    },
+});
+```
+
+## Identify 示例
+
+```ts
+import { identify, track } from "rsclick-log-sdk-web";
+
+identify("user_123");
+
+await track("submit_signup_form", {
+    properties: {
+        plan_type: "pro",
+    },
+});
+```
+
+`identify` 只影响后续事件，不会回溯历史匿名事件。
+
+## 浏览器直接接入
+
+```html
+<script src="/sdk/index.global.js"></script>
+<script>
+    TrackingAnalyticsSDK.init({
+        writeKey: "trk_live_xxx",
+        endpoint: "https://your-api.example.com/track/collect"
+    }).then(function () {
+        return TrackingAnalyticsSDK.track("landing_cta_click", {
+            properties: {
+                section: "hero"
+            }
+        });
+    });
+</script>
+```
+
+## 采集字段
+
+SDK 默认上报以下字段：
+
+- `anonymous_id`
+- `session_id`
+- `user_id`
+- `page_url`
+- `page_path`
+- `page_title`
+- `referrer`
+- `utm_source`
+- `utm_medium`
+- `utm_campaign`
+- `properties`
+
+传输策略：
+
+1. 优先调用 `navigator.sendBeacon`
+2. 如果 `sendBeacon` 返回 `false` 或抛错，则回退到 `fetch(..., { keepalive: true })`
+
+## 发布说明
+
+当前 npm 包名为 `rsclick-log-sdk-web`。如果要发布到 npm，按下面步骤操作：
+
+1. 进入 SDK 目录并执行发布前检查。
+
+```bash
+cd fronts/sdk-web
+bun test
+bun run build
+npx -p typescript tsc --noEmit -p tsconfig.json
+npm pack --dry-run
+```
+
+2. 登录 npm 并发布：
+
+```bash
+npm login
+npm publish --access public
+```
+
+如果本机 `~/.npmrc` 残留旧 token，优先清理后再登录，否则 `npm publish` 可能不会使用当前登录态。
+
+当前包通过 `files` 字段控制发布内容，默认只会带上：
+
+- `dist`
+- `README.md`
+
+如果只想内部使用，不需要发布到 npm，可以直接分发构建产物：
+
+- `dist/index.js`
+- `dist/index.global.js`
+- `dist/index.d.ts`

package/dist/browser.d.ts

@@ -0,0 +1,9 @@
+declare const TrackingAnalyticsSDK: {
+    init: (options: import("./types").TrackingInitOptions) => Promise<void>;
+    track: (eventName: string, options?: import("./types").TrackOptions) => Promise<import("./types").TrackingDispatchResult>;
+    identify: (userId: string | null) => void;
+    page: (options?: import("./types").PageOptions) => Promise<import("./types").TrackingDispatchResult>;
+    reset: () => import("./types").TrackingStateSnapshot;
+    getDebugState: () => import("./types").TrackingStateSnapshot;
+};
+export { TrackingAnalyticsSDK };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { getDebugState, identify, init, page, reset, track } from "./sdk";
+export type { PageOptions, TrackOptions, TrackingCollectPayload, TrackingDispatchResult, TrackingEventPayload, TrackingInitOptions, TrackingProperties, TrackingResponse, TrackingScalar, TrackingStateSnapshot, } from "./types";

package/dist/index.global.js

@@ -0,0 +1,359 @@
+(() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __moduleCache = /* @__PURE__ */ new WeakMap;
+  var __toCommonJS = (from) => {
+    var entry = __moduleCache.get(from), desc;
+    if (entry)
+      return entry;
+    entry = __defProp({}, "__esModule", { value: true });
+    if (from && typeof from === "object" || typeof from === "function")
+      __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+        get: () => from[key],
+        enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+      }));
+    __moduleCache.set(from, entry);
+    return entry;
+  };
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, {
+        get: all[name],
+        enumerable: true,
+        configurable: true,
+        set: (newValue) => all[name] = () => newValue
+      });
+  };
+
+  // src/browser.ts
+  var exports_browser = {};
+  __export(exports_browser, {
+    TrackingAnalyticsSDK: () => TrackingAnalyticsSDK
+  });
+
+  // src/sdk.ts
+  var DEFAULT_ENDPOINT = "/track/collect";
+  var DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+  var DEFAULT_STORAGE_PREFIX = "rs_tracking_sdk";
+  var STORAGE_KEYS = {
+    anonymousId: "anonymous_id",
+    sessionId: "session_id",
+    lastActivityAt: "last_activity_at",
+    userId: "user_id"
+  };
+  var trackingClient = null;
+  var init = async (options) => {
+    trackingClient = createTrackingClient(options);
+    await trackingClient.init();
+  };
+  var track = async (eventName, options = {}) => getClient().track(eventName, options);
+  var identify = (userId) => {
+    getClient().identify(userId);
+  };
+  var page = async (options = {}) => getClient().page(options);
+  var reset = () => getClient().reset();
+  var getDebugState = () => getClient().getState();
+  var createTrackingClient = (options) => {
+    const browser = resolveBrowser();
+    const config = normalizeConfig(options);
+    const storage = createScopedStorage(browser, config.storagePrefix);
+    let state = loadState(browser, storage);
+    const touchSession = (now) => {
+      const timeoutExceeded = now - state.lastActivityAt >= config.sessionTimeoutMs / 1000;
+      if (timeoutExceeded) {
+        state = {
+          ...state,
+          sessionId: generateId(browser)
+        };
+      }
+      state = {
+        ...state,
+        lastActivityAt: now
+      };
+      persistState(storage, state);
+      return state;
+    };
+    const buildEventPayload = (eventName, options2 = {}) => {
+      const now = currentUnixTime(browser);
+      const nextState = touchSession(now);
+      const pageContext = resolvePageContext(browser, options2.page);
+      const utm = extractUtm(pageContext.url);
+      return {
+        event_name: eventName.trim(),
+        event_time: options2.eventTime,
+        anonymous_id: nextState.anonymousId,
+        session_id: nextState.sessionId,
+        user_id: nextState.userId ?? undefined,
+        page_url: pageContext.url,
+        page_path: pageContext.path,
+        page_title: pageContext.title,
+        referrer: pageContext.referrer,
+        utm_source: utm.utm_source,
+        utm_medium: utm.utm_medium,
+        utm_campaign: utm.utm_campaign,
+        properties: sanitizeProperties(options2.properties)
+      };
+    };
+    const dispatch = async (payload) => {
+      const body = JSON.stringify(payload);
+      if (canUseBeacon(browser)) {
+        try {
+          const blob = createJsonBlob(browser, body);
+          const sent = browser.navigator?.sendBeacon?.(config.endpoint, blob);
+          if (sent) {
+            return { transport: "beacon" };
+          }
+        } catch {
+        }
+      }
+      const response = await postWithFetch(browser, config.endpoint, body);
+      return {
+        transport: "fetch",
+        response
+      };
+    };
+    return {
+      init: async () => {
+        if (config.autoPageview) {
+          await dispatch({
+            write_key: config.writeKey,
+            events: [buildEventPayload("$page_view")]
+          });
+        }
+      },
+      track: async (eventName, options2 = {}) => {
+        const payload = {
+          write_key: config.writeKey,
+          events: [buildEventPayload(eventName, options2)]
+        };
+        return dispatch(payload);
+      },
+      identify: (userId) => {
+        state = {
+          ...state,
+          userId: normalizeOptionalString(userId)
+        };
+        persistState(storage, state);
+      },
+      page: async (options2 = {}) => dispatch({
+        write_key: config.writeKey,
+        events: [
+          buildEventPayload("$page_view", {
+            properties: options2.properties,
+            page: options2
+          })
+        ]
+      }),
+      reset: () => {
+        clearState(storage);
+        state = createFreshState(browser);
+        persistState(storage, state);
+        return { ...state };
+      },
+      getState: () => ({ ...state })
+    };
+  };
+  var getClient = () => {
+    if (!trackingClient) {
+      throw new Error("Tracking SDK has not been initialized");
+    }
+    return trackingClient;
+  };
+  var resolveBrowser = () => {
+    const candidate = globalThis;
+    return {
+      document: candidate.document,
+      location: candidate.location,
+      navigator: candidate.navigator,
+      screen: candidate.screen,
+      localStorage: candidate.localStorage,
+      fetch: candidate.fetch?.bind(globalThis),
+      crypto: candidate.crypto,
+      Blob: candidate.Blob,
+      Date
+    };
+  };
+  var normalizeConfig = (options) => {
+    const writeKey = options.writeKey.trim();
+    if (!writeKey) {
+      throw new Error("Tracking writeKey is required");
+    }
+    return {
+      writeKey,
+      endpoint: normalizeOptionalString(options.endpoint) ?? DEFAULT_ENDPOINT,
+      autoPageview: options.autoPageview ?? true,
+      sessionTimeoutMs: Math.max(options.sessionTimeoutMinutes ?? DEFAULT_SESSION_TIMEOUT_MINUTES, 1) * 60000,
+      storagePrefix: normalizeOptionalString(options.storagePrefix) ?? DEFAULT_STORAGE_PREFIX
+    };
+  };
+  var createScopedStorage = (browser, prefix) => {
+    const nativeStorage = browser.localStorage;
+    if (!nativeStorage) {
+      const memoryStore = new Map;
+      return {
+        getItem: (key) => memoryStore.get(key) ?? null,
+        setItem: (key, value) => {
+          memoryStore.set(key, value);
+        },
+        removeItem: (key) => {
+          memoryStore.delete(key);
+        }
+      };
+    }
+    return {
+      getItem: (key) => nativeStorage.getItem(`${prefix}:${key}`),
+      setItem: (key, value) => {
+        nativeStorage.setItem(`${prefix}:${key}`, value);
+      },
+      removeItem: (key) => {
+        nativeStorage.removeItem(`${prefix}:${key}`);
+      }
+    };
+  };
+  var loadState = (browser, storage) => {
+    const anonymousId = normalizeOptionalString(storage.getItem(STORAGE_KEYS.anonymousId));
+    const sessionId = normalizeOptionalString(storage.getItem(STORAGE_KEYS.sessionId));
+    const userId = normalizeOptionalString(storage.getItem(STORAGE_KEYS.userId));
+    const lastActivityAt = parseInteger(storage.getItem(STORAGE_KEYS.lastActivityAt));
+    if (anonymousId && sessionId && lastActivityAt) {
+      return {
+        anonymousId,
+        sessionId,
+        userId,
+        lastActivityAt
+      };
+    }
+    const freshState = createFreshState(browser);
+    persistState(storage, freshState);
+    return freshState;
+  };
+  var createFreshState = (browser) => {
+    const now = currentUnixTime(browser);
+    return {
+      anonymousId: generateId(browser),
+      sessionId: generateId(browser),
+      userId: null,
+      lastActivityAt: now
+    };
+  };
+  var persistState = (storage, state) => {
+    storage.setItem(STORAGE_KEYS.anonymousId, state.anonymousId);
+    storage.setItem(STORAGE_KEYS.sessionId, state.sessionId);
+    storage.setItem(STORAGE_KEYS.lastActivityAt, String(state.lastActivityAt));
+    if (state.userId) {
+      storage.setItem(STORAGE_KEYS.userId, state.userId);
+      return;
+    }
+    storage.removeItem(STORAGE_KEYS.userId);
+  };
+  var clearState = (storage) => {
+    storage.removeItem(STORAGE_KEYS.anonymousId);
+    storage.removeItem(STORAGE_KEYS.sessionId);
+    storage.removeItem(STORAGE_KEYS.lastActivityAt);
+    storage.removeItem(STORAGE_KEYS.userId);
+  };
+  var currentUnixTime = (browser) => Math.floor((browser.Date ?? Date).now() / 1000);
+  var generateId = (browser) => {
+    if (browser.crypto?.randomUUID) {
+      return browser.crypto.randomUUID();
+    }
+    const bytes = new Uint8Array(16);
+    if (browser.crypto?.getRandomValues) {
+      browser.crypto.getRandomValues(bytes);
+    } else {
+      for (let index = 0;index < bytes.length; index += 1) {
+        bytes[index] = Math.floor(Math.random() * 256);
+      }
+    }
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  };
+  var resolvePageContext = (browser, page2 = {}) => ({
+    url: normalizeOptionalString(page2.url) ?? undefinedIfNull(normalizeOptionalString(browser.location?.href)),
+    path: normalizeOptionalString(page2.path) ?? undefinedIfNull(normalizeOptionalString(browser.location?.pathname)),
+    title: normalizeOptionalString(page2.title) ?? undefinedIfNull(normalizeOptionalString(browser.document?.title)),
+    referrer: normalizeOptionalString(page2.referrer) ?? undefinedIfNull(normalizeOptionalString(browser.document?.referrer))
+  });
+  var extractUtm = (url) => {
+    if (!url) {
+      return {};
+    }
+    try {
+      const parsed = new URL(url, "https://sdk.local");
+      return {
+        utm_source: undefinedIfNull(normalizeOptionalString(parsed.searchParams.get("utm_source"))),
+        utm_medium: undefinedIfNull(normalizeOptionalString(parsed.searchParams.get("utm_medium"))),
+        utm_campaign: undefinedIfNull(normalizeOptionalString(parsed.searchParams.get("utm_campaign")))
+      };
+    } catch {
+      return {};
+    }
+  };
+  var sanitizeProperties = (properties) => {
+    if (!properties) {
+      return {};
+    }
+    return Object.entries(properties).reduce((accumulator, [key, value]) => {
+      const normalizedKey = key.trim();
+      if (!normalizedKey) {
+        return accumulator;
+      }
+      if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+        accumulator[normalizedKey] = value;
+      }
+      return accumulator;
+    }, {});
+  };
+  var normalizeOptionalString = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+  };
+  var undefinedIfNull = (value) => value ?? undefined;
+  var parseInteger = (value) => {
+    if (!value) {
+      return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  };
+  var canUseBeacon = (browser) => typeof browser.navigator?.sendBeacon === "function";
+  var createJsonBlob = (browser, body) => {
+    if (browser.Blob) {
+      return new browser.Blob([body], { type: "application/json" });
+    }
+    return body;
+  };
+  var postWithFetch = async (browser, endpoint, body) => {
+    if (!browser.fetch) {
+      throw new Error("Tracking SDK requires fetch when sendBeacon is unavailable");
+    }
+    const response = await browser.fetch(endpoint, {
+      method: "POST",
+      keepalive: true,
+      headers: {
+        "content-type": "application/json"
+      },
+      body
+    });
+    if (!response.ok) {
+      throw new Error(`Tracking collect request failed with status ${response.status}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/json")) {
+      return;
+    }
+    return await response.json();
+  };
+  // src/browser.ts
+  var TrackingAnalyticsSDK = {
+    init,
+    track,
+    identify,
+    page,
+    reset,
+    getDebugState
+  };
+  var browserGlobal = globalThis;
+  browserGlobal.TrackingAnalyticsSDK = TrackingAnalyticsSDK;
+})();

package/dist/index.js

@@ -0,0 +1,320 @@
+// src/sdk.ts
+var DEFAULT_ENDPOINT = "/track/collect";
+var DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+var DEFAULT_STORAGE_PREFIX = "rs_tracking_sdk";
+var STORAGE_KEYS = {
+  anonymousId: "anonymous_id",
+  sessionId: "session_id",
+  lastActivityAt: "last_activity_at",
+  userId: "user_id"
+};
+var trackingClient = null;
+var init = async (options) => {
+  trackingClient = createTrackingClient(options);
+  await trackingClient.init();
+};
+var track = async (eventName, options = {}) => getClient().track(eventName, options);
+var identify = (userId) => {
+  getClient().identify(userId);
+};
+var page = async (options = {}) => getClient().page(options);
+var reset = () => getClient().reset();
+var getDebugState = () => getClient().getState();
+var createTrackingClient = (options) => {
+  const browser = resolveBrowser();
+  const config = normalizeConfig(options);
+  const storage = createScopedStorage(browser, config.storagePrefix);
+  let state = loadState(browser, storage);
+  const touchSession = (now) => {
+    const timeoutExceeded = now - state.lastActivityAt >= config.sessionTimeoutMs / 1000;
+    if (timeoutExceeded) {
+      state = {
+        ...state,
+        sessionId: generateId(browser)
+      };
+    }
+    state = {
+      ...state,
+      lastActivityAt: now
+    };
+    persistState(storage, state);
+    return state;
+  };
+  const buildEventPayload = (eventName, options2 = {}) => {
+    const now = currentUnixTime(browser);
+    const nextState = touchSession(now);
+    const pageContext = resolvePageContext(browser, options2.page);
+    const utm = extractUtm(pageContext.url);
+    return {
+      event_name: eventName.trim(),
+      event_time: options2.eventTime,
+      anonymous_id: nextState.anonymousId,
+      session_id: nextState.sessionId,
+      user_id: nextState.userId ?? undefined,
+      page_url: pageContext.url,
+      page_path: pageContext.path,
+      page_title: pageContext.title,
+      referrer: pageContext.referrer,
+      utm_source: utm.utm_source,
+      utm_medium: utm.utm_medium,
+      utm_campaign: utm.utm_campaign,
+      properties: sanitizeProperties(options2.properties)
+    };
+  };
+  const dispatch = async (payload) => {
+    const body = JSON.stringify(payload);
+    if (canUseBeacon(browser)) {
+      try {
+        const blob = createJsonBlob(browser, body);
+        const sent = browser.navigator?.sendBeacon?.(config.endpoint, blob);
+        if (sent) {
+          return { transport: "beacon" };
+        }
+      } catch {
+      }
+    }
+    const response = await postWithFetch(browser, config.endpoint, body);
+    return {
+      transport: "fetch",
+      response
+    };
+  };
+  return {
+    init: async () => {
+      if (config.autoPageview) {
+        await dispatch({
+          write_key: config.writeKey,
+          events: [buildEventPayload("$page_view")]
+        });
+      }
+    },
+    track: async (eventName, options2 = {}) => {
+      const payload = {
+        write_key: config.writeKey,
+        events: [buildEventPayload(eventName, options2)]
+      };
+      return dispatch(payload);
+    },
+    identify: (userId) => {
+      state = {
+        ...state,
+        userId: normalizeOptionalString(userId)
+      };
+      persistState(storage, state);
+    },
+    page: async (options2 = {}) => dispatch({
+      write_key: config.writeKey,
+      events: [
+        buildEventPayload("$page_view", {
+          properties: options2.properties,
+          page: options2
+        })
+      ]
+    }),
+    reset: () => {
+      clearState(storage);
+      state = createFreshState(browser);
+      persistState(storage, state);
+      return { ...state };
+    },
+    getState: () => ({ ...state })
+  };
+};
+var getClient = () => {
+  if (!trackingClient) {
+    throw new Error("Tracking SDK has not been initialized");
+  }
+  return trackingClient;
+};
+var resolveBrowser = () => {
+  const candidate = globalThis;
+  return {
+    document: candidate.document,
+    location: candidate.location,
+    navigator: candidate.navigator,
+    screen: candidate.screen,
+    localStorage: candidate.localStorage,
+    fetch: candidate.fetch?.bind(globalThis),
+    crypto: candidate.crypto,
+    Blob: candidate.Blob,
+    Date
+  };
+};
+var normalizeConfig = (options) => {
+  const writeKey = options.writeKey.trim();
+  if (!writeKey) {
+    throw new Error("Tracking writeKey is required");
+  }
+  return {
+    writeKey,
+    endpoint: normalizeOptionalString(options.endpoint) ?? DEFAULT_ENDPOINT,
+    autoPageview: options.autoPageview ?? true,
+    sessionTimeoutMs: Math.max(options.sessionTimeoutMinutes ?? DEFAULT_SESSION_TIMEOUT_MINUTES, 1) * 60000,
+    storagePrefix: normalizeOptionalString(options.storagePrefix) ?? DEFAULT_STORAGE_PREFIX
+  };
+};
+var createScopedStorage = (browser, prefix) => {
+  const nativeStorage = browser.localStorage;
+  if (!nativeStorage) {
+    const memoryStore = new Map;
+    return {
+      getItem: (key) => memoryStore.get(key) ?? null,
+      setItem: (key, value) => {
+        memoryStore.set(key, value);
+      },
+      removeItem: (key) => {
+        memoryStore.delete(key);
+      }
+    };
+  }
+  return {
+    getItem: (key) => nativeStorage.getItem(`${prefix}:${key}`),
+    setItem: (key, value) => {
+      nativeStorage.setItem(`${prefix}:${key}`, value);
+    },
+    removeItem: (key) => {
+      nativeStorage.removeItem(`${prefix}:${key}`);
+    }
+  };
+};
+var loadState = (browser, storage) => {
+  const anonymousId = normalizeOptionalString(storage.getItem(STORAGE_KEYS.anonymousId));
+  const sessionId = normalizeOptionalString(storage.getItem(STORAGE_KEYS.sessionId));
+  const userId = normalizeOptionalString(storage.getItem(STORAGE_KEYS.userId));
+  const lastActivityAt = parseInteger(storage.getItem(STORAGE_KEYS.lastActivityAt));
+  if (anonymousId && sessionId && lastActivityAt) {
+    return {
+      anonymousId,
+      sessionId,
+      userId,
+      lastActivityAt
+    };
+  }
+  const freshState = createFreshState(browser);
+  persistState(storage, freshState);
+  return freshState;
+};
+var createFreshState = (browser) => {
+  const now = currentUnixTime(browser);
+  return {
+    anonymousId: generateId(browser),
+    sessionId: generateId(browser),
+    userId: null,
+    lastActivityAt: now
+  };
+};
+var persistState = (storage, state) => {
+  storage.setItem(STORAGE_KEYS.anonymousId, state.anonymousId);
+  storage.setItem(STORAGE_KEYS.sessionId, state.sessionId);
+  storage.setItem(STORAGE_KEYS.lastActivityAt, String(state.lastActivityAt));
+  if (state.userId) {
+    storage.setItem(STORAGE_KEYS.userId, state.userId);
+    return;
+  }
+  storage.removeItem(STORAGE_KEYS.userId);
+};
+var clearState = (storage) => {
+  storage.removeItem(STORAGE_KEYS.anonymousId);
+  storage.removeItem(STORAGE_KEYS.sessionId);
+  storage.removeItem(STORAGE_KEYS.lastActivityAt);
+  storage.removeItem(STORAGE_KEYS.userId);
+};
+var currentUnixTime = (browser) => Math.floor((browser.Date ?? Date).now() / 1000);
+var generateId = (browser) => {
+  if (browser.crypto?.randomUUID) {
+    return browser.crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (browser.crypto?.getRandomValues) {
+    browser.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0;index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+var resolvePageContext = (browser, page2 = {}) => ({
+  url: normalizeOptionalString(page2.url) ?? undefinedIfNull(normalizeOptionalString(browser.location?.href)),
+  path: normalizeOptionalString(page2.path) ?? undefinedIfNull(normalizeOptionalString(browser.location?.pathname)),
+  title: normalizeOptionalString(page2.title) ?? undefinedIfNull(normalizeOptionalString(browser.document?.title)),
+  referrer: normalizeOptionalString(page2.referrer) ?? undefinedIfNull(normalizeOptionalString(browser.document?.referrer))
+});
+var extractUtm = (url) => {
+  if (!url) {
+    return {};
+  }
+  try {
+    const parsed = new URL(url, "https://sdk.local");
+    return {
+      utm_source: undefinedIfNull(normalizeOptionalString(parsed.searchParams.get("utm_source"))),
+      utm_medium: undefinedIfNull(normalizeOptionalString(parsed.searchParams.get("utm_medium"))),
+      utm_campaign: undefinedIfNull(normalizeOptionalString(parsed.searchParams.get("utm_campaign")))
+    };
+  } catch {
+    return {};
+  }
+};
+var sanitizeProperties = (properties) => {
+  if (!properties) {
+    return {};
+  }
+  return Object.entries(properties).reduce((accumulator, [key, value]) => {
+    const normalizedKey = key.trim();
+    if (!normalizedKey) {
+      return accumulator;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+      accumulator[normalizedKey] = value;
+    }
+    return accumulator;
+  }, {});
+};
+var normalizeOptionalString = (value) => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+};
+var undefinedIfNull = (value) => value ?? undefined;
+var parseInteger = (value) => {
+  if (!value) {
+    return null;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+var canUseBeacon = (browser) => typeof browser.navigator?.sendBeacon === "function";
+var createJsonBlob = (browser, body) => {
+  if (browser.Blob) {
+    return new browser.Blob([body], { type: "application/json" });
+  }
+  return body;
+};
+var postWithFetch = async (browser, endpoint, body) => {
+  if (!browser.fetch) {
+    throw new Error("Tracking SDK requires fetch when sendBeacon is unavailable");
+  }
+  const response = await browser.fetch(endpoint, {
+    method: "POST",
+    keepalive: true,
+    headers: {
+      "content-type": "application/json"
+    },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(`Tracking collect request failed with status ${response.status}`);
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    return;
+  }
+  return await response.json();
+};
+export {
+  track,
+  reset,
+  page,
+  init,
+  identify,
+  getDebugState
+};

package/dist/sdk.d.ts

@@ -0,0 +1,41 @@
+import type { PageOptions, TrackOptions, TrackingDispatchResult, TrackingInitOptions, TrackingStateSnapshot } from "./types";
+/**
+ * 初始化 SDK，并按默认配置发送一次 `$page_view`。
+ *
+ * @param options - SDK 初始化配置
+ * @returns 初始化完成后的 Promise
+ */
+export declare const init: (options: TrackingInitOptions) => Promise<void>;
+/**
+ * 上报自定义事件。
+ *
+ * @param eventName - 事件名
+ * @param options - 事件上下文与业务属性
+ * @returns 返回本次上报的传输结果
+ */
+export declare const track: (eventName: string, options?: TrackOptions) => Promise<TrackingDispatchResult>;
+/**
+ * 识别当前登录用户，仅影响后续事件。
+ *
+ * @param userId - 业务系统用户标识，传 `null` 可清除当前识别结果
+ */
+export declare const identify: (userId: string | null) => void;
+/**
+ * 主动发送 `$page_view` 事件。
+ *
+ * @param options - 页面上下文与附加属性
+ * @returns 返回本次上报的传输结果
+ */
+export declare const page: (options?: PageOptions) => Promise<TrackingDispatchResult>;
+/**
+ * 清空本地身份状态并生成新的匿名访客与会话。
+ *
+ * @returns 返回重置后的身份快照
+ */
+export declare const reset: () => TrackingStateSnapshot;
+/**
+ * 仅用于调试或测试，返回当前内存态。
+ *
+ * @returns 返回 SDK 当前状态快照
+ */
+export declare const getDebugState: () => TrackingStateSnapshot;

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+export type TrackingScalar = string | number | boolean | null;
+export type TrackingProperties = Record<string, TrackingScalar>;
+export interface TrackingInitOptions {
+    writeKey: string;
+    endpoint: string;
+    autoPageview?: boolean;
+    sessionTimeoutMinutes?: number;
+    storagePrefix?: string;
+}
+export interface PageOptions {
+    path?: string;
+    url?: string;
+    title?: string;
+    referrer?: string;
+    properties?: TrackingProperties;
+}
+export interface TrackOptions {
+    eventTime?: number;
+    properties?: TrackingProperties;
+    page?: PageOptions;
+}
+export interface TrackingEventPayload {
+    event_name: string;
+    event_time?: number;
+    anonymous_id: string;
+    session_id: string;
+    user_id?: string;
+    page_url?: string;
+    page_path?: string;
+    page_title?: string;
+    referrer?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    properties: TrackingProperties;
+}
+export interface TrackingCollectPayload {
+    write_key: string;
+    events: TrackingEventPayload[];
+}
+export interface TrackingResponse {
+    request_id?: string;
+    accepted?: number;
+    rejected?: number;
+    server_time?: number;
+}
+export interface TrackingDispatchResult {
+    transport: "beacon" | "fetch";
+    response?: TrackingResponse;
+}
+export interface TrackingStateSnapshot {
+    anonymousId: string;
+    sessionId: string;
+    userId: string | null;
+    lastActivityAt: number;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "rsclick-log-sdk-web",
+    "version": "0.1.0",
+    "private": false,
+    "type": "module",
+    "description": "Lightweight Web tracking SDK for rs-click-log.",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./browser": {
+            "default": "./dist/index.global.js"
+        }
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "bun run build:esm && bun run build:browser && bun run build:types",
+        "build:esm": "bun build --outdir=./dist --format=esm --target=browser ./src/index.ts",
+        "build:browser": "bun build --outfile=./dist/index.global.js --format=iife --target=browser ./src/browser.ts",
+        "build:types": "npx -p typescript tsc -p tsconfig.build.json",
+        "test": "bun test",
+        "typecheck": "npx -p typescript tsc --noEmit -p tsconfig.json"
+    }
+}