@rei-standard/amsg-client 2.4.0 → 2.5.0

package/dist/index.cjs

@@ -19,21 +19,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
-  MESSAGE_KIND: () => import_amsg_shared.MESSAGE_KIND,
-  MESSAGE_TYPE: () => import_amsg_shared.MESSAGE_TYPE,
-  PUSH_SOURCE: () => import_amsg_shared.PUSH_SOURCE,
+  MESSAGE_KIND: () => import_amsg_shared2.MESSAGE_KIND,
+  MESSAGE_TYPE: () => import_amsg_shared2.MESSAGE_TYPE,
+  PUSH_SOURCE: () => import_amsg_shared2.PUSH_SOURCE,
   ReiClient: () => ReiClient,
-  buildContentPush: () => import_amsg_shared.buildContentPush,
-  buildErrorPush: () => import_amsg_shared.buildErrorPush,
-  buildReasoningPush: () => import_amsg_shared.buildReasoningPush,
-  buildToolRequestPush: () => import_amsg_shared.buildToolRequestPush,
-  isContentPush: () => import_amsg_shared.isContentPush,
-  isErrorPush: () => import_amsg_shared.isErrorPush,
-  isReasoningPush: () => import_amsg_shared.isReasoningPush,
-  isToolRequestPush: () => import_amsg_shared.isToolRequestPush
+  buildContentPush: () => import_amsg_shared2.buildContentPush,
+  buildErrorPush: () => import_amsg_shared2.buildErrorPush,
+  buildReasoningPush: () => import_amsg_shared2.buildReasoningPush,
+  buildToolRequestPush: () => import_amsg_shared2.buildToolRequestPush,
+  isContentPush: () => import_amsg_shared2.isContentPush,
+  isErrorPush: () => import_amsg_shared2.isErrorPush,
+  isReasoningPush: () => import_amsg_shared2.isReasoningPush,
+  isToolRequestPush: () => import_amsg_shared2.isToolRequestPush
 });
 module.exports = __toCommonJS(src_exports);
 var import_amsg_shared = require("@rei-standard/amsg-shared");
+var import_amsg_shared2 = require("@rei-standard/amsg-shared");
+var TEXT_ENCODER = new TextEncoder();
 var AVATAR_URL_MAX_LENGTH = 2048;
 function makeLocalError(code, message, details) {
   const err = new Error(`[rei-standard-amsg-client] ${message}`);
@@ -41,6 +43,17 @@ function makeLocalError(code, message, details) {
   if (details) err.details = details;
   return err;
 }
+function isThenable(value) {
+  return !!value && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+var SSE_LINE_NORMALIZE = /\r\n?/g;
+function classifyContentType(contentType) {
+  const main = (contentType || "").split(";")[0].trim().toLowerCase();
+  if (main === "text/event-stream") return "sse";
+  if (main === "application/json") return "json";
+  if (/^application\/[\w.+-]+\+json$/.test(main)) return "json";
+  return "unknown";
+}
 var ReiClient = class {
   /**
    * @param {ReiClientConfig} config
@@ -67,6 +80,7 @@ var ReiClient = class {
     this._instantEncryption = instantEncryption;
     this._instantClientToken = typeof config.instantClientToken === "string" && config.instantClientToken ? config.instantClientToken : "";
     this._maxPayloadBytes = normalizeMaxPayloadBytes(config.maxPayloadBytes);
+    this._lowLevelWarned = /* @__PURE__ */ new Set();
   }
   /**
    * Resolve the base URL for a given endpoint, falling back to `baseUrl`.
@@ -84,10 +98,11 @@ var ReiClient = class {
    * Must be called before any encrypted request.
    *
    * In plaintext-instant mode (`instantEncryption: false`) this is a no-op:
-   * `sendInstant()` does not need a userKey. Note that if you also intend to
-   * call `scheduleMessage` / `listMessages` / `updateMessage` (which always
-   * use AES-256-GCM), you must construct with `instantEncryption: true`
-   * (the default) — those methods will throw "Not initialised" otherwise.
+   * `sendInstant()` / `deliver()` do not need a userKey. Note that if you
+   * also intend to call `scheduleMessage` / `listMessages` / `updateMessage`
+   * (which always use AES-256-GCM), you must construct with
+   * `instantEncryption: true` (the default) — those methods will throw
+   * "Not initialised" otherwise.
    */
   async init() {
     if (this._instantEncryption === false) {
@@ -109,11 +124,11 @@ var ReiClient = class {
   /**
    * Schedule a message.
    *
-   * Note: For `messageType: 'instant'`, prefer `sendInstant()` instead.
-   * That routes through `@rei-standard/amsg-instant` (stateless, no DB
-   * round-trip) rather than `amsg-server`'s schedule-message endpoint.
-   * This method still works for instant via amsg-server for backward
-   * compatibility — see CHANGELOG / README for details.
+   * Note: For `messageType: 'instant'`, prefer `deliver()` (2.5.0+) or
+   * `sendInstant()`. Both route through `@rei-standard/amsg-instant`
+   * (stateless, no DB round-trip) rather than `amsg-server`'s schedule-
+   * message endpoint. This method still works for instant via amsg-server
+   * for backward compatibility — see CHANGELOG / README for details.
    *
    * The payload is automatically encrypted before transmission.
    *
@@ -143,12 +158,19 @@ var ReiClient = class {
     return res.json();
   }
   /**
-   * Send a one-shot instant message via `@rei-standard/amsg-instant`.
+   * **Low-level JSON dispatcher.** Use `deliver()` for new code — it
+   * gives you a correct `send-failed` vs `delivered` verdict by
+   * coordinating transport with an out-of-band observation channel.
    *
-   * Compared to `scheduleMessage({ messageType: 'instant', ... })`:
-   *   - No DB round-trip on the server side (stateless)
-   *   - Deployable to Cloudflare Workers / Deno Deploy / Vercel Edge
-   *   - Rejects scheduled-only fields (`firstSendTime`, `recurrenceType`)
+   * Posts an instant message via `@rei-standard/amsg-instant` and
+   * returns whatever the worker returns. **HTTP 200 ≠ delivery
+   * confirmation** when amsg-instant is configured with backup Web
+   * Push (default in 0.9.0+): the dispatch succeeded but the message
+   * may still land via the backup channel even if this call rejected,
+   * and a 200 here does not guarantee the consumer ever saw it. If
+   * you only care about the transport response (no delivery
+   * coordination needed), this stays useful — otherwise prefer
+   * `deliver()`.
    *
    * Two transport modes (chosen by constructor `instantEncryption`):
    *
@@ -158,59 +180,51 @@ var ReiClient = class {
    *   `X-User-Id` + `X-Payload-Encrypted: true` + `X-Encryption-Version: 1`.
    *
    * - **Plaintext** (`instantEncryption: false`) — payload is sent as raw
-   *   JSON. Targets amsg-instant 0.2.x. Sends `X-Client-Token` if
+   *   JSON. Targets amsg-instant 0.2.x+. Sends `X-Client-Token` if
    *   `instantClientToken` was configured.
    *
    * Routes to `customBaseUrls.instant` if configured, otherwise `baseUrl`.
    *
-   * If `avatarUrl` is unusable (`data:` URI, > 2 KB, or non-string), the
-   * client soft-strips it on the payload and emits a `console.warn` — the
-   * push still ships, just without an icon. If `maxPayloadBytes` is
-   * configured, oversized JSON payloads throw `PAYLOAD_TOO_LARGE_LOCAL`.
-   *
    * @param {Object} payload - Instant message payload.
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
-   * @param {{ authorization?: string }} [opts] - Optional auth header to forward.
+   * @param {{ authorization?: string, expectsBackupPush?: boolean }} [opts]
+   *   - `authorization`: optional auth header to forward.
+   *   - `expectsBackupPush`: opt-in dev reminder. Set to `true` to log a
+   *     one-shot console.warn that this is a low-level transport and
+   *     "HTTP 200 ≠ delivery confirmation" once the worker has backup
+   *     push enabled (amsg-instant 0.9.0+ default). Default (omitted) is
+   *     silent.
    * @returns {Promise<Object>} `{ success, data?: { messagesSent, sentAt }, error? }`
    */
   async sendInstant(payload, endpointPath = "/instant", opts = {}) {
-    this._sanitizeAvatarUrl(payload);
-    const json = JSON.stringify(payload);
-    this._assertPayloadSize(json, "sendInstant");
-    const headers = { "Content-Type": "application/json" };
-    let body;
-    if (this._instantEncryption === false) {
-      body = json;
-      if (this._instantClientToken) {
-        headers["X-Client-Token"] = this._instantClientToken;
-      }
-    } else {
-      const encrypted = await this._encrypt(json);
-      headers["X-User-Id"] = this._userId;
-      headers["X-Payload-Encrypted"] = "true";
-      headers["X-Encryption-Version"] = "1";
-      body = JSON.stringify(encrypted);
-    }
-    if (opts.authorization) {
-      headers["Authorization"] = opts.authorization;
-    }
-    const path = endpointPath.startsWith("/") ? endpointPath : `/${endpointPath}`;
-    const res = await fetch(`${this._resolveBaseUrl("instant")}${path}`, {
-      method: "POST",
-      headers,
-      body
-    });
+    this._maybeWarnLowLevel("sendInstant", opts);
+    const { url, headers, body } = await this._buildInstantRequest(
+      payload,
+      endpointPath,
+      { authorization: opts.authorization, methodName: "sendInstant" }
+    );
+    headers["Accept"] = "application/json";
+    const res = await fetch(url, { method: "POST", headers, body });
     return res.json();
   }
   /**
-   * Consume an instant SSE stream.
+   * **Low-level SSE consumer.** Use `deliver()` for new code — it gives
+   * you a correct `send-failed` vs `delivered` verdict by coordinating
+   * transport with an out-of-band observation channel.
+   *
+   * **Rejection ≠ delivery failure** when amsg-instant is configured
+   * with backup Web Push (default in 0.9.0+): SSE may reject for many
+   * unrelated reasons (iOS background tab killed fetch, network blip,
+   * worker 5xx) while the backup push still lands the message. Treating
+   * the rejection as the canonical error path is wrong for that worker
+   * configuration. If you need the foreground SSE chunk hook without
+   * delivery coordination (you have your own observed channel), this
+   * stays useful — otherwise prefer `deliver()`.
    *
    * Error semantics: any failure (network, protocol, abort, `onPayload`
-   * callback throwing) rejects the returned Promise. `options.onError`,
-   * when provided, is a side-channel notification (e.g. for logging or
-   * UI flashes) and fires before the rejection — it does not suppress
-   * it. Always wrap calls in `try / await` and treat the rejection as
-   * the canonical error path.
+   * callback throwing) rejects the returned Promise. `options.onError`
+   * fires before the rejection as a side-channel notification — it does
+   * NOT suppress the throw. Always wrap calls in `try / await`.
    *
    * @param {Object} payload - Instant message payload.
    * @param {string} [endpointPath] - Path under the resolved base URL. Default '/instant'.
@@ -220,28 +234,20 @@ var ReiClient = class {
    * @param {(error: unknown) => void} [options.onError]
    * @param {() => void} [options.onDone]
    * @param {AbortSignal} [options.signal]
+   * @param {boolean} [options.expectsBackupPush] - Opt-in dev reminder. Set
+   *   to `true` to log a one-shot console.warn that "rejection ≠ delivery
+   *   failure" once the worker has backup push enabled (amsg-instant 0.9.0+
+   *   default). Default (omitted) is silent.
    * @returns {Promise<void>}
    */
   async consumeInstantStream(payload, endpointPath = "/instant", options = {}) {
-    this._sanitizeAvatarUrl(payload);
-    const json = JSON.stringify(payload);
-    this._assertPayloadSize(json, "consumeInstantStream");
-    const headers = { "Content-Type": "application/json", ...options.headers || {} };
-    let body;
-    if (this._instantEncryption === false) {
-      body = json;
-      if (this._instantClientToken) {
-        headers["X-Client-Token"] = this._instantClientToken;
-      }
-    } else {
-      const encrypted = await this._encrypt(json);
-      headers["X-User-Id"] = this._userId;
-      headers["X-Payload-Encrypted"] = "true";
-      headers["X-Encryption-Version"] = "1";
-      body = JSON.stringify(encrypted);
-    }
-    const path = endpointPath.startsWith("/") ? endpointPath : `/${endpointPath}`;
-    const res = await fetch(`${this._resolveBaseUrl("instant")}${path}`, {
+    this._maybeWarnLowLevel("consumeInstantStream", options);
+    const { url, headers, body } = await this._buildInstantRequest(
+      payload,
+      endpointPath,
+      { headers: options.headers, methodName: "consumeInstantStream" }
+    );
+    const res = await fetch(url, {
       method: "POST",
       headers,
       body,
@@ -252,94 +258,211 @@ var ReiClient = class {
       throw new Error(`Instant request failed: ${res.status} ${text}`);
     }
     const contentType = res.headers.get("content-type") || "";
-    if (!contentType.includes("text/event-stream")) {
+    if (classifyContentType(contentType) !== "sse") {
       const text = await res.text().catch(() => "");
       throw new Error(`Expected text/event-stream, got ${contentType}: ${text}`);
     }
     if (!res.body) {
       throw new Error("Response body is null");
     }
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let thrown;
     try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const parts = buffer.split("\n\n");
-        buffer = parts.pop() || "";
-        for (const part of parts) {
-          if (!part.trim()) continue;
-          let eventName = "message";
-          let data = "";
-          const lines = part.split("\n");
-          for (const line of lines) {
-            if (line.startsWith(":")) continue;
-            if (line.startsWith("event:")) {
-              eventName = line.slice(6).trim();
-            } else if (line.startsWith("data:")) {
-              const piece = line.slice(5).trim();
-              data = data ? `${data}
-${piece}` : piece;
-            }
-          }
-          if (eventName === "done") {
-            if (options.onDone) options.onDone();
-            return;
-          }
-          if (eventName === "error") {
-            let parsedErr;
-            try {
-              parsedErr = JSON.parse(data);
-            } catch {
-              parsedErr = { code: "PARSE_ERROR", message: data };
-            }
-            const err = new Error(parsedErr.message || "Stream error");
-            err.code = parsedErr.code;
-            thrown = err;
-            return;
-          }
-          if (eventName === "payload") {
-            let parsedPayload;
-            try {
-              parsedPayload = JSON.parse(data);
-            } catch {
-              continue;
-            }
-            if (options.onPayload) {
-              await options.onPayload(parsedPayload);
-            }
-          }
-        }
-      }
+      await this._consumeSseStream(res, { onPayload: options.onPayload });
       if (options.onDone) options.onDone();
     } catch (err) {
-      thrown = err;
-    } finally {
-      if (thrown) {
-        try {
-          await reader.cancel(thrown);
-        } catch {
-        }
-        if (options.onError) {
-          try {
-            options.onError(thrown);
-          } catch {
-          }
-        }
+      if (options.onError) {
         try {
-          reader.releaseLock();
+          options.onError(err);
         } catch {
         }
-        throw thrown;
       }
+      throw err;
+    }
+  }
+  /**
+   * Deliver a message with an explicit delivery contract.
+   *
+   * `deliver()` is the recommended primitive for new code. It coordinates
+   * the foreground transport (SSE / JSON, picked automatically by
+   * response Content-Type) with an optional out-of-band observation
+   * channel that the caller supplies as a Promise — the library doesn't
+   * care what produces that Promise (Service Worker broadcast, IPC,
+   * native push handler, polling, anything). It returns a single
+   * `DeliveryResult` with a five-value `outcome` so you can distinguish
+   * `delivered` (truth-grade) from `cancelled` / `timeout` / `send-failed`
+   * without inferring delivery from transport rejections.
+   *
+   * Why this exists: when the server uses always-on backup Web Push
+   * (amsg-instant 0.9.0+ default), `sendInstant`'s HTTP 200 and
+   * `consumeInstantStream`'s rejection are both ambiguous w.r.t. actual
+   * delivery — the backup channel can still deliver after a transport
+   * reject, and a clean transport doesn't prove the consumer ever
+   * observed the message. `deliver()` resolves that ambiguity by
+   * making the observation channel a first-class input.
+   *
+   * @param {Object}         payload  - Instant message payload (same shape as `sendInstant`).
+   * @param {DeliverOptions} opts     - Delivery contract; see typedef.
+   * @returns {Promise<DeliveryResult>}
+   */
+  async deliver(payload, opts) {
+    if (!opts || typeof opts !== "object") {
+      throw new TypeError("[rei-standard-amsg-client] deliver() requires an options object");
+    }
+    const {
+      delivery,
+      timeoutMs,
+      onChunk,
+      postTransportGraceMs,
+      signal,
+      headers,
+      authorization,
+      endpointPath
+    } = opts;
+    if (!delivery || typeof delivery !== "object") {
+      throw new TypeError("[rei-standard-amsg-client] deliver() requires opts.delivery (discriminated union)");
+    }
+    if (delivery.mode !== "observed" && delivery.mode !== "transport-only") {
+      throw new TypeError(
+        '[rei-standard-amsg-client] opts.delivery.mode must be "observed" or "transport-only"'
+      );
+    }
+    if (delivery.mode === "observed" && !isThenable(delivery.observed)) {
+      throw new TypeError(
+        "[rei-standard-amsg-client] opts.delivery.observed must be a Promise<ObservedDeliveryReceipt>"
+      );
+    }
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new TypeError("[rei-standard-amsg-client] opts.timeoutMs must be a positive finite number");
+    }
+    if (postTransportGraceMs !== void 0 && (typeof postTransportGraceMs !== "number" || !Number.isFinite(postTransportGraceMs) || postTransportGraceMs < 0)) {
+      throw new TypeError(
+        "[rei-standard-amsg-client] opts.postTransportGraceMs, if set, must be a non-negative finite number"
+      );
+    }
+    const start = Date.now();
+    const detail = { waitedMs: 0 };
+    if (signal && signal.aborted) {
+      detail.cancelledByCaller = true;
+      return { ok: false, outcome: "cancelled", detail };
+    }
+    const built = await this._buildInstantRequest(
+      payload,
+      endpointPath || "/instant",
+      { headers, authorization, methodName: "deliver" }
+    );
+    if (signal && signal.aborted) {
+      detail.cancelledByCaller = true;
+      detail.waitedMs = Date.now() - start;
+      return { ok: false, outcome: "cancelled", detail };
+    }
+    let finalized = false;
+    let validatedObserved = null;
+    let observedP = null;
+    if (delivery.mode === "observed") {
+      validatedObserved = this._waitForValidReceipt(delivery.observed);
+      observedP = validatedObserved.then((receipt) => ({ tag: "delivered", receipt }));
+    }
+    const wrappedOnChunk = onChunk ? async (chunk) => {
       try {
-        reader.releaseLock();
-      } catch {
+        await onChunk(chunk);
+      } catch (err) {
+        if (finalized) return;
+        if (detail.chunkHandlerError === void 0) detail.chunkHandlerError = err;
+      }
+    } : void 0;
+    const internalAbort = new AbortController();
+    let transportEnded = false;
+    let transportError;
+    const transportPromise = (async () => {
+      try {
+        const result = await this._runInstantTransport(built, {
+          signal: internalAbort.signal,
+          onChunk: wrappedOnChunk
+        });
+        if (finalized) return;
+        transportEnded = true;
+        if (result && result.kind === "json") detail.transportResponse = result.body;
+      } catch (err) {
+        if (finalized) return;
+        transportError = err;
+      }
+    })();
+    let timeoutId;
+    const timeoutP = new Promise((resolve) => {
+      timeoutId = setTimeout(() => resolve({ tag: "timeout" }), timeoutMs);
+    });
+    const signalListeners = [];
+    let cancelledP = null;
+    if (signal) {
+      cancelledP = new Promise((resolve) => {
+        const cancelListener = () => resolve({ tag: "cancelled" });
+        const abortForwarder = () => internalAbort.abort();
+        signal.addEventListener("abort", cancelListener, { once: true });
+        signal.addEventListener("abort", abortForwarder, { once: true });
+        signalListeners.push(cancelListener, abortForwarder);
+        if (signal.aborted) {
+          cancelListener();
+          abortForwarder();
+        }
+      });
+    }
+    const transportP = transportPromise.then(() => ({ tag: "transport-ended" }));
+    const racers = [transportP, timeoutP];
+    if (observedP) racers.push(observedP);
+    if (cancelledP) racers.push(cancelledP);
+    const winner = await Promise.race(racers);
+    const finalize = (outcome, ok, extras) => {
+      finalized = true;
+      clearTimeout(timeoutId);
+      internalAbort.abort();
+      if (signal) {
+        for (const l of signalListeners) signal.removeEventListener("abort", l);
+      }
+      detail.waitedMs = Date.now() - start;
+      if (transportEnded) detail.transportEnded = true;
+      if (transportError !== void 0) detail.transportError = transportError;
+      if (extras) Object.assign(detail, extras);
+      return { ok, outcome, detail };
+    };
+    const remainingBudget = () => Math.max(0, timeoutMs - (Date.now() - start));
+    if (winner.tag === "delivered") {
+      return finalize("delivered", true, { receipt: winner.receipt });
+    }
+    if (winner.tag === "cancelled") {
+      detail.cancelledByCaller = true;
+      if (validatedObserved) {
+        internalAbort.abort();
+        const cancelGrace = this._computeGrace(postTransportGraceMs, timeoutMs, remainingBudget()) / 2;
+        const lateReceipt = await this._raceObservedWithTimeout(validatedObserved, cancelGrace);
+        if (lateReceipt) {
+          return finalize("delivered", true, { receipt: lateReceipt });
+        }
       }
+      return finalize("cancelled", false);
     }
+    if (winner.tag === "timeout") {
+      return finalize("timeout", false);
+    }
+    clearTimeout(timeoutId);
+    if (!validatedObserved) {
+      if (transportError !== void 0) return finalize("send-failed", false);
+      return finalize("completed-unconfirmed", false, { transportEnded: true });
+    }
+    const grace = this._computeGrace(postTransportGraceMs, timeoutMs, remainingBudget());
+    const observedLateP = this._raceObservedWithTimeout(validatedObserved, grace).then((receipt) => ({ tag: "late", receipt }));
+    const lateRacers = [observedLateP];
+    if (cancelledP) lateRacers.push(cancelledP);
+    const lateWinner = await Promise.race(lateRacers);
+    if (lateWinner.tag === "cancelled") {
+      detail.cancelledByCaller = true;
+      return finalize("cancelled", false);
+    }
+    if (lateWinner.receipt) {
+      return finalize("delivered", true, { receipt: lateWinner.receipt });
+    }
+    if (transportError !== void 0) {
+      return finalize("send-failed", false);
+    }
+    return finalize("timeout", false, { transportEnded: true, observationChannelStalled: true });
   }
   /**
    * Update an existing scheduled message.
@@ -431,7 +554,7 @@ ${piece}` : piece;
   async subscribePush(vapidPublicKey, registration) {
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
-      applicationServerKey: this._urlBase64ToUint8Array(vapidPublicKey)
+      applicationServerKey: (0, import_amsg_shared.base64UrlToBytes)(vapidPublicKey)
     });
     return subscription;
   }
@@ -479,7 +602,7 @@ ${piece}` : piece;
    */
   _assertPayloadSize(bodyJson, methodName) {
     if (this._maxPayloadBytes == null) return;
-    const bytes = new TextEncoder().encode(bodyJson).length;
+    const bytes = TEXT_ENCODER.encode(bodyJson).length;
     if (bytes > this._maxPayloadBytes) {
       throw makeLocalError(
         "PAYLOAD_TOO_LARGE_LOCAL",
@@ -488,6 +611,287 @@ ${piece}` : piece;
       );
     }
   }
+  // ─── Transport helpers (shared by sendInstant / consumeInstantStream / deliver) ─
+  /**
+   * Build the URL, headers, and body for an instant-endpoint POST.
+   * Used by `sendInstant`, `consumeInstantStream`, and `deliver`.
+   *
+   * @private
+   * @param {Object} payload
+   * @param {string} endpointPath
+   * @param {{ headers?: Record<string, string>, authorization?: string, methodName: string }} opts
+   * @returns {Promise<{ url: string, headers: Record<string, string>, body: string }>}
+   */
+  async _buildInstantRequest(payload, endpointPath, opts) {
+    const { headers: extraHeaders, authorization, methodName } = opts;
+    this._sanitizeAvatarUrl(payload);
+    const json = JSON.stringify(payload);
+    this._assertPayloadSize(json, methodName);
+    const headers = { "Content-Type": "application/json", ...extraHeaders || {} };
+    let body;
+    if (this._instantEncryption === false) {
+      body = json;
+      if (this._instantClientToken) headers["X-Client-Token"] = this._instantClientToken;
+    } else {
+      const encrypted = await this._encrypt(json);
+      headers["X-User-Id"] = this._userId;
+      headers["X-Payload-Encrypted"] = "true";
+      headers["X-Encryption-Version"] = "1";
+      body = JSON.stringify(encrypted);
+    }
+    if (authorization) headers["Authorization"] = authorization;
+    const path = endpointPath.startsWith("/") ? endpointPath : `/${endpointPath}`;
+    const url = `${this._resolveBaseUrl("instant")}${path}`;
+    return { url, headers, body };
+  }
+  /**
+   * Run the foreground transport for `deliver()`. Takes a request pre-built
+   * by `_buildInstantRequest` so the caller can surface local-validation
+   * errors (encryption, payload-size) synchronously, instead of having
+   * them buried inside the post-transport grace race.
+   * Picks SSE or JSON based on the response Content-Type. Resolves on
+   * natural stream EOF / parsed JSON; throws on network / protocol / SSE
+   * error frame / AbortError.
+   *
+   * @private
+   * @param {{ url: string, headers: Record<string, string>, body: string }} built
+   * @param {{ signal: AbortSignal, onChunk?: (p: unknown) => Promise<void> | void }} opts
+   * @returns {Promise<{ kind: 'sse' } | { kind: 'json', body: unknown }>}
+   */
+  async _runInstantTransport(built, opts) {
+    const { signal, onChunk } = opts;
+    const { url, headers, body } = built;
+    const res = await fetch(url, { method: "POST", headers, body, signal });
+    if (!res.ok) {
+      const text2 = await res.text().catch(() => "");
+      const err = new Error(`Instant request failed: ${res.status} ${text2}`);
+      err.status = res.status;
+      throw err;
+    }
+    const contentType = res.headers.get("content-type") || "";
+    const kind = classifyContentType(contentType);
+    if (kind === "sse") {
+      if (!res.body) throw new Error("Response body is null");
+      await this._consumeSseStream(res, { onPayload: onChunk });
+      return { kind: "sse" };
+    }
+    if (kind === "json") {
+      const json = await res.json();
+      return { kind: "json", body: json };
+    }
+    const text = await res.text().catch(() => "");
+    throw new Error(`Expected text/event-stream or application/json, got ${contentType}: ${text}`);
+  }
+  /**
+   * Consume an SSE response body, dispatching `event: payload` frames to
+   * `onPayload`. Resolves on `event: done` or natural EOF. Throws on
+   * `event: error` frames, `onPayload` throws, or stream read errors.
+   *
+   * @private
+   * @param {Response} res
+   * @param {{ onPayload?: (p: unknown) => Promise<void> | void }} opts
+   * @returns {Promise<void>}
+   */
+  async _consumeSseStream(res, opts) {
+    const { onPayload } = opts;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let thrown;
+    const processFrame = async (part) => {
+      if (!part.trim()) return null;
+      let eventName = "message";
+      let data = "";
+      const lines = part.split("\n");
+      for (const line of lines) {
+        if (line.startsWith(":")) continue;
+        if (line.startsWith("event:")) {
+          eventName = line.slice(6).trim();
+        } else if (line.startsWith("data:")) {
+          const piece = line.slice(5).trim();
+          data = data ? `${data}
+${piece}` : piece;
+        }
+      }
+      if (eventName === "done") return "done";
+      if (eventName === "error") {
+        let parsedErr;
+        try {
+          parsedErr = JSON.parse(data);
+        } catch {
+          parsedErr = { code: "PARSE_ERROR", message: data };
+        }
+        const err = new Error(parsedErr.message || "Stream error");
+        err.code = parsedErr.code;
+        throw err;
+      }
+      if (eventName === "payload") {
+        let parsedPayload;
+        try {
+          parsedPayload = JSON.parse(data);
+        } catch {
+          return null;
+        }
+        if (onPayload) await onPayload(parsedPayload);
+      }
+      return null;
+    };
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          buffer += decoder.decode();
+          const finalNormalized = buffer.replace(SSE_LINE_NORMALIZE, "\n");
+          if (finalNormalized.trim()) {
+            await processFrame(finalNormalized);
+          }
+          return;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const trailingCr = buffer.endsWith("\r");
+        const head = trailingCr ? buffer.slice(0, -1) : buffer;
+        const normalized = head.replace(SSE_LINE_NORMALIZE, "\n");
+        const parts = normalized.split("\n\n");
+        buffer = (parts.pop() || "") + (trailingCr ? "\r" : "");
+        for (const part of parts) {
+          const result = await processFrame(part);
+          if (result === "done") return;
+        }
+      }
+    } catch (err) {
+      thrown = err;
+    } finally {
+      if (thrown) {
+        try {
+          await reader.cancel(thrown);
+        } catch {
+        }
+        try {
+          reader.releaseLock();
+        } catch {
+        }
+        throw thrown;
+      }
+      try {
+        reader.releaseLock();
+      } catch {
+      }
+    }
+  }
+  // ─── deliver() helpers ──────────────────────────────────────────
+  /**
+   * Wraps the caller's observed Promise so it only settles on a valid
+   * `ObservedDeliveryReceipt` (per RFC: at least one of messageId /
+   * sessionId must be a non-empty string). Invalid receipts and
+   * rejections leave the returned Promise pending — the race's timeout
+   * or abort branches take over.
+   *
+   * @private
+   * @param {Promise<ObservedDeliveryReceipt>} source
+   * @returns {Promise<ObservedDeliveryReceipt>}
+   */
+  _waitForValidReceipt(source) {
+    return new Promise((resolve) => {
+      Promise.resolve(source).then(
+        (receipt) => {
+          if (this._validateReceipt(receipt)) {
+            resolve(receipt);
+          }
+        },
+        () => {
+        }
+      );
+    });
+  }
+  /**
+   * Identity check: a receipt must be an object with at least one of
+   * `messageId` or `sessionId` as a non-empty string. Caller-supplied
+   * observation channels can produce arbitrary shapes; this gate
+   * prevents an empty-resolve from being interpreted as a successful
+   * delivery (a common shape of caller bug).
+   *
+   * @private
+   * @param {unknown} receipt
+   * @returns {boolean}
+   */
+  _validateReceipt(receipt) {
+    if (!receipt || typeof receipt !== "object") return false;
+    const hasMsgId = typeof receipt.messageId === "string" && receipt.messageId.length > 0;
+    const hasSessionId = typeof receipt.sessionId === "string" && receipt.sessionId.length > 0;
+    return hasMsgId || hasSessionId;
+  }
+  /**
+   * Race a Promise against a timeout. Returns the resolved value if the
+   * Promise wins, or `null` if the timeout fires first. Promise rejection
+   * is treated as "did not arrive" (same as timeout, returns `null`).
+   *
+   * @private
+   * @template T
+   * @param {Promise<T>} promise
+   * @param {number} ms
+   * @returns {Promise<T | null>}
+   */
+  _raceObservedWithTimeout(promise, ms) {
+    return new Promise((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        resolve(null);
+      }, Math.max(0, ms));
+      Promise.resolve(promise).then(
+        (value) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(value);
+        },
+        () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(null);
+        }
+      );
+    });
+  }
+  /**
+   * Post-transport grace formula. Defaults to
+   * `min(remainingBudget, max(5000ms, timeoutMs * 0.1))`. Caller override
+   * is capped by remaining budget so it can never exceed the total timeout.
+   *
+   * @private
+   * @param {number | undefined} override
+   * @param {number} totalTimeoutMs
+   * @param {number} remainingMs
+   * @returns {number}
+   */
+  _computeGrace(override, totalTimeoutMs, remainingMs) {
+    if (typeof override === "number" && Number.isFinite(override) && override >= 0) {
+      return Math.min(override, remainingMs);
+    }
+    const defaultGrace = Math.max(5e3, Math.floor(totalTimeoutMs * 0.1));
+    return Math.min(defaultGrace, remainingMs);
+  }
+  /**
+   * One-shot dev reminder for low-level instant APIs. The warning is opt-in
+   * per call via `opts.expectsBackupPush === true` and fires at most once
+   * per ReiClient instance per method name. Default (omitted or `false`)
+   * is silent.
+   *
+   * @private
+   * @param {string} methodName
+   * @param {{ expectsBackupPush?: boolean }} opts
+   */
+  _maybeWarnLowLevel(methodName, opts) {
+    if (!opts || opts.expectsBackupPush !== true) return;
+    if (this._lowLevelWarned.has(methodName)) return;
+    this._lowLevelWarned.add(methodName);
+    const verdict = methodName === "sendInstant" ? "HTTP 200 \u2260 delivery confirmation" : "rejection \u2260 delivery failure";
+    console.warn(
+      `[rei-standard-amsg-client] ${methodName} is a low-level transport \u2014 ${verdict} when the worker is configured with always-on backup Web Push (amsg-instant 0.9.0+ default). Prefer client.deliver() for a correct delivered / cancelled / timeout / send-failed verdict.`
+    );
+  }
   // ─── Crypto helpers (Web Crypto API) ────────────────────────────
   /**
    * Encrypt plaintext with AES-256-GCM.
@@ -499,7 +903,7 @@ ${piece}` : piece;
     if (!this._userKey) throw new Error("[rei-standard-amsg-client] Not initialised. Call init() first.");
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const key = await crypto.subtle.importKey("raw", this._userKey, { name: "AES-GCM" }, false, ["encrypt"]);
-    const encoded = new TextEncoder().encode(plaintext);
+    const encoded = TEXT_ENCODER.encode(plaintext);
     const cipherBuf = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);
     const cipherArr = new Uint8Array(cipherBuf);
     const encryptedData = cipherArr.slice(0, cipherArr.length - 16);
@@ -552,15 +956,6 @@ ${piece}` : piece;
     }
     return arr;
   }
-  /** @private */
-  _urlBase64ToUint8Array(base64String) {
-    const padding = "=".repeat((4 - base64String.length % 4) % 4);
-    const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
-    const raw = atob(base64);
-    const arr = new Uint8Array(raw.length);
-    for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
-    return arr;
-  }
 };
 function normalizeMaxPayloadBytes(value) {
   if (value === void 0 || value === null) return null;