@cross-deck/web 1.7.0 → 1.8.0

package/dist/react.cjs

@@ -37,6 +37,8 @@ var CrossdeckError = class _CrossdeckError extends Error {
     this.requestId = payload.requestId;
     this.status = payload.status;
     this.retryAfterMs = payload.retryAfterMs;
+    this.minVersion = payload.minVersion;
+    this.surface = payload.surface;
     Object.setPrototypeOf(this, _CrossdeckError.prototype);
   }
 };
@@ -57,7 +59,10 @@ async function crossdeckErrorFromResponse(res) {
       message: envelope.message ?? `HTTP ${res.status}`,
       requestId: envelope.request_id ?? requestId,
       status: res.status,
-      retryAfterMs
+      retryAfterMs,
+      // PARK metadata, present only on a 426 / sdk_version_unsupported body.
+      minVersion: typeof envelope.minVersion === "string" ? envelope.minVersion : void 0,
+      surface: typeof envelope.surface === "string" ? envelope.surface : void 0
     });
   }
   return new CrossdeckError({
@@ -93,7 +98,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.7.0";
+var SDK_VERSION = "1.8.0";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -933,6 +938,18 @@ var EventQueue = class {
     this.cancelTimer = null;
     this.firstFlushFired = false;
     this.nextRetryAt = null;
+    /**
+     * PARK state (HTTP 426 / `sdk_version_unsupported`). Once parked, the
+     * queue stops flushing — the server has told us our wire dialect is too
+     * old, and retrying the same payload only burns the user's battery and
+     * bandwidth and drips pointless rejects into the server logs until the
+     * app ships an upgraded SDK. The held events stay durable (persisted)
+     * and are delivered by the next boot's rehydrate, post-upgrade. Parked
+     * is per-instance: a fresh boot (the upgraded build) starts unparked.
+     */
+    this.parked = false;
+    /** One developer-facing console warning per instance — never per-event spam. */
+    this.parkWarned = false;
     this.retry = new RetryPolicy(cfg.retry ?? {});
     this.persistent = cfg.persistentStore ?? null;
     if (this.persistent) {
@@ -988,6 +1005,7 @@ var EventQueue = class {
    * flushes (pagehide / visibilitychange→hidden / beforeunload).
    */
   async flush(options = {}) {
+    if (this.parked) return null;
     let batch;
     let batchId;
     if (this.pendingBatch !== null && this.pendingBatchId !== null) {
@@ -1039,6 +1057,29 @@ var EventQueue = class {
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       this.lastError = message;
+      if (isVersionRejected(err)) {
+        this.parked = true;
+        this.buffer = [...batch, ...this.buffer];
+        if (this.buffer.length > HARD_BUFFER_CAP) {
+          const overflow = this.buffer.length - HARD_BUFFER_CAP;
+          this.buffer.splice(0, overflow);
+          this.dropped += overflow;
+        }
+        this.pendingBatch = null;
+        this.pendingBatchId = null;
+        this.inFlight -= batch.length;
+        this.persistAll();
+        this.cfg.onBufferChange?.(this.buffer.length);
+        const minVersion = versionRejectionFloor(err);
+        if (!this.parkWarned) {
+          this.parkWarned = true;
+          console.warn(
+            `[Crossdeck] SDK outdated \u2014 the server is no longer accepting this version's event format. Your events are PARKED on-device (held, not lost) and will deliver automatically once you update @cross-deck/web${minVersion ? ` to >= ${minVersion}` : ""} and redeploy.`
+          );
+        }
+        this.cfg.onParked?.({ minVersion, surface: versionRejectionSurface(err) });
+        return null;
+      }
       if (isPermanent4xx(err)) {
         const droppedCount = batch.length;
         this.pendingBatch = null;
@@ -1157,8 +1198,22 @@ function isPermanent4xx(err) {
   if (typeof status !== "number" || !Number.isFinite(status)) return false;
   if (status < 400 || status >= 500) return false;
   if (status === 408 || status === 429) return false;
+  if (status === 426) return false;
   return true;
 }
+function isVersionRejected(err) {
+  if (!err || typeof err !== "object") return false;
+  if (err.status === 426) return true;
+  return err.code === "sdk_version_unsupported";
+}
+function versionRejectionFloor(err) {
+  const v = err?.minVersion;
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function versionRejectionSurface(err) {
+  const v = err?.surface;
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
 function defaultScheduler(fn, ms) {
   const id = setTimeout(fn, ms);
   if (typeof id.unref === "function") {
@@ -2899,6 +2954,13 @@ var CROSSDECK_ERROR_CODES = Object.freeze([
     description: "A field is present but the value failed validation (wrong shape, wrong length, wrong enum value).",
     resolution: "Read error.message for the specific field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
     retryable: false
+  },
+  {
+    code: "sdk_version_unsupported",
+    type: "version_error",
+    description: "HTTP 426 \u2014 your installed SDK sends an event format the server no longer accepts. The data is good; only the wire dialect is too old. The SDK PARKS automatically: events are held on-device (paused, not lost) and deliver on the next launch after you upgrade.",
+    resolution: "Update @cross-deck/web to at least the version in error.minVersion and redeploy \u2014 the parked queue backfills automatically. See https://cross-deck.com/docs/sdk-event-durability/.",
+    retryable: false
   }
 ]);
 function getErrorCode(code) {
@@ -3444,7 +3506,8 @@ var BACKEND_WIRE_CODES = Object.freeze([
   "google_not_supported",
   "stripe_not_supported",
   "missing_required_param",
-  "invalid_param_value"
+  "invalid_param_value",
+  "sdk_version_unsupported"
 ]);
 var VERIFIER_SDK_ERROR_CODES_CATALOGUE = {
   contractId: "sdk-error-codes-catalogue",
@@ -4601,6 +4664,13 @@ var CrossdeckClient = class {
           headline,
           { ...info }
         );
+      },
+      onParked: (info) => {
+        debug.emit(
+          "sdk.parked",
+          `[crossdeck] SDK parked \u2014 server no longer accepts this version's event format. Events held on-device (paused, not lost); update @cross-deck/web${info.minVersion ? ` to >= ${info.minVersion}` : ""} to resume.`,
+          { ...info }
+        );
       }
     });
     const deviceInfo = autoTrack.deviceInfo ? collectDeviceInfo({ appVersion: opts.appVersion ?? void 0 }) : opts.appVersion ? { appVersion: opts.appVersion } : {};