rsclick-log-sdk-web 0.1.0 → 0.1.2

package/README.md

@@ -8,6 +8,7 @@
 - 自动维护 30 分钟 `session_id`
 - 调用后端 `POST /track/collect` 上报事件
 - 默认初始化后自动发送 `$page_view`
+- 支持 SPA 场景下的路由切换自动发送 `$page_view`
 - 登录态识别仅影响后续事件
 
 ## 目录
@@ -52,6 +53,12 @@ await init({
     writeKey: "trk_live_xxx",
     endpoint: "https://your-api.example.com/track/collect",
 });
+
+默认行为：
+
+- 初始化完成后自动发送当前页面的 `$page_view`
+- 在 SPA 中监听 `history.pushState`、`history.replaceState`、`popstate`、`hashchange`
+- 同一 URL 不会重复自动上报
 ```
 
 关闭默认 `$page_view`：
@@ -143,8 +150,9 @@ SDK 默认上报以下字段：
 
 传输策略：
 
-1. 优先调用 `navigator.sendBeacon`
-2. 如果 `sendBeacon` 返回 `false` 或抛错，则回退到 `fetch(..., { keepalive: true })`
+1. 同源 endpoint 优先调用 `navigator.sendBeacon`
+2. 跨源 endpoint 直接使用 `fetch(..., { mode: "cors", credentials: "omit", keepalive: true })`
+3. 同源 `sendBeacon` 返回 `false` 或抛错时，回退到 `fetch(..., { keepalive: true })`
 
 ## 发布说明
 

package/dist/index.global.js

@@ -33,7 +33,7 @@
     TrackingAnalyticsSDK: () => TrackingAnalyticsSDK
   });
 
-  // src/sdk.ts
+  // src/sdk-core.ts
   var DEFAULT_ENDPOINT = "/track/collect";
   var DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
   var DEFAULT_STORAGE_PREFIX = "rs_tracking_sdk";
@@ -43,128 +43,24 @@
     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
-      };
-    };
+  var normalizeConfig = (options) => {
+    const writeKey = options.writeKey.trim();
+    if (!writeKey) {
+      throw new Error("Tracking writeKey is required");
+    }
     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 })
+      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 getClient = () => {
-    if (!trackingClient) {
-      throw new Error("Tracking SDK has not been initialized");
-    }
-    return trackingClient;
-  };
   var resolveBrowser = () => {
     const candidate = globalThis;
     return {
       document: candidate.document,
+      history: candidate.history,
       location: candidate.location,
       navigator: candidate.navigator,
       screen: candidate.screen,
@@ -172,22 +68,99 @@
       fetch: candidate.fetch?.bind(globalThis),
       crypto: candidate.crypto,
       Blob: candidate.Blob,
-      Date
+      Date,
+      addEventListener: candidate.addEventListener?.bind(globalThis),
+      removeEventListener: candidate.removeEventListener?.bind(globalThis),
+      setTimeout: candidate.setTimeout?.bind(globalThis),
+      clearTimeout: candidate.clearTimeout?.bind(globalThis)
     };
   };
-  var normalizeConfig = (options) => {
-    const writeKey = options.writeKey.trim();
-    if (!writeKey) {
-      throw new Error("Tracking writeKey is required");
+  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 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;
+  };
+
+  // src/sdk-payload.ts
+  var buildTrackingEventPayload = (input) => {
+    const pageContext = resolvePageContext(input.browser, input.options?.page);
+    const utm = extractUtm(pageContext.url);
     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
+      event_name: input.eventName.trim(),
+      event_time: input.options?.eventTime,
+      anonymous_id: input.state.anonymousId,
+      session_id: input.state.sessionId,
+      user_id: input.state.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(input.options?.properties)
     };
   };
+  var resolvePageContext = (browser, page = {}) => ({
+    url: normalizeOptionalString(page.url) ?? undefinedIfNull(normalizeOptionalString(browser.location?.href)),
+    path: normalizeOptionalString(page.path) ?? undefinedIfNull(normalizeOptionalString(browser.location?.pathname)),
+    title: normalizeOptionalString(page.title) ?? undefinedIfNull(normalizeOptionalString(browser.document?.title)),
+    referrer: normalizeOptionalString(page.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;
+    }, {});
+  };
+
+  // src/sdk-state.ts
   var createScopedStorage = (browser, prefix) => {
     const nativeStorage = browser.localStorage;
     if (!nativeStorage) {
@@ -254,68 +227,25 @@
     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;
+
+  // src/sdk-transport.ts
+  var dispatchCollect = async (browser, endpoint, payload) => {
+    const body = JSON.stringify(payload);
+    if (canUseBeacon(browser)) {
+      try {
+        const blob = createJsonBlob(browser, body);
+        const sent = browser.navigator?.sendBeacon?.(endpoint, blob);
+        if (sent) {
+          return { transport: "beacon" };
+        }
+      } catch {
       }
-      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;
+    const response = await postWithFetch(browser, endpoint, body);
+    return {
+      transport: "fetch",
+      response
+    };
   };
   var canUseBeacon = (browser) => typeof browser.navigator?.sendBeacon === "function";
   var createJsonBlob = (browser, body) => {
@@ -345,6 +275,150 @@
     }
     return await response.json();
   };
+
+  // src/sdk-client.ts
+  var createTrackingClient = (options) => {
+    const browser = resolveBrowser();
+    const config = normalizeConfig(options);
+    const storage = createScopedStorage(browser, config.storagePrefix);
+    let state = loadState(browser, storage);
+    let routeListenerCleanup = null;
+    const routeRuntime = {
+      timer: null,
+      lastAutoPageUrl: normalizeOptionalString(browser.location?.href)
+    };
+    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 createCollectPayload = (eventName, options2 = {}) => {
+      const nextState = touchSession(currentUnixTime(browser));
+      return {
+        write_key: config.writeKey,
+        events: [
+          buildTrackingEventPayload({
+            browser,
+            state: nextState,
+            eventName,
+            options: options2
+          })
+        ]
+      };
+    };
+    const autoTrackCurrentPage = async () => {
+      const currentUrl = normalizeOptionalString(browser.location?.href);
+      if (!currentUrl || currentUrl === routeRuntime.lastAutoPageUrl) {
+        return null;
+      }
+      routeRuntime.lastAutoPageUrl = currentUrl;
+      return dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
+    };
+    const installRouteListeners = () => {
+      const addEventListener = browser.addEventListener?.bind(globalThis);
+      const removeEventListener = browser.removeEventListener?.bind(globalThis);
+      const pushState = browser.history?.pushState;
+      const replaceState = browser.history?.replaceState;
+      if (!addEventListener || !removeEventListener || !pushState || !replaceState) {
+        return null;
+      }
+      const scheduleRouteTracking = () => {
+        if (routeRuntime.timer) {
+          const clearTimeoutFn = browser.clearTimeout ?? clearTimeout;
+          clearTimeoutFn(routeRuntime.timer);
+        }
+        const setTimeoutFn = browser.setTimeout ?? setTimeout;
+        routeRuntime.timer = setTimeoutFn(() => {
+          routeRuntime.timer = null;
+          autoTrackCurrentPage();
+        }, 0);
+      };
+      const patchHistoryMethod = (method) => (...args) => {
+        const result = method.apply(browser.history, args);
+        scheduleRouteTracking();
+        return result;
+      };
+      browser.history.pushState = patchHistoryMethod(pushState);
+      browser.history.replaceState = patchHistoryMethod(replaceState);
+      addEventListener("popstate", scheduleRouteTracking);
+      addEventListener("hashchange", scheduleRouteTracking);
+      return () => {
+        browser.history.pushState = pushState;
+        browser.history.replaceState = replaceState;
+        removeEventListener("popstate", scheduleRouteTracking);
+        removeEventListener("hashchange", scheduleRouteTracking);
+        if (routeRuntime.timer) {
+          const clearTimeoutFn = browser.clearTimeout ?? clearTimeout;
+          clearTimeoutFn(routeRuntime.timer);
+          routeRuntime.timer = null;
+        }
+      };
+    };
+    return {
+      init: async () => {
+        if (!config.autoPageview) {
+          return;
+        }
+        await dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
+        routeRuntime.lastAutoPageUrl = normalizeOptionalString(browser.location?.href);
+        routeListenerCleanup = installRouteListeners();
+      },
+      track: async (eventName, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(eventName, options2)),
+      identify: (userId) => {
+        state = {
+          ...state,
+          userId: normalizeOptionalString(userId)
+        };
+        persistState(storage, state);
+      },
+      page: async (options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view", {
+        properties: options2.properties,
+        page: options2
+      })),
+      reset: () => {
+        clearState(storage);
+        state = createFreshState(browser);
+        persistState(storage, state);
+        return { ...state };
+      },
+      getState: () => ({ ...state }),
+      destroy: () => {
+        routeListenerCleanup?.();
+        routeListenerCleanup = null;
+      }
+    };
+  };
+
+  // src/sdk.ts
+  var trackingClient = null;
+  var init = async (options) => {
+    trackingClient?.destroy();
+    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 getClient = () => {
+    if (!trackingClient) {
+      throw new Error("Tracking SDK has not been initialized");
+    }
+    return trackingClient;
+  };
   // src/browser.ts
   var TrackingAnalyticsSDK = {
     init,

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/sdk.ts
+// src/sdk-core.ts
 var DEFAULT_ENDPOINT = "/track/collect";
 var DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
 var DEFAULT_STORAGE_PREFIX = "rs_tracking_sdk";
@@ -8,128 +8,24 @@ var STORAGE_KEYS = {
   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
-    };
-  };
+var normalizeConfig = (options) => {
+  const writeKey = options.writeKey.trim();
+  if (!writeKey) {
+    throw new Error("Tracking writeKey is required");
+  }
   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 })
+    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 getClient = () => {
-  if (!trackingClient) {
-    throw new Error("Tracking SDK has not been initialized");
-  }
-  return trackingClient;
-};
 var resolveBrowser = () => {
   const candidate = globalThis;
   return {
     document: candidate.document,
+    history: candidate.history,
     location: candidate.location,
     navigator: candidate.navigator,
     screen: candidate.screen,
@@ -137,22 +33,99 @@ var resolveBrowser = () => {
     fetch: candidate.fetch?.bind(globalThis),
     crypto: candidate.crypto,
     Blob: candidate.Blob,
-    Date
+    Date,
+    addEventListener: candidate.addEventListener?.bind(globalThis),
+    removeEventListener: candidate.removeEventListener?.bind(globalThis),
+    setTimeout: candidate.setTimeout?.bind(globalThis),
+    clearTimeout: candidate.clearTimeout?.bind(globalThis)
   };
 };
-var normalizeConfig = (options) => {
-  const writeKey = options.writeKey.trim();
-  if (!writeKey) {
-    throw new Error("Tracking writeKey is required");
+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 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;
+};
+
+// src/sdk-payload.ts
+var buildTrackingEventPayload = (input) => {
+  const pageContext = resolvePageContext(input.browser, input.options?.page);
+  const utm = extractUtm(pageContext.url);
   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
+    event_name: input.eventName.trim(),
+    event_time: input.options?.eventTime,
+    anonymous_id: input.state.anonymousId,
+    session_id: input.state.sessionId,
+    user_id: input.state.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(input.options?.properties)
   };
 };
+var resolvePageContext = (browser, page = {}) => ({
+  url: normalizeOptionalString(page.url) ?? undefinedIfNull(normalizeOptionalString(browser.location?.href)),
+  path: normalizeOptionalString(page.path) ?? undefinedIfNull(normalizeOptionalString(browser.location?.pathname)),
+  title: normalizeOptionalString(page.title) ?? undefinedIfNull(normalizeOptionalString(browser.document?.title)),
+  referrer: normalizeOptionalString(page.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;
+  }, {});
+};
+
+// src/sdk-state.ts
 var createScopedStorage = (browser, prefix) => {
   const nativeStorage = browser.localStorage;
   if (!nativeStorage) {
@@ -219,68 +192,25 @@ var clearState = (storage) => {
   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;
+
+// src/sdk-transport.ts
+var dispatchCollect = async (browser, endpoint, payload) => {
+  const body = JSON.stringify(payload);
+  if (canUseBeacon(browser)) {
+    try {
+      const blob = createJsonBlob(browser, body);
+      const sent = browser.navigator?.sendBeacon?.(endpoint, blob);
+      if (sent) {
+        return { transport: "beacon" };
+      }
+    } catch {
     }
-    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;
+  const response = await postWithFetch(browser, endpoint, body);
+  return {
+    transport: "fetch",
+    response
+  };
 };
 var canUseBeacon = (browser) => typeof browser.navigator?.sendBeacon === "function";
 var createJsonBlob = (browser, body) => {
@@ -310,6 +240,150 @@ var postWithFetch = async (browser, endpoint, body) => {
   }
   return await response.json();
 };
+
+// src/sdk-client.ts
+var createTrackingClient = (options) => {
+  const browser = resolveBrowser();
+  const config = normalizeConfig(options);
+  const storage = createScopedStorage(browser, config.storagePrefix);
+  let state = loadState(browser, storage);
+  let routeListenerCleanup = null;
+  const routeRuntime = {
+    timer: null,
+    lastAutoPageUrl: normalizeOptionalString(browser.location?.href)
+  };
+  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 createCollectPayload = (eventName, options2 = {}) => {
+    const nextState = touchSession(currentUnixTime(browser));
+    return {
+      write_key: config.writeKey,
+      events: [
+        buildTrackingEventPayload({
+          browser,
+          state: nextState,
+          eventName,
+          options: options2
+        })
+      ]
+    };
+  };
+  const autoTrackCurrentPage = async () => {
+    const currentUrl = normalizeOptionalString(browser.location?.href);
+    if (!currentUrl || currentUrl === routeRuntime.lastAutoPageUrl) {
+      return null;
+    }
+    routeRuntime.lastAutoPageUrl = currentUrl;
+    return dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
+  };
+  const installRouteListeners = () => {
+    const addEventListener = browser.addEventListener?.bind(globalThis);
+    const removeEventListener = browser.removeEventListener?.bind(globalThis);
+    const pushState = browser.history?.pushState;
+    const replaceState = browser.history?.replaceState;
+    if (!addEventListener || !removeEventListener || !pushState || !replaceState) {
+      return null;
+    }
+    const scheduleRouteTracking = () => {
+      if (routeRuntime.timer) {
+        const clearTimeoutFn = browser.clearTimeout ?? clearTimeout;
+        clearTimeoutFn(routeRuntime.timer);
+      }
+      const setTimeoutFn = browser.setTimeout ?? setTimeout;
+      routeRuntime.timer = setTimeoutFn(() => {
+        routeRuntime.timer = null;
+        autoTrackCurrentPage();
+      }, 0);
+    };
+    const patchHistoryMethod = (method) => (...args) => {
+      const result = method.apply(browser.history, args);
+      scheduleRouteTracking();
+      return result;
+    };
+    browser.history.pushState = patchHistoryMethod(pushState);
+    browser.history.replaceState = patchHistoryMethod(replaceState);
+    addEventListener("popstate", scheduleRouteTracking);
+    addEventListener("hashchange", scheduleRouteTracking);
+    return () => {
+      browser.history.pushState = pushState;
+      browser.history.replaceState = replaceState;
+      removeEventListener("popstate", scheduleRouteTracking);
+      removeEventListener("hashchange", scheduleRouteTracking);
+      if (routeRuntime.timer) {
+        const clearTimeoutFn = browser.clearTimeout ?? clearTimeout;
+        clearTimeoutFn(routeRuntime.timer);
+        routeRuntime.timer = null;
+      }
+    };
+  };
+  return {
+    init: async () => {
+      if (!config.autoPageview) {
+        return;
+      }
+      await dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view"));
+      routeRuntime.lastAutoPageUrl = normalizeOptionalString(browser.location?.href);
+      routeListenerCleanup = installRouteListeners();
+    },
+    track: async (eventName, options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload(eventName, options2)),
+    identify: (userId) => {
+      state = {
+        ...state,
+        userId: normalizeOptionalString(userId)
+      };
+      persistState(storage, state);
+    },
+    page: async (options2 = {}) => dispatchCollect(browser, config.endpoint, createCollectPayload("$page_view", {
+      properties: options2.properties,
+      page: options2
+    })),
+    reset: () => {
+      clearState(storage);
+      state = createFreshState(browser);
+      persistState(storage, state);
+      return { ...state };
+    },
+    getState: () => ({ ...state }),
+    destroy: () => {
+      routeListenerCleanup?.();
+      routeListenerCleanup = null;
+    }
+  };
+};
+
+// src/sdk.ts
+var trackingClient = null;
+var init = async (options) => {
+  trackingClient?.destroy();
+  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 getClient = () => {
+  if (!trackingClient) {
+    throw new Error("Tracking SDK has not been initialized");
+  }
+  return trackingClient;
+};
 export {
   track,
   reset,

package/dist/sdk-client.d.ts

@@ -0,0 +1,9 @@
+import type { TrackingInitOptions } from "./types";
+import { type TrackingClient } from "./sdk-core";
+/**
+ * 创建一个完整的追踪客户端实例。
+ *
+ * @param options - 初始化参数
+ * @returns 返回可管理生命周期的客户端
+ */
+export declare const createTrackingClient: (options: TrackingInitOptions) => TrackingClient;

package/dist/sdk-core.d.ts

@@ -0,0 +1,115 @@
+import type { PageOptions, TrackOptions, TrackingDispatchResult, TrackingInitOptions, TrackingStateSnapshot } from "./types";
+export declare const DEFAULT_ENDPOINT = "/track/collect";
+export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+export declare const DEFAULT_STORAGE_PREFIX = "rs_tracking_sdk";
+export declare const STORAGE_KEYS: {
+    readonly anonymousId: "anonymous_id";
+    readonly sessionId: "session_id";
+    readonly lastActivityAt: "last_activity_at";
+    readonly userId: "user_id";
+};
+export interface BrowserLike {
+    document?: {
+        referrer?: string;
+        title?: string;
+    };
+    history?: {
+        pushState?: History["pushState"];
+        replaceState?: History["replaceState"];
+    };
+    location?: {
+        href?: string;
+        pathname?: string;
+        search?: string;
+    };
+    navigator?: {
+        language?: string;
+        sendBeacon?: (url: string, data?: BodyInit | null) => boolean;
+    };
+    screen?: {
+        width?: number;
+        height?: number;
+    };
+    localStorage?: StorageLike;
+    fetch?: typeof fetch;
+    crypto?: {
+        randomUUID?: () => string;
+        getRandomValues?: (array: Uint8Array) => Uint8Array;
+    };
+    Blob?: typeof Blob;
+    Date?: DateConstructor;
+    addEventListener?: typeof globalThis.addEventListener;
+    removeEventListener?: typeof globalThis.removeEventListener;
+    setTimeout?: typeof globalThis.setTimeout;
+    clearTimeout?: typeof globalThis.clearTimeout;
+}
+export interface StorageLike {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+export interface NormalizedConfig {
+    writeKey: string;
+    endpoint: string;
+    autoPageview: boolean;
+    sessionTimeoutMs: number;
+    storagePrefix: string;
+}
+export interface TrackingClient {
+    init: () => Promise<void>;
+    track: (eventName: string, options?: TrackOptions) => Promise<TrackingDispatchResult>;
+    identify: (userId: string | null) => void;
+    page: (options?: PageOptions) => Promise<TrackingDispatchResult>;
+    reset: () => TrackingStateSnapshot;
+    getState: () => TrackingStateSnapshot;
+    destroy: () => void;
+}
+/**
+ * 归一化初始化配置，并补齐默认值。
+ *
+ * @param options - SDK 初始化参数
+ * @returns 返回内部使用的标准配置
+ * @throws 当 writeKey 为空时抛错
+ */
+export declare const normalizeConfig: (options: TrackingInitOptions) => NormalizedConfig;
+/**
+ * 解析当前运行时的浏览器能力。
+ *
+ * @returns 返回 SDK 需要访问的浏览器能力快照
+ */
+export declare const resolveBrowser: () => BrowserLike;
+/**
+ * 返回当前 Unix 秒级时间戳。
+ *
+ * @param browser - 浏览器能力对象
+ * @returns 当前秒级时间戳
+ */
+export declare const currentUnixTime: (browser: BrowserLike) => number;
+/**
+ * 生成匿名访客或会话 ID。
+ *
+ * @param browser - 浏览器能力对象
+ * @returns 返回随机 ID
+ */
+export declare const generateId: (browser: BrowserLike) => string;
+/**
+ * 归一化可选字符串，空白视为 null。
+ *
+ * @param value - 输入字符串
+ * @returns 返回 trim 后的值或 null
+ */
+export declare const normalizeOptionalString: (value: string | null | undefined) => string | null;
+/**
+ * 将 null 映射为 undefined，便于序列化时省略字段。
+ *
+ * @param value - 任意可空值
+ * @returns 返回 undefined 或原值
+ */
+export declare const undefinedIfNull: <T>(value: T | null) => T | undefined;
+/**
+ * 解析整数文本，失败时返回 null。
+ *
+ * @param value - 待解析文本
+ * @returns 返回整数或 null
+ */
+export declare const parseInteger: (value: string | null) => number | null;

package/dist/sdk-payload.d.ts

@@ -0,0 +1,50 @@
+import type { PageOptions, TrackOptions, TrackingEventPayload, TrackingProperties, TrackingStateSnapshot } from "./types";
+import { type BrowserLike } from "./sdk-core";
+interface BuildEventPayloadOptions {
+    browser: BrowserLike;
+    state: TrackingStateSnapshot;
+    eventName: string;
+    options?: TrackOptions;
+}
+/**
+ * 构建符合后端契约的事件 payload。
+ *
+ * @param input - 事件构建参数
+ * @returns 返回标准化事件对象
+ */
+export declare const buildTrackingEventPayload: (input: BuildEventPayloadOptions) => TrackingEventPayload;
+/**
+ * 解析页面上下文字段，优先使用显式传入值。
+ *
+ * @param browser - 浏览器能力对象
+ * @param page - 页面参数
+ * @returns 返回页面上下文
+ */
+export declare const resolvePageContext: (browser: BrowserLike, page?: PageOptions) => {
+    url?: string;
+    path?: string;
+    title?: string;
+    referrer?: string;
+};
+/**
+ * 从 URL 中提取 UTM 参数。
+ *
+ * @param url - 页面 URL
+ * @returns 返回可选的 UTM 字段集合
+ */
+export declare const extractUtm: (url?: string) => Partial<Record<"utm_source" | "utm_medium" | "utm_campaign", string>>;
+/**
+ * 清洗自定义属性，仅保留后端允许的标量值。
+ *
+ * @param properties - 业务属性
+ * @returns 返回清洗后的属性对象
+ */
+export declare const sanitizeProperties: (properties?: TrackingProperties) => TrackingProperties;
+/**
+ * 计算当前事件应使用的会话活跃时间。
+ *
+ * @param browser - 浏览器能力对象
+ * @returns 返回当前秒级时间戳
+ */
+export declare const getEventTimestamp: (browser: BrowserLike) => number;
+export {};

package/dist/sdk-state.d.ts

@@ -0,0 +1,38 @@
+import type { TrackingStateSnapshot } from "./types";
+import { type BrowserLike, type StorageLike } from "./sdk-core";
+/**
+ * 创建带命名空间前缀的存储访问器；无 localStorage 时回退到内存。
+ *
+ * @param browser - 浏览器能力对象
+ * @param prefix - 存储前缀
+ * @returns 返回作用域隔离后的存储实现
+ */
+export declare const createScopedStorage: (browser: BrowserLike, prefix: string) => StorageLike;
+/**
+ * 从持久化介质恢复访客态，缺失时自动生成新状态。
+ *
+ * @param browser - 浏览器能力对象
+ * @param storage - 存储实现
+ * @returns 返回当前有效状态
+ */
+export declare const loadState: (browser: BrowserLike, storage: StorageLike) => TrackingStateSnapshot;
+/**
+ * 创建全新的匿名访客与会话状态。
+ *
+ * @param browser - 浏览器能力对象
+ * @returns 返回新的状态快照
+ */
+export declare const createFreshState: (browser: BrowserLike) => TrackingStateSnapshot;
+/**
+ * 持久化当前访客状态。
+ *
+ * @param storage - 存储实现
+ * @param state - 状态快照
+ */
+export declare const persistState: (storage: StorageLike, state: TrackingStateSnapshot) => void;
+/**
+ * 清空持久化中的访客状态。
+ *
+ * @param storage - 存储实现
+ */
+export declare const clearState: (storage: StorageLike) => void;

package/dist/sdk-transport.d.ts

@@ -0,0 +1,36 @@
+import type { TrackingCollectPayload, TrackingDispatchResult, TrackingResponse } from "./types";
+import type { BrowserLike } from "./sdk-core";
+/**
+ * 发送采集请求，优先使用 beacon，失败后回退到 fetch。
+ *
+ * @param browser - 浏览器能力对象
+ * @param endpoint - 上报地址
+ * @param payload - 请求体
+ * @returns 返回本次传输结果
+ */
+export declare const dispatchCollect: (browser: BrowserLike, endpoint: string, payload: TrackingCollectPayload) => Promise<TrackingDispatchResult>;
+/**
+ * 判断当前环境是否支持 sendBeacon。
+ *
+ * @param browser - 浏览器能力对象
+ * @returns 返回是否可用
+ */
+export declare const canUseBeacon: (browser: BrowserLike) => boolean;
+/**
+ * 创建 JSON Blob，缺失 Blob 构造器时直接返回字符串。
+ *
+ * @param browser - 浏览器能力对象
+ * @param body - JSON 字符串
+ * @returns 返回 Blob 或字符串
+ */
+export declare const createJsonBlob: (browser: BrowserLike, body: string) => Blob | string;
+/**
+ * 使用 fetch 发送采集请求，并在响应为 JSON 时返回解析结果。
+ *
+ * @param browser - 浏览器能力对象
+ * @param endpoint - 上报地址
+ * @param body - JSON 字符串
+ * @returns 返回可选响应体
+ * @throws 当当前环境不可用 fetch 或 HTTP 状态非成功时抛错
+ */
+export declare const postWithFetch: (browser: BrowserLike, endpoint: string, body: string) => Promise<TrackingResponse | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rsclick-log-sdk-web",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "private": false,
     "type": "module",
     "description": "Lightweight Web tracking SDK for rs-click-log.",
@@ -29,8 +29,8 @@
         "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",
+        "build:types": "npm exec --package=typescript tsc -- --project tsconfig.build.json",
         "test": "bun test",
         "typecheck": "npx -p typescript tsc --noEmit -p tsconfig.json"
     }
-}
+}