@fabricorg/experience-runtime 0.4.8 → 0.4.10

package/dist/offline.js

@@ -1,267 +1,328 @@
-// offline.ts
+//#region offline.ts
 function createOfflineCaptureQueue(options) {
-  if (options.store.protection !== "encrypted-at-rest" && !options.allowEphemeralStore) {
-    throw new Error("Production offline capture requires an encrypted-at-rest store.");
-  }
-  if (!options.gateway.replay) throw new Error("Offline capture requires a gateway replay adapter.");
-  const fragments = indexFragments(options.plan.root);
-  const now = options.now ?? (() => /* @__PURE__ */ new Date());
-  return {
-    async capture(fragmentId, eventName, parameters, idempotencyKey) {
-      const fragment = fragments.get(fragmentId);
-      if (!fragment?.offlineEvents?.includes(eventName)) {
-        throw new Error(`Fragment event "${fragmentId}.${eventName}" is not offline-capturable.`);
-      }
-      if (!idempotencyKey || idempotencyKey.length > 256) throw new Error("Offline capture requires a bounded stable idempotency key.");
-      const capturedAt = now();
-      const captureExpiry = capturedAt.getTime() + (options.captureTtlMs ?? 864e5);
-      const planExpiry = Date.parse(options.plan.expiresAt);
-      if (!Number.isFinite(planExpiry) || planExpiry <= capturedAt.getTime()) throw new Error("Offline capture requires an unexpired render plan.");
-      const safeParameters = cloneOfflineParameters(parameters);
-      const captureId = options.nextCaptureId();
-      if (!captureId.trim()) throw new Error("Offline capture id is required.");
-      const record = {
-        captureId,
-        planId: options.plan.planId,
-        releaseDigest: options.plan.releaseDigest,
-        fragmentId,
-        eventName,
-        parameters: safeParameters,
-        idempotencyKey,
-        capturedAt: capturedAt.toISOString(),
-        expiresAt: new Date(Math.min(captureExpiry, planExpiry)).toISOString()
-      };
-      await options.store.put(record);
-      return record;
-    },
-    async replay() {
-      let completed = 0;
-      let failed = 0;
-      const parked = [];
-      const expired = [];
-      const reconciled = [];
-      const storeFailures = [];
-      const replayOne = async (record) => {
-        if (Date.parse(record.expiresAt) <= now().getTime()) {
-          await options.store.remove(record.captureId);
-          expired.push(record);
-          return;
-        }
-        const request = {
-          planId: record.planId,
-          fragmentId: record.fragmentId,
-          eventName: record.eventName,
-          parameters: record.parameters,
-          idempotencyKey: record.idempotencyKey,
-          executionReason: "offline_replay",
-          capturedAt: record.capturedAt
-        };
-        let outcome;
-        try {
-          outcome = await options.gateway.replay(request);
-        } catch (error) {
-          const thrown = classifyThrownReplayFailure(error);
-          if (thrown.kind === "transient") {
-            failed += 1;
-            return;
-          }
-          await options.store.remove(record.captureId);
-          reconciled.push({
-            record,
-            status: thrown.status,
-            ...thrown.actionInvocationId === void 0 ? {} : { actionInvocationId: thrown.actionInvocationId },
-            certainty: thrown.certainty,
-            reason: messageOf(error)
-          });
-          return;
-        }
-        const disposition = dispositionOf(outcome);
-        if (disposition.kind === "not-delivered") {
-          failed += 1;
-          return;
-        }
-        await options.store.remove(record.captureId);
-        const actionInvocationId = typeof outcome?.actionInvocationId === "string" ? outcome.actionInvocationId : void 0;
-        if (disposition.kind === "attention") {
-          reconciled.push({
-            record,
-            status: disposition.status,
-            ...actionInvocationId === void 0 ? {} : { actionInvocationId },
-            certainty: disposition.certainty,
-            reason: disposition.reason
-          });
-        } else if (disposition.kind === "parked") {
-          parked.push({ record, ...actionInvocationId === void 0 ? {} : { actionInvocationId } });
-        } else {
-          completed += 1;
-        }
-      };
-      for (const record of await options.store.list()) {
-        try {
-          await replayOne(record);
-        } catch (error) {
-          storeFailures.push({ record, reason: messageOf(error) });
-        }
-      }
-      return { completed, parked, failed, expired, reconciled, storeFailures };
-    }
-  };
+	if (options.store.protection !== "encrypted-at-rest" && !options.allowEphemeralStore) throw new Error("Production offline capture requires an encrypted-at-rest store.");
+	if (!options.gateway.replay) throw new Error("Offline capture requires a gateway replay adapter.");
+	const fragments = indexFragments(options.plan.root);
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	return {
+		async capture(fragmentId, eventName, parameters, idempotencyKey) {
+			if (!fragments.get(fragmentId)?.offlineEvents?.includes(eventName)) throw new Error(`Fragment event "${fragmentId}.${eventName}" is not offline-capturable.`);
+			if (!idempotencyKey || idempotencyKey.length > 256) throw new Error("Offline capture requires a bounded stable idempotency key.");
+			const capturedAt = now();
+			const captureExpiry = capturedAt.getTime() + (options.captureTtlMs ?? 864e5);
+			const planExpiry = Date.parse(options.plan.expiresAt);
+			if (!Number.isFinite(planExpiry) || planExpiry <= capturedAt.getTime()) throw new Error("Offline capture requires an unexpired render plan.");
+			const safeParameters = cloneOfflineParameters(parameters);
+			const captureId = options.nextCaptureId();
+			if (!captureId.trim()) throw new Error("Offline capture id is required.");
+			const record = {
+				captureId,
+				planId: options.plan.planId,
+				releaseDigest: options.plan.releaseDigest,
+				fragmentId,
+				eventName,
+				parameters: safeParameters,
+				idempotencyKey,
+				capturedAt: capturedAt.toISOString(),
+				expiresAt: new Date(Math.min(captureExpiry, planExpiry)).toISOString()
+			};
+			await options.store.put(record);
+			return record;
+		},
+		async replay() {
+			let completed = 0;
+			let failed = 0;
+			const parked = [];
+			const expired = [];
+			const reconciled = [];
+			const storeFailures = [];
+			const replayOne = async (record) => {
+				if (Date.parse(record.expiresAt) <= now().getTime()) {
+					await options.store.remove(record.captureId);
+					expired.push(record);
+					return;
+				}
+				const request = {
+					planId: record.planId,
+					fragmentId: record.fragmentId,
+					eventName: record.eventName,
+					parameters: record.parameters,
+					idempotencyKey: record.idempotencyKey,
+					executionReason: "offline_replay",
+					capturedAt: record.capturedAt
+				};
+				let outcome;
+				try {
+					outcome = await options.gateway.replay(request);
+				} catch (error) {
+					const thrown = classifyThrownReplayFailure(error);
+					if (thrown.kind === "transient") {
+						failed += 1;
+						return;
+					}
+					await options.store.remove(record.captureId);
+					reconciled.push({
+						record,
+						status: thrown.status,
+						...thrown.actionInvocationId === void 0 ? {} : { actionInvocationId: thrown.actionInvocationId },
+						certainty: thrown.certainty,
+						reason: messageOf(error)
+					});
+					return;
+				}
+				const disposition = dispositionOf(outcome);
+				if (disposition.kind === "not-delivered") {
+					failed += 1;
+					return;
+				}
+				await options.store.remove(record.captureId);
+				const actionInvocationId = typeof outcome?.actionInvocationId === "string" ? outcome.actionInvocationId : void 0;
+				if (disposition.kind === "attention") reconciled.push({
+					record,
+					status: disposition.status,
+					...actionInvocationId === void 0 ? {} : { actionInvocationId },
+					certainty: disposition.certainty,
+					reason: disposition.reason
+				});
+				else if (disposition.kind === "parked") parked.push({
+					record,
+					...actionInvocationId === void 0 ? {} : { actionInvocationId }
+				});
+				else completed += 1;
+			};
+			for (const record of await options.store.list()) try {
+				await replayOne(record);
+			} catch (error) {
+				storeFailures.push({
+					record,
+					reason: messageOf(error)
+				});
+			}
+			return {
+				completed,
+				parked,
+				failed,
+				expired,
+				reconciled,
+				storeFailures
+			};
+		}
+	};
 }
 function cloneOfflineParameters(parameters) {
-  let nodes = 0;
-  const visit = (value, depth, key) => {
-    nodes += 1;
-    if (nodes > 1e4 || depth > 20) throw new Error("Offline capture parameters exceed structural limits.");
-    if (key !== void 0 && /(?:authorization|bearer|cookie|credential|password|secret|token|claims?)/i.test(key)) {
-      throw new Error(`Offline capture parameters may not contain credential or claim field "${key}".`);
-    }
-    if (value === null || typeof value === "string" || typeof value === "boolean") return;
-    if (typeof value === "number" && Number.isFinite(value)) return;
-    if (Array.isArray(value)) {
-      value.forEach((entry) => visit(entry, depth + 1));
-      return;
-    }
-    if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
-      for (const [childKey, child] of Object.entries(value)) visit(child, depth + 1, childKey);
-      return;
-    }
-    throw new Error("Offline capture parameters must contain only portable JSON values.");
-  };
-  visit(parameters, 0);
-  const serialized = JSON.stringify(parameters);
-  if (utf8ByteLength(serialized) > 65536) throw new Error("Offline capture parameters exceed the 65536-byte limit.");
-  return JSON.parse(serialized);
+	let nodes = 0;
+	const visit = (value, depth, key) => {
+		nodes += 1;
+		if (nodes > 1e4 || depth > 20) throw new Error("Offline capture parameters exceed structural limits.");
+		if (key !== void 0 && /(?:authorization|bearer|cookie|credential|password|secret|token|claims?)/i.test(key)) throw new Error(`Offline capture parameters may not contain credential or claim field "${key}".`);
+		if (value === null || typeof value === "string" || typeof value === "boolean") return;
+		if (typeof value === "number" && Number.isFinite(value)) return;
+		if (Array.isArray(value)) {
+			value.forEach((entry) => visit(entry, depth + 1));
+			return;
+		}
+		if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+			for (const [childKey, child] of Object.entries(value)) visit(child, depth + 1, childKey);
+			return;
+		}
+		throw new Error("Offline capture parameters must contain only portable JSON values.");
+	};
+	visit(parameters, 0);
+	const serialized = JSON.stringify(parameters);
+	if (utf8ByteLength(serialized) > 65536) throw new Error("Offline capture parameters exceed the 65536-byte limit.");
+	return JSON.parse(serialized);
 }
+/**
+* UTF-8 length without an encoder global.
+*
+* This package is the interface a client uses to reach capabilities, so it
+* assumes nothing about the host beyond JSON. A React Native runtime, a worker,
+* or an older embedded engine may not supply the encoder or clone globals, and
+* the parameters were validated as portable JSON just above, so a JSON round
+* trip is the clone and a code-point walk is the byte count.
+*/
 function utf8ByteLength(text) {
-  let bytes = 0;
-  for (const character of text) {
-    const codePoint = character.codePointAt(0);
-    bytes += codePoint < 128 ? 1 : codePoint < 2048 ? 2 : codePoint < 65536 ? 3 : 4;
-  }
-  return bytes;
+	let bytes = 0;
+	for (const character of text) {
+		const codePoint = character.codePointAt(0);
+		bytes += codePoint < 128 ? 1 : codePoint < 2048 ? 2 : codePoint < 65536 ? 3 : 4;
+	}
+	return bytes;
 }
+/** Records are validated JSON, so a round trip is a faithful clone on any host. */
 function cloneRecord(value) {
-  return JSON.parse(JSON.stringify(value));
+	return JSON.parse(JSON.stringify(value));
 }
 function indexFragments(root) {
-  const result = /* @__PURE__ */ new Map();
-  const visit = (fragment) => {
-    result.set(fragment.id, fragment);
-    for (const child of fragment.children ?? []) visit(child);
-  };
-  visit(root);
-  return result;
+	const result = /* @__PURE__ */ new Map();
+	const visit = (fragment) => {
+		result.set(fragment.id, fragment);
+		for (const child of fragment.children ?? []) visit(child);
+	};
+	visit(root);
+	return result;
 }
 function createMemoryOfflineCaptureStore() {
-  const records = /* @__PURE__ */ new Map();
-  return {
-    protection: "ephemeral",
-    async put(record) {
-      if (records.has(record.captureId)) throw new Error(`Offline capture "${record.captureId}" already exists.`);
-      records.set(record.captureId, cloneRecord(record));
-    },
-    async list() {
-      return [...records.values()].map((record) => cloneRecord(record));
-    },
-    async remove(captureId) {
-      records.delete(captureId);
-    }
-  };
+	const records = /* @__PURE__ */ new Map();
+	return {
+		protection: "ephemeral",
+		async put(record) {
+			if (records.has(record.captureId)) throw new Error(`Offline capture "${record.captureId}" already exists.`);
+			records.set(record.captureId, cloneRecord(record));
+		},
+		async list() {
+			return [...records.values()].map((record) => cloneRecord(record));
+		},
+		async remove(captureId) {
+			records.delete(captureId);
+		}
+	};
 }
 function messageOf(error) {
-  return error instanceof Error ? error.message : String(error);
+	return error instanceof Error ? error.message : String(error);
 }
+/**
+* Read a returned outcome across the platform's whole status set.
+*
+* Enumerating the statuses that looked like refusals left the rest falling
+* through to "applied", which is how a validation failure got reported to an
+* operator as success. The switch covers every `ActionStatus`, and the default
+* arm surfaces anything else rather than counting it a success — the status
+* arrives as a string over a transport, so this is a runtime guarantee and not
+* a compile-time one.
+*
+* There is no "already applied" branch. A key that legitimately repeats returns
+* the original invocation without complaint, and a genuine idempotency conflict
+* means the key was reused for a materially different command, so that capture
+* was never applied and must not be discarded.
+*/
 function dispositionOf(outcome) {
-  if (!outcome || typeof outcome !== "object") {
-    return { kind: "not-delivered" };
-  }
-  const status = typeof outcome.status === "string" ? outcome.status : "";
-  const reason = outcome.reconciliation?.message ?? outcome.reconciliation?.kind ?? (typeof outcome.error === "string" ? outcome.error : status);
-  switch (status) {
-    case "pending":
-    case "running":
-    case "completed":
-      return { kind: "delivered" };
-    case "waiting_for_approval":
-      return { kind: "parked" };
-    case "reconciliation_required": {
-      const recovery = outcome.reconciliation?.executionReason === "recovery";
-      const unknown = outcome.adapterReconciliation !== void 0 || recovery;
-      return { kind: "attention", status, certainty: unknown ? "unknown" : "refused", reason };
-    }
-    case "blocked_by_policy":
-    case "validation_failed":
-      return { kind: "attention", status, certainty: "unknown", reason };
-    case "failed":
-      return { kind: "attention", status, certainty: "unknown", reason };
-    default:
-      return { kind: "attention", status: status || "unknown", certainty: "unknown", reason };
-  }
+	if (!outcome || typeof outcome !== "object") return { kind: "not-delivered" };
+	const status = typeof outcome.status === "string" ? outcome.status : "";
+	const reason = outcome.reconciliation?.message ?? outcome.reconciliation?.kind ?? (typeof outcome.error === "string" ? outcome.error : status);
+	switch (status) {
+		case "pending":
+		case "running":
+		case "completed": return { kind: "delivered" };
+		case "waiting_for_approval": return { kind: "parked" };
+		case "reconciliation_required": {
+			const recovery = outcome.reconciliation?.executionReason === "recovery";
+			return {
+				kind: "attention",
+				status,
+				certainty: outcome.adapterReconciliation !== void 0 || recovery ? "unknown" : "refused",
+				reason
+			};
+		}
+		case "blocked_by_policy":
+		case "validation_failed": return {
+			kind: "attention",
+			status,
+			certainty: "unknown",
+			reason
+		};
+		case "failed": return {
+			kind: "attention",
+			status,
+			certainty: "unknown",
+			reason
+		};
+		default: return {
+			kind: "attention",
+			status: status || "unknown",
+			certainty: "unknown",
+			reason
+		};
+	}
 }
-var CONFLICT_REASONS = /* @__PURE__ */ new Set(["actor", "authority_binding", "action_version", "parameters"]);
+const CONFLICT_REASONS = /* @__PURE__ */ new Set([
+	"actor",
+	"authority_binding",
+	"action_version",
+	"parameters"
+]);
+/**
+* An idempotency conflict is settled — retrying yields the same conflict
+* forever — but which way depends on *why* the key conflicted. `parameters`
+* or `actor` means the key was reused for a materially different command, so
+* this capture was never applied. `authority_binding` or `action_version`
+* means the *original* invocation exists and may well have applied: the
+* capture-authority adapter mints a fresh binding on every attempt, so a first
+* attempt whose response was lost conflicts with itself on the second. Deleting
+* that and calling it refused is exactly the wrong answer, so it is surfaced as
+* unknown, with the invocation it conflicted with, since that is what
+* `recordExternalReconciliation` needs.
+*
+* A conflict whose reasons cannot be read is still a conflict, so it is still
+* settled; the previous version let it fall through to transient and retried
+* it forever. Unreadable reasons resolve to `unknown`, never to `refused`.
+*/
 function classifyThrownReplayFailure(error) {
-  const conflict = conflictOf(error);
-  if (conflict) {
-    const readable = conflict.reasons.size > 0 && [...conflict.reasons].every((reason) => CONFLICT_REASONS.has(reason));
-    const neverApplied = readable && (conflict.reasons.has("parameters") || conflict.reasons.has("actor"));
-    if (neverApplied) return { kind: "settled", status: "not_delivered", certainty: "refused" };
-    return {
-      kind: "settled",
-      status: "conflict_prior_invocation",
-      certainty: "unknown",
-      ...conflict.existingInvocationId === void 0 ? {} : { actionInvocationId: conflict.existingInvocationId }
-    };
-  }
-  return isSettledReplayFailure(error) ? { kind: "settled", status: "not_delivered", certainty: "refused" } : { kind: "transient" };
+	const conflict = conflictOf(error);
+	if (conflict) {
+		if (conflict.reasons.size > 0 && [...conflict.reasons].every((reason) => CONFLICT_REASONS.has(reason)) && (conflict.reasons.has("parameters") || conflict.reasons.has("actor"))) return {
+			kind: "settled",
+			status: "not_delivered",
+			certainty: "refused"
+		};
+		return {
+			kind: "settled",
+			status: "conflict_prior_invocation",
+			certainty: "unknown",
+			...conflict.existingInvocationId === void 0 ? {} : { actionInvocationId: conflict.existingInvocationId }
+		};
+	}
+	return isSettledReplayFailure(error) ? {
+		kind: "settled",
+		status: "not_delivered",
+		certainty: "refused"
+	} : { kind: "transient" };
 }
+/**
+* Read an idempotency conflict off a thrown error.
+*
+* The host's `IdempotencyConflictError` carries the conflict as data, and a
+* gateway that rethrows it (or any error shaped like it) is read structurally.
+* Only when that is absent is the message parsed, and then defensively: the
+* phrase is located from the *end*, because the idempotency key is interpolated
+* before it and a key is whatever the application chose; the reasons are read
+* to the end of their own line, because a wrapped error may append a stack or
+* a detail line below. A message that names the phrase but cannot be parsed
+* further is still reported as a conflict, with no reasons.
+*/
 function conflictOf(error) {
-  const structural = error !== null && typeof error === "object" ? error.conflict : void 0;
-  if (structural !== null && typeof structural === "object") {
-    const { existingInvocationId, reasons } = structural;
-    if (Array.isArray(reasons)) {
-      return {
-        ...typeof existingInvocationId === "string" && existingInvocationId ? { existingInvocationId } : {},
-        reasons: new Set(reasons.filter((reason) => typeof reason === "string"))
-      };
-    }
-  }
-  const message = messageOf(error);
-  const phrase = "conflicts with invocation";
-  const at = message.toLowerCase().lastIndexOf(phrase);
-  if (at < 0) return void 0;
-  const tail = /^\s+([^\s:]+):[ \t]*([^\n]*)/.exec(message.slice(at + phrase.length));
-  if (!tail) return { reasons: /* @__PURE__ */ new Set() };
-  return {
-    existingInvocationId: tail[1],
-    reasons: new Set(tail[2].split(",").map((reason) => reason.trim()).filter(Boolean))
-  };
+	const structural = error !== null && typeof error === "object" ? error.conflict : void 0;
+	if (structural !== null && typeof structural === "object") {
+		const { existingInvocationId, reasons } = structural;
+		if (Array.isArray(reasons)) return {
+			...typeof existingInvocationId === "string" && existingInvocationId ? { existingInvocationId } : {},
+			reasons: new Set(reasons.filter((reason) => typeof reason === "string"))
+		};
+	}
+	const message = messageOf(error);
+	const at = message.toLowerCase().lastIndexOf("conflicts with invocation");
+	if (at < 0) return void 0;
+	const tail = /^\s+([^\s:]+):[ \t]*([^\n]*)/.exec(message.slice(at + 25));
+	if (!tail) return { reasons: /* @__PURE__ */ new Set() };
+	return {
+		existingInvocationId: tail[1],
+		reasons: new Set(tail[2].split(",").map((reason) => reason.trim()).filter(Boolean))
+	};
 }
 function isSettledReplayFailure(error) {
-  return [
-    // The action was never offline-eligible.
-    /not eligible for offline replay/i,
-    // The plan no longer grants, no longer exists, or was never this actor's.
-    /is not granted by the render plan/i,
-    /render plan was not found/i,
-    /render plan has expired/i,
-    /scope does not match/i,
-    /belongs to a different application assembly/i,
-    // A capture only gets older, so an age refusal can never come good. This
-    // one is independent of the capture TTL, so nothing else retires it.
-    /capturedAt is older than/i,
-    // Malformed beyond repair: passes the grammar, names no real instant.
-    /capturedAt is not a parseable instant/i,
-    /capturedAt must be an RFC 3339/i
-    // Deliberately absent: a capture dated in the future comes good as real
-    // time advances; a gateway missing its replay window is a deployment
-    // mistake somebody will fix; and an action-version mismatch fires
-    // transiently mid-rollout when a client's plan is newer than the pod it
-    // reached. Discarding any of them would destroy work a clock correction,
-    // a config change, or the rollout finishing would have replayed.
-  ].some((pattern) => pattern.test(messageOf(error)));
+	return [
+		/not eligible for offline replay/i,
+		/is not granted by the render plan/i,
+		/render plan was not found/i,
+		/render plan has expired/i,
+		/scope does not match/i,
+		/belongs to a different application assembly/i,
+		/capturedAt is older than/i,
+		/capturedAt is not a parseable instant/i,
+		/capturedAt must be an RFC 3339/i
+	].some((pattern) => pattern.test(messageOf(error)));
 }
-export {
-  createMemoryOfflineCaptureStore,
-  createOfflineCaptureQueue
-};
+//#endregion
+export { createMemoryOfflineCaptureStore, createOfflineCaptureQueue };
+
 //# sourceMappingURL=offline.js.map