ytracking-web 0.1.1

package/README.md

@@ -0,0 +1,73 @@
+# ytracking-web（瀏覽器 SDK）
+
+TypeScript 實作，對齊 [docs/SDK_DESIGN.md](../../docs/SDK_DESIGN.md)：事件先入 **IndexedDB** 佇列，背景 **flush**、**退避重試**、**多 `baseUrl` 故障轉移**；失敗時可降級為記憶體佇列（不持久）。
+
+## 建置產物（提交於 `site/public/sdk/`）
+
+| 檔案 | 說明 |
+|------|------|
+| `ytracking-web.js` | IIFE，`globalThis.YTrackingWeb` |
+| `ytracking-web.min.js` | 同上，minify |
+| `ytracking-web.mjs` | ESM `import { init, track } from '...'`（部署路徑依站點） |
+
+根目錄執行：`npm run build:web-sdk`
+## npm 套件（選用）
+
+```bash
+npm install ytracking-web
+```
+
+套件 **exports** 指向 **`src/*.ts` 原始碼**（`type: module`）；整合專案需使用可轉譯／bundle TypeScript 的工具鏈，或繼續使用倉庫建置之 **`site/public/sdk/*`** 靜態檔。發佈 registry 前請於根目錄執行 **`npm run check:web-sdk`** 與 **`npm run build:web-sdk`** 驗證。
+
+## 發佈至 npm
+
+1. 於倉庫根目錄：`npm run check:web-sdk`、（建議）`npm run build:web-sdk`。
+2. **GitHub Actions**：「Publish ytracking-web to npm」workflow（`workflow_dispatch`）。需在 repo 設定 **`NPM_TOKEN`**（npm automation access token，具 publish 權限）。
+3. **本機（免 `npm login`，適合首次發佈作法 B）**：在倉庫根目錄設定 **`NPM_TOKEN`** 後執行 **`npm run publish:ytracking-web`**（會先跑 `check:web-sdk` 再 `npm publish`）。亦可手動：`cd packages/ytracking-web && npm publish`（需已 `npm login` 或 `~/.npmrc` token）。
+
+
+## 使用（IIFE）
+
+```html
+<script src="https://你的網域/sdk/ytracking-web.js"></script>
+<script>
+  YTrackingWeb.init({
+    siteId: "站點-UUID",
+    baseUrls: ["https://你的網域"],
+    fallbackBaseUrls: [],
+    endpointListTtlSec: 300,
+    domainHealthReportMinIntervalMs: 300000,
+    debug: false,
+  });
+  YTrackingWeb.trackPageView();
+</script>
+```
+
+## API（`YTrackingWeb`）
+
+- `init(config)` — 必填 `siteId`、`baseUrls`（無尾階 `/` 之 origin）
+  - `enableVisitorFallbackFingerprint`：可選（預設 `false`），僅在無 cookie + 無 localStorage visitor 時以低熵指紋產生暫時 visitor seed
+  - `maxQueueSize`：本地 queue 容量上限（預設 `500`），超量時淘汰低優先且最舊事件
+  - `batchSize`：單次 flush 最多取件數（預設 `8`）
+  - `flushConcurrency`：單次 flush 內平行送件 worker 數（預設 `2`，最小 `1`）
+  - `endpointListTtlSec`：成功送達後重新拉取 `/v1/sdk/ingestion-hosts` 的最短間隔（秒，預設 300）
+  - `domainHealthReportMinIntervalMs`：同一 domain 不可達回報最短間隔（毫秒，預設 300000）
+- `track(type, { props })` — 對應 `POST /v1/collect` envelope
+- `trackPageView()` — `page_view`
+- `install({ clickId? })` — 內嵌 **`POST /v1/install`**（無 `appId` 之 embed 形態）
+- `flush()` — 手動送出佇列
+- `setContext({ visitorId, sessionId, clickId, campaignId, appId })` — 後續事件帶入
+- `shutdown()` — 停止定時 flush
+
+## 與後端的關係
+
+- 每筆事件在 `event.props` 附 **`_ytSdkEventId`**（支援 `crypto.randomUUID` 時為 UUID）與 **`_ytSdk: "web-v1"`**；同時在 JSON 根層帶 **`idempotencyKey`**（與該 UUID 相同），與 **`POST /v1/collect`** 去重契約對齊（見 [API.md](../../docs/API.md) §2.2）。重試／重送同一佇列項目時沿用同一 id，consumer 只會落庫一次。
+- `collect` 出站 `Idempotency-Key` 會優先使用 payload 根層 `idempotencyKey`（若缺失才回退 queue id），確保 header 與 body 同鍵。
+- collect 成功回應若包含 `visitorId`，SDK 會寫入 localStorage（`yt_vid_v1`）並自動帶入後續事件 context；可在 cookie 受限環境維持 visitor 關聯。
+- 須符合 `sites.allowed_origins`（見 [SITE_AND_EMBED.md](../../docs/SITE_AND_EMBED.md)）。
+- fallback 會維護 endpoint pool + cursor；成功入口可刷新新 hosts，不可達時會送 best-effort `domain-health/report`（含節流）。
+- `Retry-After` 同時支援秒數與 HTTP-date；`shutdown()` 會解除 `visibilitychange` listener，避免重複初始化時累積監聽器。
+
+## 型別檢查
+
+`npm run check:web-sdk`

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "ytracking-web",
+  "version": "0.1.1",
+  "description": "Browser SDK for YTracking collect/install (IndexedDB queue, retry, multi-host)",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": ["src", "README.md"],
+  "sideEffects": false,
+  "keywords": ["ytracking", "analytics", "tracking", "indexeddb"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TI-Eddie/YTracking.git",
+    "directory": "packages/ytracking-web"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,578 @@
+import {
+  backoffMs,
+  eventPriority,
+  isNonRetryableStatus,
+  isRetryableStatus,
+} from "./retry";
+import {
+  idbAdd,
+  idbCount,
+  idbDelete,
+  idbGetAll,
+  idbGetDue,
+  idbPut,
+  openOutboxDb,
+} from "./idb";
+import {
+  buildCollectEnvelope,
+  buildSoftFingerprintVisitorId,
+  readStoredVisitorId,
+  writeStoredVisitorId,
+} from "./payload";
+import { postJson } from "./transport";
+import type { InitConfig, OutboxRecord } from "./types";
+
+function log(debug: boolean | undefined, ...args: unknown[]): void {
+  if (debug) console.log("[YTrackingWeb]", ...args);
+}
+
+function normalizeOrigins(urls: string[]): string[] {
+  const out: string[] = [];
+  for (const u of urls) {
+    const t = String(u || "")
+      .trim()
+      .replace(/\/+$/, "");
+    if (t) out.push(t);
+  }
+  return out;
+}
+
+function collectUrl(origin: string): string {
+  return `${origin}/v1/collect`;
+}
+
+function installUrl(origin: string): string {
+  return `${origin}/v1/install`;
+}
+
+export class YTrackingWebClient {
+  private cfg: Required<
+    Pick<InitConfig, "siteId" | "baseUrls"> & {
+      fallbackBaseUrls: string[];
+      debug: boolean;
+      enableVisitorFallbackFingerprint: boolean;
+      maxQueueSize: number;
+      flushIntervalMs: number;
+      requestTimeoutMs: number;
+      batchSize: number;
+      flushConcurrency: number;
+      maxAttempts: number;
+      endpointListTtlSec: number;
+      domainHealthReportMinIntervalMs: number;
+    }
+  >;
+  private db: IDBDatabase | null = null;
+  private mem: OutboxRecord[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private flushing = false;
+  private originPool: string[] = [];
+  private originCursor = 0;
+  private lastEndpointListRefreshAt = 0;
+  private lastDomainHealthReportAt = new Map<string, number>();
+  private visibilityHandler: (() => void) | null = null;
+  private context: {
+    visitorId?: string;
+    sessionId?: string;
+    clickId?: string;
+    campaignId?: string;
+    appId?: string;
+  } = {};
+
+  constructor(cfg: InitConfig) {
+    const base = normalizeOrigins(cfg.baseUrls);
+    if (!cfg.siteId?.trim() || base.length === 0) {
+      throw new Error(
+        "YTrackingWeb: siteId and at least one baseUrl are required",
+      );
+    }
+    this.cfg = {
+      siteId: cfg.siteId.trim(),
+      baseUrls: base,
+      fallbackBaseUrls: normalizeOrigins(cfg.fallbackBaseUrls ?? []),
+      debug: !!cfg.debug,
+      enableVisitorFallbackFingerprint: !!cfg.enableVisitorFallbackFingerprint,
+      maxQueueSize: cfg.maxQueueSize ?? 500,
+      flushIntervalMs: cfg.flushIntervalMs ?? 3000,
+      requestTimeoutMs: cfg.requestTimeoutMs ?? 15000,
+      batchSize: cfg.batchSize ?? 8,
+      flushConcurrency: Math.max(1, cfg.flushConcurrency ?? 2),
+      maxAttempts: cfg.maxAttempts ?? 12,
+      endpointListTtlSec: cfg.endpointListTtlSec ?? 300,
+      domainHealthReportMinIntervalMs:
+        cfg.domainHealthReportMinIntervalMs ?? 300_000,
+    };
+    this.originPool = [
+      ...new Set([...this.cfg.baseUrls, ...this.cfg.fallbackBaseUrls]),
+    ];
+  }
+
+  setContext(partial: {
+    visitorId?: string;
+    sessionId?: string;
+    clickId?: string;
+    campaignId?: string;
+    appId?: string;
+  }): void {
+    this.context = { ...this.context, ...partial };
+  }
+
+  async start(): Promise<void> {
+    if (!this.context.visitorId) {
+      const storedVisitorId = readStoredVisitorId();
+      if (storedVisitorId) {
+        this.context.visitorId = storedVisitorId;
+      } else if (this.cfg.enableVisitorFallbackFingerprint) {
+        const fpVisitorId = buildSoftFingerprintVisitorId();
+        if (fpVisitorId) {
+          this.context.visitorId = fpVisitorId;
+          writeStoredVisitorId(fpVisitorId);
+        }
+      }
+    }
+    this.db = await openOutboxDb();
+    if (!this.db)
+      log(
+        this.cfg.debug,
+        "IndexedDB unavailable; using in-memory queue (not durable)",
+      );
+    if (this.timer) clearInterval(this.timer);
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.cfg.flushIntervalMs);
+    if (typeof document !== "undefined" && !this.visibilityHandler) {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "hidden") void this.flush();
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+    void this.flush();
+  }
+
+  shutdown(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (
+      typeof document !== "undefined" &&
+      this.visibilityHandler &&
+      document.removeEventListener
+    ) {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+    }
+    this.visibilityHandler = null;
+  }
+
+  async track(
+    eventType: string,
+    options?: { props?: Record<string, unknown> },
+  ): Promise<void> {
+    const props =
+      options?.props && typeof options.props === "object" ? options.props : {};
+    const envelope = buildCollectEnvelope(
+      this.cfg.siteId,
+      eventType,
+      props,
+      this.context,
+    );
+    const payload = JSON.stringify(envelope);
+    await this.enqueue({
+      kind: "collect",
+      payload,
+      eventType,
+      priority: eventPriority(eventType),
+    });
+  }
+
+  async trackPageView(): Promise<void> {
+    return this.track("page_view", {});
+  }
+
+  async install(opts?: { clickId?: string }): Promise<void> {
+    const body: Record<string, string> = { siteId: this.cfg.siteId };
+    const cid = opts?.clickId?.trim() || this.context.clickId?.trim();
+    if (cid) body.clickId = cid;
+    await this.enqueue({
+      kind: "install",
+      payload: JSON.stringify(body),
+      eventType: "install",
+      priority: 10,
+    });
+  }
+
+  private async enqueue(p: {
+    kind: OutboxRecord["kind"];
+    payload: string;
+    eventType: string;
+    priority: number;
+  }): Promise<void> {
+    const id =
+      typeof crypto !== "undefined" && crypto.randomUUID
+        ? crypto.randomUUID()
+        : `q_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const now = Date.now();
+    const rec: OutboxRecord = {
+      id,
+      kind: p.kind,
+      payload: p.payload,
+      attempts: 0,
+      nextAttemptAt: now,
+      createdAt: now,
+      priority: p.priority,
+      eventType: p.eventType,
+    };
+    await this.enforceCapacity();
+    if (this.db) {
+      const ok = await idbAdd(this.db, rec);
+      if (ok) {
+        log(this.cfg.debug, "enqueued", p.kind, id);
+        void this.flush();
+        return;
+      }
+      log(this.cfg.debug, "idb add failed; falling back to memory");
+    }
+    this.mem.push(rec);
+    log(this.cfg.debug, "enqueued (mem)", p.kind, id);
+    void this.flush();
+  }
+
+  private async enforceCapacity(): Promise<void> {
+    const persisted = this.db ? await idbCount(this.db) : 0;
+    const all = this.db ? await idbGetAll(this.db) : [];
+    const total = persisted + this.mem.length;
+    if (total < this.cfg.maxQueueSize) return;
+    const overflow = total - this.cfg.maxQueueSize + 1;
+    const sorted = [...all].sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.createdAt - b.createdAt;
+    });
+    sorted.push(...this.mem);
+    sorted.sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.createdAt - b.createdAt;
+    });
+    for (let i = 0; i < overflow && i < sorted.length; i++) {
+      await this.removeRecord(sorted[i].id);
+      log(this.cfg.debug, "dropped low-priority queue item", sorted[i].id);
+    }
+  }
+
+  private async allRecords(): Promise<OutboxRecord[]> {
+    if (this.db) {
+      const rows = await idbGetAll(this.db);
+      return rows.concat(this.mem);
+    }
+    return [...this.mem];
+  }
+
+  private async removeRecord(id: string): Promise<void> {
+    if (this.db) {
+      try {
+        await idbDelete(this.db, id);
+      } catch {
+        log(this.cfg.debug, "idbDelete failed, clearing from memory", id);
+      }
+    }
+    this.mem = this.mem.filter((r) => r.id !== id);
+  }
+
+  private async updateRecord(rec: OutboxRecord): Promise<void> {
+    if (this.db) {
+      const inMem = this.mem.some((r) => r.id === rec.id);
+      if (!inMem) {
+        try {
+          await idbPut(this.db, rec);
+        } catch {
+          log(this.cfg.debug, "idbPut failed, falling back to memory", rec.id);
+          this.mem.push(rec);
+        }
+        return;
+      }
+    }
+    const idx = this.mem.findIndex((r) => r.id === rec.id);
+    if (idx >= 0) this.mem[idx] = rec;
+  }
+
+  async flush(): Promise<void> {
+    if (this.flushing) return;
+    this.flushing = true;
+    try {
+      const now = Date.now();
+      const dbDue = this.db
+        ? await idbGetDue(this.db, now, this.cfg.batchSize * 2)
+        : [];
+      const memDue = this.mem.filter((r) => r.nextAttemptAt <= now);
+      const due = [...dbDue, ...memDue]
+        .sort((a, b) => {
+          if (b.priority !== a.priority) return b.priority - a.priority;
+          return a.nextAttemptAt - b.nextAttemptAt;
+        })
+        .slice(0, this.cfg.batchSize);
+      if (!due.length) return;
+      const workers = Math.min(this.cfg.flushConcurrency, due.length);
+      let idx = 0;
+      const runOne = async () => {
+        while (idx < due.length) {
+          const i = idx;
+          idx += 1;
+          const rec = due[i];
+          if (rec) await this.sendOne(rec);
+        }
+      };
+      await Promise.all(Array.from({ length: workers }, () => runOne()));
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  private originsInOrder(): string[] {
+    if (this.originPool.length === 0) {
+      this.originPool = [
+        ...new Set([...this.cfg.baseUrls, ...this.cfg.fallbackBaseUrls]),
+      ];
+    }
+    if (this.originPool.length <= 1) return [...this.originPool];
+    const idx =
+      ((this.originCursor % this.originPool.length) + this.originPool.length) %
+      this.originPool.length;
+    return [...this.originPool.slice(idx), ...this.originPool.slice(0, idx)];
+  }
+
+  private async sendOne(rec: OutboxRecord): Promise<void> {
+    const pathFn = rec.kind === "install" ? installUrl : collectUrl;
+    let lastRetryAfter: number | undefined;
+
+    for (const origin of this.originsInOrder()) {
+      const url = pathFn(origin);
+      const idempotencyForRequest =
+        rec.kind === "collect"
+          ? (this.collectIdempotencyKey(rec.payload) ?? rec.id)
+          : rec.id;
+      const res = await postJson(
+        url,
+        rec.payload,
+        this.cfg.requestTimeoutMs,
+        idempotencyForRequest,
+      );
+      if (!res.ok) {
+        log(this.cfg.debug, "post transport fail", rec.id, origin, res.kind);
+        if (res.retryAfterMs !== undefined) lastRetryAfter = res.retryAfterMs;
+        if (res.kind === "network" || res.kind === "timeout") {
+          await this.reportDomainUnreachable(origin, res.kind);
+          this.rotateCursorAfter(origin);
+        }
+        continue;
+      }
+      if (res.retryAfterMs !== undefined) lastRetryAfter = res.retryAfterMs;
+
+      if (res.status >= 200 && res.status < 300) {
+        if (rec.kind === "collect") {
+          this.captureVisitorFromCollectAck(res.bodyJson);
+        }
+        this.setCursorToOrigin(origin);
+        await this.refreshEndpointPool(origin);
+        await this.removeRecord(rec.id);
+        log(this.cfg.debug, "sent", rec.id, res.status, origin);
+        return;
+      }
+      if (isNonRetryableStatus(res.status)) {
+        log(this.cfg.debug, "drop non-retryable", rec.id, res.status);
+        await this.removeRecord(rec.id);
+        return;
+      }
+      if (isRetryableStatus(res.status)) {
+        log(
+          this.cfg.debug,
+          "retryable http, try next origin",
+          rec.id,
+          res.status,
+          origin,
+        );
+        continue;
+      }
+      log(this.cfg.debug, "drop unexpected status", rec.id, res.status);
+      await this.removeRecord(rec.id);
+      return;
+    }
+
+    await this.scheduleRetry(rec, lastRetryAfter);
+  }
+
+  private async scheduleRetry(
+    rec: OutboxRecord,
+    retryAfterMs?: number,
+  ): Promise<void> {
+    const nextAttempt = rec.attempts + 1;
+    if (nextAttempt >= this.cfg.maxAttempts) {
+      log(this.cfg.debug, "max attempts, dropping", rec.id);
+      await this.removeRecord(rec.id);
+      return;
+    }
+    const delay =
+      retryAfterMs !== undefined && retryAfterMs > 0
+        ? retryAfterMs
+        : backoffMs(rec.attempts);
+    rec.attempts = nextAttempt;
+    rec.nextAttemptAt = Date.now() + delay;
+    await this.updateRecord(rec);
+  }
+
+  private originHost(origin: string): string {
+    try {
+      return new URL(origin).hostname.toLowerCase();
+    } catch {
+      return origin.toLowerCase();
+    }
+  }
+
+  private setCursorToOrigin(origin: string): void {
+    const idx = this.originPool.indexOf(origin);
+    if (idx >= 0) this.originCursor = idx;
+  }
+
+  private rotateCursorAfter(origin: string): void {
+    const idx = this.originPool.indexOf(origin);
+    if (idx >= 0 && this.originPool.length > 1) {
+      this.originCursor = (idx + 1) % this.originPool.length;
+    }
+  }
+
+  private async reportDomainUnreachable(
+    origin: string,
+    kind: "network" | "timeout",
+  ): Promise<void> {
+    const host = this.originHost(origin);
+    const now = Date.now();
+    const lastAt = this.lastDomainHealthReportAt.get(host) ?? 0;
+    if (now - lastAt < this.cfg.domainHealthReportMinIntervalMs) return;
+    this.lastDomainHealthReportAt.set(host, now);
+    const reason = kind === "timeout" ? "timeout" : "network";
+    const payload = JSON.stringify({
+      domain: host,
+      sdk: "web",
+      reason,
+      sdkVersion: "web-v1",
+      unreachableCount: 1,
+      totalCount: 1,
+      timestamp: new Date(now).toISOString(),
+    });
+    await postJson(
+      `${origin}/v1/sdk/domain-health/report`,
+      payload,
+      this.cfg.requestTimeoutMs,
+    );
+  }
+
+  private async refreshEndpointPool(origin: string): Promise<void> {
+    const now = Date.now();
+    if (
+      now - this.lastEndpointListRefreshAt <
+      this.cfg.endpointListTtlSec * 1000
+    )
+      return;
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), this.cfg.requestTimeoutMs);
+    try {
+      const res = await fetch(`${origin}/v1/sdk/ingestion-hosts`, {
+        method: "GET",
+        signal: ctrl.signal,
+      });
+      if (!res.ok) return;
+      const body = (await res.json()) as { hosts?: unknown };
+      if (!Array.isArray(body.hosts)) return;
+      const nextOrigins = body.hosts
+        .map((h) =>
+          String(h || "")
+            .trim()
+            .toLowerCase(),
+        )
+        .filter(Boolean)
+        .map((h) => `https://${h}`);
+      if (!nextOrigins.length) return;
+      this.originPool = [...new Set(nextOrigins)];
+      this.originCursor = 0;
+      this.lastEndpointListRefreshAt = now;
+    } catch {
+      // best effort only
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private collectIdempotencyKey(payload: string): string | undefined {
+    try {
+      const parsed = JSON.parse(payload) as { idempotencyKey?: unknown };
+      const v =
+        typeof parsed?.idempotencyKey === "string"
+          ? parsed.idempotencyKey.trim()
+          : "";
+      return v || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private captureVisitorFromCollectAck(body: unknown): void {
+    if (!body || typeof body !== "object") return;
+    const visitorIdRaw =
+      "visitorId" in body ? (body as { visitorId?: unknown }).visitorId : "";
+    const visitorId =
+      typeof visitorIdRaw === "string" ? visitorIdRaw.trim() : "";
+    if (!visitorId) return;
+    this.context.visitorId = visitorId;
+    writeStoredVisitorId(visitorId);
+  }
+}
+
+let singleton: YTrackingWebClient | null = null;
+
+export function init(cfg: InitConfig): YTrackingWebClient {
+  if (typeof window === "undefined") {
+    throw new Error("YTrackingWeb: browser only");
+  }
+  singleton?.shutdown();
+  singleton = new YTrackingWebClient(cfg);
+  void singleton.start();
+  return singleton;
+}
+
+export function getClient(): YTrackingWebClient | null {
+  return singleton;
+}
+
+export async function track(
+  eventType: string,
+  options?: { props?: Record<string, unknown> },
+): Promise<void> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.track(eventType, options);
+}
+
+export async function trackPageView(): Promise<void> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.trackPageView();
+}
+
+export async function flush(): Promise<void> {
+  if (singleton) await singleton.flush();
+}
+
+export function shutdown(): void {
+  singleton?.shutdown();
+  singleton = null;
+}
+
+export async function install(opts?: { clickId?: string }): Promise<void> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.install(opts);
+}
+
+export function setContext(partial: {
+  visitorId?: string;
+  sessionId?: string;
+  clickId?: string;
+  campaignId?: string;
+  appId?: string;
+}): void {
+  singleton?.setContext(partial);
+}

package/src/idb.ts

@@ -0,0 +1,103 @@
+import type { OutboxRecord } from "./types";
+
+const DB_NAME = "ytracking_web_sdk";
+const DB_VERSION = 2;
+const STORE = "outbox";
+
+export async function openOutboxDb(): Promise<IDBDatabase | null> {
+  if (typeof indexedDB === "undefined") return null;
+  return new Promise((resolve) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onerror = () => resolve(null);
+    req.onsuccess = () => resolve(req.result);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE)) {
+        const s = db.createObjectStore(STORE, { keyPath: "id" });
+        s.createIndex("nextAttemptAt", "nextAttemptAt", { unique: false });
+      } else {
+        const tx = req.transaction;
+        const s = tx?.objectStore(STORE);
+        if (s && !s.indexNames.contains("nextAttemptAt")) {
+          s.createIndex("nextAttemptAt", "nextAttemptAt", { unique: false });
+        }
+      }
+    };
+  });
+}
+
+export async function idbAdd(
+  db: IDBDatabase,
+  record: OutboxRecord,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    const tx = db.transaction(STORE, "readwrite");
+    tx.oncomplete = () => resolve(true);
+    tx.onerror = () => resolve(false);
+    tx.onabort = () => resolve(false);
+    tx.objectStore(STORE).add(record);
+  });
+}
+
+export async function idbGetAll(db: IDBDatabase): Promise<OutboxRecord[]> {
+  return new Promise((resolve) => {
+    const tx = db.transaction(STORE, "readonly");
+    const req = tx.objectStore(STORE).getAll();
+    req.onsuccess = () => resolve((req.result as OutboxRecord[]) || []);
+    req.onerror = () => resolve([]);
+  });
+}
+
+export async function idbCount(db: IDBDatabase): Promise<number> {
+  return new Promise((resolve) => {
+    const tx = db.transaction(STORE, "readonly");
+    const req = tx.objectStore(STORE).count();
+    req.onsuccess = () => resolve(Number(req.result ?? 0));
+    req.onerror = () => resolve(0);
+  });
+}
+
+export async function idbGetDue(
+  db: IDBDatabase,
+  nowMs: number,
+  limit: number,
+): Promise<OutboxRecord[]> {
+  if (limit <= 0) return [];
+  return new Promise((resolve) => {
+    const tx = db.transaction(STORE, "readonly");
+    const out: OutboxRecord[] = [];
+    const idx = tx.objectStore(STORE).index("nextAttemptAt");
+    const req = idx.openCursor(IDBKeyRange.upperBound(nowMs));
+    req.onsuccess = () => {
+      const cur = req.result;
+      if (!cur || out.length >= limit) {
+        resolve(out);
+        return;
+      }
+      out.push(cur.value as OutboxRecord);
+      cur.continue();
+    };
+    req.onerror = () => resolve([]);
+  });
+}
+
+export async function idbDelete(db: IDBDatabase, id: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE, "readwrite");
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.objectStore(STORE).delete(id);
+  });
+}
+
+export async function idbPut(
+  db: IDBDatabase,
+  record: OutboxRecord,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE, "readwrite");
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.objectStore(STORE).put(record);
+  });
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export type { InitConfig, OutboxRecord, OutboxKind } from "./types";
+export {
+  backoffMs,
+  eventPriority,
+  isNonRetryableStatus,
+  isRetryableStatus,
+} from "./retry";
+export { buildCollectEnvelope, getOrCreateSessionId } from "./payload";
+export {
+  init,
+  track,
+  trackPageView,
+  flush,
+  shutdown,
+  install,
+  setContext,
+  getClient,
+  YTrackingWebClient,
+} from "./client";

package/src/payload.ts

@@ -0,0 +1,208 @@
+const SESSION_KEY = "_ytsid";
+const VISITOR_KEY = "yt_vid_v1";
+
+export function getOrCreateSessionId(): string | undefined {
+  try {
+    const existing = localStorage.getItem(SESSION_KEY);
+    if (existing) return existing;
+    const sid =
+      typeof crypto !== "undefined" && crypto.randomUUID
+        ? crypto.randomUUID()
+        : `sess_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    localStorage.setItem(SESSION_KEY, sid);
+    return sid;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readStoredVisitorId(): string | undefined {
+  try {
+    const v = localStorage.getItem(VISITOR_KEY)?.trim() ?? "";
+    return v || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeStoredVisitorId(visitorId: string | undefined): void {
+  if (!visitorId) return;
+  try {
+    localStorage.setItem(VISITOR_KEY, visitorId.trim());
+  } catch {
+    // best effort
+  }
+}
+
+function hashDjb2(input: string): string {
+  let h = 5381;
+  for (let i = 0; i < input.length; i += 1) {
+    h = (h * 33) ^ input.charCodeAt(i);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+export function buildSoftFingerprintVisitorId(): string | undefined {
+  try {
+    const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+    const language = typeof navigator !== "undefined" ? navigator.language : "";
+    const timezone =
+      typeof Intl !== "undefined"
+        ? Intl.DateTimeFormat().resolvedOptions().timeZone
+        : "";
+    const width = typeof screen !== "undefined" ? String(screen.width) : "";
+    const height = typeof screen !== "undefined" ? String(screen.height) : "";
+    const seed = [ua, language, timezone, width, height].join("|");
+    if (!seed.replace(/\|/g, "").trim()) return undefined;
+    return `fp_${hashDjb2(seed)}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function queryParams(): Record<string, string> {
+  const out: Record<string, string> = {};
+  try {
+    const sp = new URLSearchParams(location.search);
+    sp.forEach((v, k) => {
+      out[k] = v;
+    });
+  } catch {
+    /* ignore */
+  }
+  return out;
+}
+
+export function coarseDevice(ua: string): {
+  type: string;
+  os: string | null;
+  browser: string | null;
+} {
+  const u = ua.toLowerCase();
+  const type = /tablet|ipad/.test(u)
+    ? "tablet"
+    : /mobile|iphone|android/.test(u)
+      ? "mobile"
+      : "desktop";
+  const os = /iphone|ipad|ipod/.test(u)
+    ? "iOS"
+    : /android/.test(u)
+      ? "Android"
+      : /mac os/.test(u)
+        ? "macOS"
+        : /windows/.test(u)
+          ? "Windows"
+          : null;
+  const browser = /edg\//.test(u)
+    ? "Edge"
+    : /chrome/.test(u) && !/edg/.test(u)
+      ? "Chrome"
+      : /safari/.test(u) && !/chrome/.test(u)
+        ? "Safari"
+        : /firefox/.test(u)
+          ? "Firefox"
+          : null;
+  return { type, os, browser };
+}
+
+function isUuidLike(s: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    s,
+  );
+}
+
+export type CollectEnvelope = {
+  siteId: string;
+  /** Same as `event.props._ytSdkEventId` when that value is a UUID; server uses it as `events.id` for retries. */
+  idempotencyKey?: string;
+  event: {
+    type: string;
+    timestamp: string;
+    sessionId?: string;
+    page: { id: string; path: string; title?: string };
+    traffic: {
+      landingUrl: string;
+      referrer?: string;
+      query: Record<string, string>;
+    };
+    device: {
+      type: string;
+      os?: string;
+      browser?: string;
+      language?: string;
+      timezone?: string;
+      screenWidth?: number;
+      screenHeight?: number;
+    };
+    props: Record<string, unknown>;
+    visitorId?: string;
+    clickId?: string;
+    campaignId?: string;
+    appId?: string;
+  };
+};
+
+export function buildCollectEnvelope(
+  siteId: string,
+  eventType: string,
+  props: Record<string, unknown>,
+  opts?: {
+    visitorId?: string;
+    sessionId?: string;
+    clickId?: string;
+    campaignId?: string;
+    appId?: string;
+  },
+): CollectEnvelope {
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+  const dev = coarseDevice(ua);
+  const sdkEventId =
+    typeof crypto !== "undefined" && crypto.randomUUID
+      ? crypto.randomUUID()
+      : `evt_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+  const root: CollectEnvelope = {
+    siteId: String(siteId).trim(),
+    event: {
+      type: eventType,
+      timestamp: new Date().toISOString(),
+      sessionId: opts?.sessionId?.trim() || getOrCreateSessionId(),
+      page: {
+        id: typeof location !== "undefined" ? location.pathname || "/" : "/",
+        path: typeof location !== "undefined" ? location.pathname || "/" : "/",
+        title:
+          typeof document !== "undefined"
+            ? document.title || undefined
+            : undefined,
+      },
+      traffic: {
+        landingUrl: typeof location !== "undefined" ? location.href : "",
+        referrer:
+          typeof document !== "undefined"
+            ? document.referrer || undefined
+            : undefined,
+        query: typeof location !== "undefined" ? queryParams() : {},
+      },
+      device: {
+        type: dev.type,
+        os: dev.os || undefined,
+        browser: dev.browser || undefined,
+        language:
+          typeof navigator !== "undefined" ? navigator.language : undefined,
+        timezone:
+          typeof Intl !== "undefined"
+            ? Intl.DateTimeFormat().resolvedOptions().timeZone
+            : undefined,
+        screenWidth: typeof screen !== "undefined" ? screen.width : undefined,
+        screenHeight: typeof screen !== "undefined" ? screen.height : undefined,
+      },
+      props: { ...props, _ytSdkEventId: sdkEventId, _ytSdk: "web-v1" },
+      visitorId: opts?.visitorId?.trim() || undefined,
+      clickId: opts?.clickId?.trim() || undefined,
+      campaignId: opts?.campaignId?.trim() || undefined,
+      appId: opts?.appId?.trim() || undefined,
+    },
+  };
+  if (isUuidLike(sdkEventId)) root.idempotencyKey = sdkEventId;
+  return root;
+}

package/src/retry.ts

@@ -0,0 +1,30 @@
+/** HTTP statuses that should not be retried (docs/SDK_DESIGN.md §8). */
+export function isNonRetryableStatus(status: number): boolean {
+  return status === 400 || status === 401 || status === 403 || status === 404;
+}
+
+export function isRetryableStatus(status: number): boolean {
+  if (status === 429) return true;
+  if (status >= 500 && status <= 599) return true;
+  if (status === 522 || status === 523 || status === 525) return true;
+  return false;
+}
+
+export function backoffMs(attemptIndexZeroBased: number): number {
+  const table = [2000, 5000, 15000, 30000, 60000];
+  const base =
+    attemptIndexZeroBased < table.length
+      ? table[attemptIndexZeroBased]
+      : 600000;
+  const jitter = base * 0.2 * (Math.random() * 2 - 1);
+  return Math.min(Math.max(0, Math.floor(base + jitter)), 600000);
+}
+
+const HIGH = new Set(["download_click", "registration", "payment", "app_open"]);
+const LOW = new Set(["page_view", "scroll", "heartbeat"]);
+
+export function eventPriority(eventType: string): number {
+  if (HIGH.has(eventType)) return 10;
+  if (LOW.has(eventType)) return 1;
+  return 5;
+}

package/src/transport.ts

@@ -0,0 +1,65 @@
+export type PostResult =
+  | { ok: true; status: number; retryAfterMs?: number; bodyJson?: unknown }
+  | {
+      ok: false;
+      kind: "network" | "timeout" | "http";
+      status?: number;
+      retryAfterMs?: number;
+    };
+
+function parseRetryAfter(header: string | null): number | undefined {
+  if (!header) return undefined;
+  const raw = header.trim();
+  const n = Number.parseInt(raw, 10);
+  if (Number.isFinite(n) && n >= 0) return n * 1000;
+  const atMs = Date.parse(raw);
+  if (Number.isFinite(atMs)) {
+    return Math.max(0, atMs - Date.now());
+  }
+  return undefined;
+}
+
+export async function postJson(
+  url: string,
+  body: string,
+  timeoutMs: number,
+  idempotencyKey?: string,
+): Promise<PostResult> {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const hdrs: Record<string, string> = { "Content-Type": "application/json" };
+    if (idempotencyKey) hdrs["Idempotency-Key"] = idempotencyKey;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: hdrs,
+      body,
+      credentials: "include",
+      signal: ctrl.signal,
+      keepalive: true,
+    });
+    clearTimeout(t);
+    const retryAfterMs = parseRetryAfter(res.headers.get("Retry-After"));
+    let bodyJson: unknown;
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      try {
+        bodyJson = await res.clone().json();
+      } catch {
+        bodyJson = undefined;
+      }
+    }
+    if (retryAfterMs !== undefined) {
+      return { ok: true, status: res.status, retryAfterMs, bodyJson };
+    }
+    return { ok: true, status: res.status, bodyJson };
+  } catch (e) {
+    clearTimeout(t);
+    const name =
+      e && typeof e === "object" && "name" in e
+        ? String((e as Error).name)
+        : "";
+    if (name === "AbortError") return { ok: false, kind: "timeout" };
+    return { ok: false, kind: "network" };
+  }
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export type OutboxKind = "collect" | "install";
+
+export type OutboxRecord = {
+  id: string;
+  kind: OutboxKind;
+  payload: string;
+  attempts: number;
+  nextAttemptAt: number;
+  createdAt: number;
+  priority: number;
+  eventType: string;
+};
+
+export type InitConfig = {
+  siteId: string;
+  baseUrls: string[];
+  fallbackBaseUrls?: string[];
+  debug?: boolean;
+  enableVisitorFallbackFingerprint?: boolean;
+  maxQueueSize?: number;
+  flushIntervalMs?: number;
+  requestTimeoutMs?: number;
+  batchSize?: number;
+  flushConcurrency?: number;
+  maxAttempts?: number;
+  endpointListTtlSec?: number;
+  domainHealthReportMinIntervalMs?: number;
+};