ytracking-web 0.1.1 → 0.1.2

package/README.md

@@ -21,9 +21,9 @@ npm install ytracking-web
 
 ## 發佈至 npm
 
-1. 於倉庫根目錄：`npm run check:web-sdk`、（建議）`npm run build:web-sdk`。
+1. 於倉庫根目錄先跑契約檢查：`npm run check:web-sdk`、`npm run check:openapi-drift`、（建議）`npm run build:web-sdk`。（本機 **`npm run publish:ytracking-web`** 已內含 `check:web-sdk` 與 `check:openapi-drift`。）
 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）。
+3. **本機（免 `npm login`，適合首次發佈作法 B）**：在倉庫根目錄設定 **`NPM_TOKEN`** 後執行 **`npm run publish:ytracking-web`**（會先跑 `check:web-sdk` 再 `npm publish`）。若有 API 契約改動，請先在 root 執行 `npm run check:openapi-drift` 並同步更新 `docs/API.md` / `docs/openapi.yaml`。
 
 
 ## 使用（IIFE）
@@ -55,6 +55,7 @@ npm install ytracking-web
 - `track(type, { props })` — 對應 `POST /v1/collect` envelope
 - `trackPageView()` — `page_view`
 - `install({ clickId? })` — 內嵌 **`POST /v1/install`**（無 `appId` 之 embed 形態）
+- `issueAttributionToken({ clickId?, ttlSeconds?, campaignId?, appId?, deferredContext? })` — 同步 **`POST /v1/attribution/token`**（不入佇列）；沿用 `setContext` 之 visitor／session／click 等
 - `flush()` — 手動送出佇列
 - `setContext({ visitorId, sessionId, clickId, campaignId, appId })` — 後續事件帶入
 - `shutdown()` — 停止定時 flush
@@ -64,7 +65,7 @@ npm install ytracking-web
 - 每筆事件在 `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)）。
+- 須符合 `sites.allowed_origins`（見 [SITE_AND_EMBED.md](../../docs/SITE_AND_EMBED.md)）。SDK collect 出站採 `credentials: "omit"`，不依賴瀏覽器 cookie。
 - fallback 會維護 endpoint pool + cursor；成功入口可刷新新 hosts，不可達時會送 best-effort `domain-health/report`（含節流）。
 - `Retry-After` 同時支援秒數與 HTTP-date；`shutdown()` 會解除 `visibilitychange` listener，避免重複初始化時累積監聽器。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytracking-web",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Browser SDK for YTracking collect/install (IndexedDB queue, retry, multi-host)",
   "type": "module",
   "main": "./src/index.ts",

package/src/client.ts

@@ -45,6 +45,10 @@ function installUrl(origin: string): string {
   return `${origin}/v1/install`;
 }
 
+function attributionTokenUrl(origin: string): string {
+  return `${origin}/v1/attribution/token`;
+}
+
 export class YTrackingWebClient {
   private cfg: Required<
     Pick<InitConfig, "siteId" | "baseUrls"> & {
@@ -200,6 +204,105 @@ export class YTrackingWebClient {
     });
   }
 
+  /**
+   * Issue a one-time deferred deep link token (`POST /v1/attribution/token`).
+   * Synchronous HTTP (not queued); rotates ingestion origins on success like collect/install.
+   */
+  async issueAttributionToken(opts?: {
+    clickId?: string;
+    ttlSeconds?: number;
+    campaignId?: string;
+    appId?: string;
+    deferredContext?: Record<string, unknown>;
+  }): Promise<{ attributionToken: string; expiresAt: string }> {
+    const body: Record<string, unknown> = { siteId: this.cfg.siteId };
+    const cid = opts?.clickId?.trim() || this.context.clickId?.trim();
+    if (cid) body.clickId = cid;
+    const vid = this.context.visitorId?.trim();
+    if (vid) body.visitorId = vid;
+    const sid = this.context.sessionId?.trim();
+    if (sid) body.sessionId = sid;
+    const camp = opts?.campaignId?.trim() || this.context.campaignId?.trim();
+    if (camp) body.campaignId = camp;
+    const aid = opts?.appId?.trim() || this.context.appId?.trim();
+    if (aid) body.appId = aid;
+    if (opts?.ttlSeconds != null) body.ttlSeconds = opts.ttlSeconds;
+    if (
+      opts?.deferredContext &&
+      typeof opts.deferredContext === "object" &&
+      !Array.isArray(opts.deferredContext)
+    ) {
+      body.deferredContext = opts.deferredContext;
+    }
+    const payload = JSON.stringify(body);
+    let lastRetryAfter: number | undefined;
+
+    for (const origin of this.originsInOrder()) {
+      const url = attributionTokenUrl(origin);
+      const res = await postJson(
+        url,
+        payload,
+        this.cfg.requestTimeoutMs,
+        undefined,
+      );
+      if (!res.ok) {
+        log(
+          this.cfg.debug,
+          "issueAttributionToken transport fail",
+          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 === 201) {
+        const j = res.bodyJson as {
+          attributionToken?: unknown;
+          expiresAt?: unknown;
+        };
+        const tok =
+          typeof j?.attributionToken === "string"
+            ? j.attributionToken.trim()
+            : "";
+        const exp = typeof j?.expiresAt === "string" ? j.expiresAt.trim() : "";
+        if (tok && exp) {
+          this.setCursorToOrigin(origin);
+          await this.refreshEndpointPool(origin);
+          return { attributionToken: tok, expiresAt: exp };
+        }
+      }
+      if (isNonRetryableStatus(res.status)) {
+        throw new Error(
+          `YTrackingWeb: issueAttributionToken failed with HTTP ${res.status}`,
+        );
+      }
+      if (isRetryableStatus(res.status)) {
+        log(
+          this.cfg.debug,
+          "issueAttributionToken retryable",
+          res.status,
+          origin,
+        );
+        continue;
+      }
+      throw new Error(
+        `YTrackingWeb: issueAttributionToken failed with HTTP ${res.status}`,
+      );
+    }
+
+    throw new Error(
+      lastRetryAfter !== undefined
+        ? `YTrackingWeb: issueAttributionToken failed (Retry-After hint ${lastRetryAfter}ms)`
+        : "YTrackingWeb: issueAttributionToken failed on all origins",
+    );
+  }
+
   private async enqueue(p: {
     kind: OutboxRecord["kind"];
     payload: string;
@@ -567,6 +670,17 @@ export async function install(opts?: { clickId?: string }): Promise<void> {
   return singleton.install(opts);
 }
 
+export async function issueAttributionToken(opts?: {
+  clickId?: string;
+  ttlSeconds?: number;
+  campaignId?: string;
+  appId?: string;
+  deferredContext?: Record<string, unknown>;
+}): Promise<{ attributionToken: string; expiresAt: string }> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.issueAttributionToken(opts);
+}
+
 export function setContext(partial: {
   visitorId?: string;
   sessionId?: string;

package/src/index.ts

@@ -13,6 +13,7 @@ export {
   flush,
   shutdown,
   install,
+  issueAttributionToken,
   setContext,
   getClient,
   YTrackingWebClient,

package/src/transport.ts

@@ -34,7 +34,9 @@ export async function postJson(
       method: "POST",
       headers: hdrs,
       body,
-      credentials: "include",
+      // Collect does not depend on cookies. Keep this non-credentialed so
+      // wildcard ACAO ("*") deployments remain browser-compatible.
+      credentials: "omit",
       signal: ctrl.signal,
       keepalive: true,
     });