@reportforge/playwright-pdf 0.23.0 → 0.24.0

package/README.md

@@ -245,7 +245,7 @@ Sharded runs need no extra config: every shard of one CI run converges on the sa
 
 Live streaming is best-effort and entitlement-gated: if the server is unreachable the run is unaffected, and an active subscription with the `live` feature is required. If you've configured Slack/Teams/Discord notifications, the watch link is also posted to those channels when the run starts.
 
-> **Security:** the watch link exposes test titles + statuses (and step titles when `steps` is on). Leaving `console: false` is recommended: enabling it streams your tests' stdout/stderr to anyone holding the link. Full details at [reportforge.org/docs/advanced/live](https://reportforge.org/docs/advanced/live).
+> **Security:** the watch link exposes test titles + statuses (and step titles when `steps` is on) to anyone holding it — no login needed, which is the point: share it with whoever should watch. The token is scoped to that one run, and rotating your license key never breaks an already-shared link. Leaving `console: false` is recommended: enabling it streams your tests' stdout/stderr to anyone holding the link. Full details at [reportforge.org/docs/advanced/live](https://reportforge.org/docs/advanced/live).
 
 ### Shard Merging
 

package/dist/index.d.mts

@@ -552,9 +552,12 @@ declare class PdfReporter implements Reporter {
      * Announces the watch link once the run is confirmed live-entitled. Gating on
      * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
      * feature) guarantees the link is never printed or posted for a run that will
-     * never stream — no dead links. The chat ping fires from the primary shard only
-     * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
-     * not N. The banner still prints from every shard's own log.
+     * never stream — no dead links. The link's token is the server-ISSUED one from
+     * the announce handshake (random, key-independent — a key rotation can never
+     * kill the link); the key-derived HMAC is minted only as a fallback when the
+     * handshake fails (network blip, older server). The chat ping fires from the
+     * primary shard only (unsharded, or `shard.current === 1`) so an N-way matrix
+     * posts one message, not N. The banner still prints from every shard's own log.
      */
     private announceLive;
     private resolveProjectName;

package/dist/index.d.ts

@@ -552,9 +552,12 @@ declare class PdfReporter implements Reporter {
      * Announces the watch link once the run is confirmed live-entitled. Gating on
      * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
      * feature) guarantees the link is never printed or posted for a run that will
-     * never stream — no dead links. The chat ping fires from the primary shard only
-     * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
-     * not N. The banner still prints from every shard's own log.
+     * never stream — no dead links. The link's token is the server-ISSUED one from
+     * the announce handshake (random, key-independent — a key rotation can never
+     * kill the link); the key-derived HMAC is minted only as a fallback when the
+     * handshake fails (network blip, older server). The chat ping fires from the
+     * primary shard only (unsharded, or `shard.current === 1`) so an N-way matrix
+     * posts one message, not N. The banner still prints from every shard's own log.
      */
     private announceLive;
     private resolveProjectName;

package/dist/index.js

@@ -14248,6 +14248,7 @@ var LiveStreamer = class {
     this.enabled = true;
     this.gated = false;
     this.gatePromise = null;
+    this.announcePromise = null;
     this.jwt = null;
     this.envSent = false;
     this.lastWarnMs = 0;
@@ -14280,6 +14281,58 @@ var LiveStreamer = class {
     this.capPreLicenseBuffer();
     this.scheduleFlush();
   }
+  /**
+   * One immediate empty "hello" batch, sent at run start before the banner
+   * prints. It binds the run server-side (so early link-openers and the
+   * dashboard see it instantly instead of a pending window) and returns the
+   * server-ISSUED watch token from the ack — the capability that survives
+   * every license-key lifecycle event, unlike the key-derived HMAC fallback.
+   * Returns null on any failure (not entitled, network error, older server
+   * whose ack carries no token); the caller then falls back to the HMAC link.
+   * Memoized so drain() can await the same in-flight promise (see drain()).
+   */
+  announce() {
+    return this.announcePromise ?? (this.announcePromise = this.announceOnce());
+  }
+  async announceOnce() {
+    const entitled = await this.ensureGate();
+    if (!entitled || !this.jwt) return null;
+    const body = {
+      runId: this.config.runId,
+      shardKey: this.config.shardKey,
+      shardTotal: this.config.shardTotal,
+      status: "running",
+      counts: this.snapshotCounts(),
+      tests: [],
+      events: [],
+      ...this.envSent ? {} : { env: this.config.env }
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), NETWORK_TIMEOUT_MS3);
+    try {
+      const res = await fetch(`${this.serverUrl}/api/live/ingest`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.jwt}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        await res.body?.cancel().catch(() => {
+        });
+        return null;
+      }
+      const ack = await res.json().catch(() => null);
+      if (body.env) this.envSent = true;
+      return typeof ack?.watchToken === "string" && ack.watchToken ? ack.watchToken : null;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
   /**
    * Final flush: cancels the pending timer, emits the terminal `finished` batch,
    * then awaits in-flight requests bounded by LIVE_DRAIN_DEADLINE_MS. Called from
@@ -14291,6 +14344,7 @@ var LiveStreamer = class {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
     }
+    if (this.announcePromise) await this.announcePromise;
     await this.flush("finished");
     await Promise.race([
       Promise.allSettled([...this.inFlight]),
@@ -14468,7 +14522,7 @@ function computeWatchToken(runId, key) {
 }
 function buildWatchUrl(serverUrl, runId, token) {
   const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
-  return `${base}/live/${encodeURIComponent(runId)}?t=${encodeURIComponent(token)}`;
+  return `${base}/live/${encodeURIComponent(runId)}#t=${encodeURIComponent(token)}`;
 }
 function formatLiveBanner(url) {
   const label = "Live Tracker";
@@ -14584,7 +14638,7 @@ var PdfReporter = class {
     if (this.options.redact.enabled) {
       this.redactor = new Redactor(this.options.redact);
     }
-    this.version = true ? "0.23.0" : "0.x";
+    this.version = true ? "0.24.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${this.version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -14849,18 +14903,8 @@ var PdfReporter = class {
     this.liveSteps = live.steps;
     this.liveConsole = live.console;
     void this.license();
-    const token = computeWatchToken(runId, this.options.licenseKey);
-    const watchUrl = token ? buildWatchUrl(serverUrl, runId, token) : void 0;
     const env = detectCiEnv();
     if (this.redactor && env?.buildUrl) env.buildUrl = this.redactor.redactText(env.buildUrl);
-    if (watchUrl) {
-      void this.announceLive(watchUrl, env, shard).catch(() => {
-      });
-    } else {
-      logger.warn(
-        "Live is enabled but no RF_LICENSE_KEY was found \u2014 cannot mint a watch link or stream. Set RF_LICENSE_KEY (or the `licenseKey` option)."
-      );
-    }
     this.liveStreamer = new LiveStreamer({
       serverUrl,
       runId,
@@ -14871,16 +14915,27 @@ var PdfReporter = class {
       env,
       flushMs: live.flushMs
     });
+    if (!this.options.licenseKey?.trim() && !process.env.RF_LICENSE_KEY?.trim()) {
+      logger.warn(
+        "Live is enabled but no RF_LICENSE_KEY was found \u2014 cannot mint a watch link or stream. Set RF_LICENSE_KEY (or the `licenseKey` option)."
+      );
+      return;
+    }
+    void this.announceLive(serverUrl, runId, env, shard).catch(() => {
+    });
   }
   /**
    * Announces the watch link once the run is confirmed live-entitled. Gating on
    * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
    * feature) guarantees the link is never printed or posted for a run that will
-   * never stream — no dead links. The chat ping fires from the primary shard only
-   * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
-   * not N. The banner still prints from every shard's own log.
+   * never stream — no dead links. The link's token is the server-ISSUED one from
+   * the announce handshake (random, key-independent — a key rotation can never
+   * kill the link); the key-derived HMAC is minted only as a fallback when the
+   * handshake fails (network blip, older server). The chat ping fires from the
+   * primary shard only (unsharded, or `shard.current === 1`) so an N-way matrix
+   * posts one message, not N. The banner still prints from every shard's own log.
    */
-  async announceLive(watchUrl, env, shard) {
+  async announceLive(serverUrl, runId, env, shard) {
     const info = await this.license();
     if (!info) {
       logger.warn("Live is enabled but no active license resolved \u2014 no watch link or streaming.");
@@ -14898,6 +14953,13 @@ var PdfReporter = class {
       );
       return;
     }
+    const issued = await this.liveStreamer?.announce();
+    const token = issued ?? computeWatchToken(runId, this.options.licenseKey);
+    if (!token) {
+      logger.warn("Live is enabled but no watch link could be established \u2014 streaming continues without one.");
+      return;
+    }
+    const watchUrl = buildWatchUrl(serverUrl, runId, token);
     if (isLevelEnabled("info")) {
       console.log(formatLiveBanner(watchUrl));
     }

package/dist/index.mjs

@@ -14249,6 +14249,7 @@ var LiveStreamer = class {
     this.enabled = true;
     this.gated = false;
     this.gatePromise = null;
+    this.announcePromise = null;
     this.jwt = null;
     this.envSent = false;
     this.lastWarnMs = 0;
@@ -14281,6 +14282,58 @@ var LiveStreamer = class {
     this.capPreLicenseBuffer();
     this.scheduleFlush();
   }
+  /**
+   * One immediate empty "hello" batch, sent at run start before the banner
+   * prints. It binds the run server-side (so early link-openers and the
+   * dashboard see it instantly instead of a pending window) and returns the
+   * server-ISSUED watch token from the ack — the capability that survives
+   * every license-key lifecycle event, unlike the key-derived HMAC fallback.
+   * Returns null on any failure (not entitled, network error, older server
+   * whose ack carries no token); the caller then falls back to the HMAC link.
+   * Memoized so drain() can await the same in-flight promise (see drain()).
+   */
+  announce() {
+    return this.announcePromise ?? (this.announcePromise = this.announceOnce());
+  }
+  async announceOnce() {
+    const entitled = await this.ensureGate();
+    if (!entitled || !this.jwt) return null;
+    const body = {
+      runId: this.config.runId,
+      shardKey: this.config.shardKey,
+      shardTotal: this.config.shardTotal,
+      status: "running",
+      counts: this.snapshotCounts(),
+      tests: [],
+      events: [],
+      ...this.envSent ? {} : { env: this.config.env }
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), NETWORK_TIMEOUT_MS3);
+    try {
+      const res = await fetch(`${this.serverUrl}/api/live/ingest`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.jwt}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        await res.body?.cancel().catch(() => {
+        });
+        return null;
+      }
+      const ack = await res.json().catch(() => null);
+      if (body.env) this.envSent = true;
+      return typeof ack?.watchToken === "string" && ack.watchToken ? ack.watchToken : null;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
   /**
    * Final flush: cancels the pending timer, emits the terminal `finished` batch,
    * then awaits in-flight requests bounded by LIVE_DRAIN_DEADLINE_MS. Called from
@@ -14292,6 +14345,7 @@ var LiveStreamer = class {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
     }
+    if (this.announcePromise) await this.announcePromise;
     await this.flush("finished");
     await Promise.race([
       Promise.allSettled([...this.inFlight]),
@@ -14469,7 +14523,7 @@ function computeWatchToken(runId, key) {
 }
 function buildWatchUrl(serverUrl, runId, token) {
   const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
-  return `${base}/live/${encodeURIComponent(runId)}?t=${encodeURIComponent(token)}`;
+  return `${base}/live/${encodeURIComponent(runId)}#t=${encodeURIComponent(token)}`;
 }
 function formatLiveBanner(url) {
   const label = "Live Tracker";
@@ -14585,7 +14639,7 @@ var PdfReporter = class {
     if (this.options.redact.enabled) {
       this.redactor = new Redactor(this.options.redact);
     }
-    this.version = true ? "0.23.0" : "0.x";
+    this.version = true ? "0.24.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${this.version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -14850,18 +14904,8 @@ var PdfReporter = class {
     this.liveSteps = live.steps;
     this.liveConsole = live.console;
     void this.license();
-    const token = computeWatchToken(runId, this.options.licenseKey);
-    const watchUrl = token ? buildWatchUrl(serverUrl, runId, token) : void 0;
     const env = detectCiEnv();
     if (this.redactor && env?.buildUrl) env.buildUrl = this.redactor.redactText(env.buildUrl);
-    if (watchUrl) {
-      void this.announceLive(watchUrl, env, shard).catch(() => {
-      });
-    } else {
-      logger.warn(
-        "Live is enabled but no RF_LICENSE_KEY was found \u2014 cannot mint a watch link or stream. Set RF_LICENSE_KEY (or the `licenseKey` option)."
-      );
-    }
     this.liveStreamer = new LiveStreamer({
       serverUrl,
       runId,
@@ -14872,16 +14916,27 @@ var PdfReporter = class {
       env,
       flushMs: live.flushMs
     });
+    if (!this.options.licenseKey?.trim() && !process.env.RF_LICENSE_KEY?.trim()) {
+      logger.warn(
+        "Live is enabled but no RF_LICENSE_KEY was found \u2014 cannot mint a watch link or stream. Set RF_LICENSE_KEY (or the `licenseKey` option)."
+      );
+      return;
+    }
+    void this.announceLive(serverUrl, runId, env, shard).catch(() => {
+    });
   }
   /**
    * Announces the watch link once the run is confirmed live-entitled. Gating on
    * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
    * feature) guarantees the link is never printed or posted for a run that will
-   * never stream — no dead links. The chat ping fires from the primary shard only
-   * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
-   * not N. The banner still prints from every shard's own log.
+   * never stream — no dead links. The link's token is the server-ISSUED one from
+   * the announce handshake (random, key-independent — a key rotation can never
+   * kill the link); the key-derived HMAC is minted only as a fallback when the
+   * handshake fails (network blip, older server). The chat ping fires from the
+   * primary shard only (unsharded, or `shard.current === 1`) so an N-way matrix
+   * posts one message, not N. The banner still prints from every shard's own log.
    */
-  async announceLive(watchUrl, env, shard) {
+  async announceLive(serverUrl, runId, env, shard) {
     const info = await this.license();
     if (!info) {
       logger.warn("Live is enabled but no active license resolved \u2014 no watch link or streaming.");
@@ -14899,6 +14954,13 @@ var PdfReporter = class {
       );
       return;
     }
+    const issued = await this.liveStreamer?.announce();
+    const token = issued ?? computeWatchToken(runId, this.options.licenseKey);
+    if (!token) {
+      logger.warn("Live is enabled but no watch link could be established \u2014 streaming continues without one.");
+      return;
+    }
+    const watchUrl = buildWatchUrl(serverUrl, runId, token);
     if (isLevelEnabled("info")) {
       console.log(formatLiveBanner(watchUrl));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportforge/playwright-pdf",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Playwright Test reporter that generates designed PDF reports: minimal, detailed, and executive templates with CI/CD integrations",
   "license": "Elastic-2.0",
   "author": "ReportForge",