@lark-apaas/observable-web-lite 1.0.0

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @lark-apaas/observable-web-lite
+
+轻量 PV/UV 上报 SDK，零外部依赖，产物 ~5KB。
+
+适用于只需要 PV/UV 统计、不需要 Logs/Traces/Metrics 全量能力的项目。与 `@lark-apaas/observable-web` 后端完全兼容（相同 metric name + payload 格式），收集端点无需改动。
+
+## 安装
+
+```bash
+yarn add @lark-apaas/observable-web-lite
+```
+
+## 快速开始
+
+```typescript
+import { pvTracker } from '@lark-apaas/observable-web-lite';
+
+const appId = window.appId || '';
+pvTracker.start({
+  collectorUrl: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
+});
+```
+
+一行代码即可启用 PV/UV 自动上报，SDK 会自动监听：
+
+- 页面首次加载（`load`）
+- 浏览器前进/后退（`popstate`）
+- SPA 路由跳转（`pushState` / `replaceState`）
+- 页面切后台/关闭时立即 flush（`visibilitychange` / `pagehide`）
+
+## API
+
+### `pvTracker.start(config)`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `collectorUrl` | `string` | 是 | Metric 收集端点 URL |
+| `headers` | `Record<string, string>` | 否 | 附加 HTTP headers |
+| `flushIntervalMs` | `number` | 否 | 批量发送间隔，默认 10000ms |
+
+### `pvTracker.shutdown()`
+
+停止上报并立即 flush 剩余数据。
+
+## 完整示例
+
+### 在 React 应用入口使用
+
+```typescript
+// client/src/index.tsx
+import { pvTracker } from '@lark-apaas/observable-web-lite';
+
+const appId = window.appId || '';
+pvTracker.start({
+  collectorUrl: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
+  flushIntervalMs: 5000, // 5 秒 flush 一次
+});
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```
+
+### 自定义实例（多实例场景）
+
+```typescript
+import { PvTracker } from '@lark-apaas/observable-web-lite';
+
+const tracker = new PvTracker();
+const appId = window.appId || '';
+tracker.start({
+  collectorUrl: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
+});
+
+// 页面卸载时
+tracker.shutdown();
+```
+
+## 与 observable-web 的对比
+
+| | observable-web | observable-web-lite |
+|---|---|---|
+| 产物大小 | ~50KB | **~5KB** |
+| 外部依赖 | 9 个（OTel + zone.js） | **0** |
+| PV/UV 上报 | ✅ | ✅ |
+| 日志（Logs） | ✅ | ❌ |
+| 指标（Metrics） | ✅ | ❌ |
+| 链路追踪（Traces） | ✅ | ❌ |
+| ESM 支持 | ❌ | ✅ |
+| tree-shake | ❌ | ✅ |
+
+## 注意事项
+
+- 与 `observable-web` **不要同时启用 PV 上报**，否则会重复计数
+- 如果项目后续需要 Logs/Traces 能力，切换回 `observable-web` 即可，PV 数据无缝衔接（metric name 相同）
+- SDK 默认读取 `window.appId` / `window.tenantId` / `window.userId` 作为上报属性，这些由服务端 ViewContextPlugin 注入

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+interface PvTrackerConfig {
+    /** Metric 收集端点 URL */
+    collectorUrl: string;
+    /** 附加的 HTTP headers */
+    headers?: Record<string, string>;
+    /** 批量发送间隔（毫秒），默认 10000 */
+    flushIntervalMs?: number;
+}
+declare class PvTracker {
+    private static _instance;
+    private config;
+    private started;
+    private lastUrl;
+    private buffer;
+    private flushTimer;
+    static get instance(): PvTracker;
+    start(config: PvTrackerConfig): void;
+    shutdown(): void;
+    private recordPv;
+    private flush;
+    private listenRouteChanges;
+    private patchHistory;
+    private registerLifecycleListeners;
+}
+
+declare const pvTracker: PvTracker;
+
+export { PvTracker, type PvTrackerConfig, pvTracker };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+interface PvTrackerConfig {
+    /** Metric 收集端点 URL */
+    collectorUrl: string;
+    /** 附加的 HTTP headers */
+    headers?: Record<string, string>;
+    /** 批量发送间隔（毫秒），默认 10000 */
+    flushIntervalMs?: number;
+}
+declare class PvTracker {
+    private static _instance;
+    private config;
+    private started;
+    private lastUrl;
+    private buffer;
+    private flushTimer;
+    static get instance(): PvTracker;
+    start(config: PvTrackerConfig): void;
+    shutdown(): void;
+    private recordPv;
+    private flush;
+    private listenRouteChanges;
+    private patchHistory;
+    private registerLifecycleListeners;
+}
+
+declare const pvTracker: PvTracker;
+
+export { PvTracker, type PvTrackerConfig, pvTracker };

package/dist/index.js

@@ -0,0 +1,196 @@
+'use strict';
+
+// src/utils/uuid.ts
+function generateUUID() {
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  let result = "";
+  for (let i = 0; i < 16; i++) {
+    result += Math.floor(Math.random() * 16).toString(16);
+  }
+  return result;
+}
+
+// src/utils/device-id.ts
+var STORAGE_KEY = "x_sdk_device_id";
+function getDeviceId() {
+  try {
+    let id = localStorage.getItem(STORAGE_KEY);
+    if (!id) {
+      id = generateUUID();
+      localStorage.setItem(STORAGE_KEY, id);
+    }
+    return id;
+  } catch {
+    return generateUUID();
+  }
+}
+
+// src/utils/device-type.ts
+function getDeviceType() {
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+  if (!ua) return "desktop";
+  if (/Android/i.test(ua) && /Mobile/i.test(ua) || /iPhone|iPod/i.test(ua) || /BlackBerry|IEMobile|Opera Mini/i.test(ua)) {
+    return "mobile";
+  }
+  return "desktop";
+}
+
+// src/utils/attributes.ts
+function getDefaultAttributes() {
+  return {
+    app_id: window.appId || "",
+    tenant_id: window.tenantId || "",
+    user_id: window.userId || "",
+    did: getDeviceId(),
+    module: "app_web",
+    app_env: "runtime",
+    source_type: "user",
+    device_type: getDeviceType(),
+    release_commit_id: window.__RELEASE_COMMIT_ID__ || ""
+  };
+}
+
+// src/sender.ts
+var SDK_VERSION = "1.0.0";
+function buildPayload(dataPoints) {
+  const defaultAttrs = getDefaultAttributes();
+  const nowNs = String(BigInt(Date.now()) * BigInt(1e6));
+  return {
+    metricsData: {
+      resource: {
+        attributes: {
+          sdk_version: SDK_VERSION,
+          sdk_lang: "javascript",
+          sdk_type: "client-frontend"
+        }
+      },
+      metrics: [
+        {
+          name: "apaas_internal_metrics_pv_uv",
+          description: "Count of page views",
+          unit: "",
+          scopeName: "apaas_internal_metrics_pv_uv",
+          sum: {
+            aggregationTemporality: 1,
+            // DELTA
+            isMonotonic: true,
+            dataPoints: dataPoints.map((dp) => ({
+              attributes: {
+                ...defaultAttrs,
+                url: dp.url,
+                path: dp.path,
+                referrer: dp.referrer
+              },
+              startTimeUnixNano: String(BigInt(dp.timestampMs) * BigInt(1e6)),
+              timeUnixNano: nowNs,
+              asDouble: 1
+            }))
+          }
+        }
+      ]
+    }
+  };
+}
+function sendPvData(collectorUrl, dataPoints, headers = {}) {
+  if (dataPoints.length === 0) return;
+  const body = JSON.stringify(buildPayload(dataPoints));
+  try {
+    fetch(collectorUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Suda-Csrf-Token": window.csrfToken || "",
+        ...headers
+      },
+      body,
+      keepalive: true
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+
+// src/tracker.ts
+var PvTracker = class _PvTracker {
+  constructor() {
+    this.started = false;
+    this.buffer = [];
+  }
+  static get instance() {
+    if (!this._instance) {
+      this._instance = new _PvTracker();
+    }
+    return this._instance;
+  }
+  start(config) {
+    var _a;
+    if (this.started) return;
+    this.config = config;
+    this.started = true;
+    this.listenRouteChanges();
+    this.registerLifecycleListeners();
+    const interval = (_a = config.flushIntervalMs) != null ? _a : 1e4;
+    this.flushTimer = setInterval(() => this.flush(), interval);
+  }
+  shutdown() {
+    this.flush();
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+    this.started = false;
+  }
+  recordPv() {
+    const currentUrl = window.location.href;
+    if (this.lastUrl === currentUrl) return;
+    this.lastUrl = currentUrl;
+    this.buffer.push({
+      url: currentUrl,
+      path: window.location.pathname,
+      referrer: document.referrer,
+      timestampMs: Date.now()
+    });
+  }
+  flush() {
+    if (!this.config || this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0);
+    sendPvData(this.config.collectorUrl, batch, this.config.headers);
+  }
+  listenRouteChanges() {
+    if (document.readyState === "complete") {
+      this.recordPv();
+    } else {
+      window.addEventListener("load", () => this.recordPv());
+    }
+    window.addEventListener("popstate", () => this.recordPv());
+    this.patchHistory("pushState");
+    this.patchHistory("replaceState");
+  }
+  patchHistory(method) {
+    const original = history[method];
+    const recordPv = () => this.recordPv();
+    history[method] = function(...args) {
+      const result = original.apply(this, args);
+      recordPv();
+      return result;
+    };
+  }
+  registerLifecycleListeners() {
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        this.flush();
+      }
+    });
+    window.addEventListener("pagehide", () => this.flush());
+  }
+};
+
+// src/index.ts
+var pvTracker = PvTracker.instance;
+
+exports.PvTracker = PvTracker;
+exports.pvTracker = pvTracker;

package/dist/index.mjs

@@ -0,0 +1,193 @@
+// src/utils/uuid.ts
+function generateUUID() {
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  let result = "";
+  for (let i = 0; i < 16; i++) {
+    result += Math.floor(Math.random() * 16).toString(16);
+  }
+  return result;
+}
+
+// src/utils/device-id.ts
+var STORAGE_KEY = "x_sdk_device_id";
+function getDeviceId() {
+  try {
+    let id = localStorage.getItem(STORAGE_KEY);
+    if (!id) {
+      id = generateUUID();
+      localStorage.setItem(STORAGE_KEY, id);
+    }
+    return id;
+  } catch {
+    return generateUUID();
+  }
+}
+
+// src/utils/device-type.ts
+function getDeviceType() {
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+  if (!ua) return "desktop";
+  if (/Android/i.test(ua) && /Mobile/i.test(ua) || /iPhone|iPod/i.test(ua) || /BlackBerry|IEMobile|Opera Mini/i.test(ua)) {
+    return "mobile";
+  }
+  return "desktop";
+}
+
+// src/utils/attributes.ts
+function getDefaultAttributes() {
+  return {
+    app_id: window.appId || "",
+    tenant_id: window.tenantId || "",
+    user_id: window.userId || "",
+    did: getDeviceId(),
+    module: "app_web",
+    app_env: "runtime",
+    source_type: "user",
+    device_type: getDeviceType(),
+    release_commit_id: window.__RELEASE_COMMIT_ID__ || ""
+  };
+}
+
+// src/sender.ts
+var SDK_VERSION = "1.0.0";
+function buildPayload(dataPoints) {
+  const defaultAttrs = getDefaultAttributes();
+  const nowNs = String(BigInt(Date.now()) * BigInt(1e6));
+  return {
+    metricsData: {
+      resource: {
+        attributes: {
+          sdk_version: SDK_VERSION,
+          sdk_lang: "javascript",
+          sdk_type: "client-frontend"
+        }
+      },
+      metrics: [
+        {
+          name: "apaas_internal_metrics_pv_uv",
+          description: "Count of page views",
+          unit: "",
+          scopeName: "apaas_internal_metrics_pv_uv",
+          sum: {
+            aggregationTemporality: 1,
+            // DELTA
+            isMonotonic: true,
+            dataPoints: dataPoints.map((dp) => ({
+              attributes: {
+                ...defaultAttrs,
+                url: dp.url,
+                path: dp.path,
+                referrer: dp.referrer
+              },
+              startTimeUnixNano: String(BigInt(dp.timestampMs) * BigInt(1e6)),
+              timeUnixNano: nowNs,
+              asDouble: 1
+            }))
+          }
+        }
+      ]
+    }
+  };
+}
+function sendPvData(collectorUrl, dataPoints, headers = {}) {
+  if (dataPoints.length === 0) return;
+  const body = JSON.stringify(buildPayload(dataPoints));
+  try {
+    fetch(collectorUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Suda-Csrf-Token": window.csrfToken || "",
+        ...headers
+      },
+      body,
+      keepalive: true
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+
+// src/tracker.ts
+var PvTracker = class _PvTracker {
+  constructor() {
+    this.started = false;
+    this.buffer = [];
+  }
+  static get instance() {
+    if (!this._instance) {
+      this._instance = new _PvTracker();
+    }
+    return this._instance;
+  }
+  start(config) {
+    var _a;
+    if (this.started) return;
+    this.config = config;
+    this.started = true;
+    this.listenRouteChanges();
+    this.registerLifecycleListeners();
+    const interval = (_a = config.flushIntervalMs) != null ? _a : 1e4;
+    this.flushTimer = setInterval(() => this.flush(), interval);
+  }
+  shutdown() {
+    this.flush();
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+    this.started = false;
+  }
+  recordPv() {
+    const currentUrl = window.location.href;
+    if (this.lastUrl === currentUrl) return;
+    this.lastUrl = currentUrl;
+    this.buffer.push({
+      url: currentUrl,
+      path: window.location.pathname,
+      referrer: document.referrer,
+      timestampMs: Date.now()
+    });
+  }
+  flush() {
+    if (!this.config || this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0);
+    sendPvData(this.config.collectorUrl, batch, this.config.headers);
+  }
+  listenRouteChanges() {
+    if (document.readyState === "complete") {
+      this.recordPv();
+    } else {
+      window.addEventListener("load", () => this.recordPv());
+    }
+    window.addEventListener("popstate", () => this.recordPv());
+    this.patchHistory("pushState");
+    this.patchHistory("replaceState");
+  }
+  patchHistory(method) {
+    const original = history[method];
+    const recordPv = () => this.recordPv();
+    history[method] = function(...args) {
+      const result = original.apply(this, args);
+      recordPv();
+      return result;
+    };
+  }
+  registerLifecycleListeners() {
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        this.flush();
+      }
+    });
+    window.addEventListener("pagehide", () => this.flush());
+  }
+};
+
+// src/index.ts
+var pvTracker = PvTracker.instance;
+
+export { PvTracker, pvTracker };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@lark-apaas/observable-web-lite",
+  "version": "1.0.0",
+  "description": "Lightweight PV/UV reporting SDK - zero dependencies",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint . --quiet",
+    "test": "vitest",
+    "test:cov": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^18.17.18"
+  }
+}