pulse-updates 1.3.6 → 1.3.8

package/src/track.ts

@@ -31,16 +31,28 @@ export interface TrackOptions {
    */
   url: string;
 
-  /** The same context the config uses — identity travels with the batch, once. */
+  /**
+   * Request context shared with config. `context` identity mode reads deviceId/userId
+   * for backwards-compatible experiment metrics; `anonymous_installation` ignores
+   * them and reads only platform/appVersion.
+   */
   getContext?: () => ConfigContext;
 
+  /**
+   * `context` preserves the original experiment-event contract and sends the context
+   * deviceId/userId. `anonymous_installation` is an explicit privacy mode: it ignores
+   * both and sends only an SDK-minted app-scoped random UUID under the legacy wire
+   * field `deviceId`. Defaults to `context` for backwards compatibility.
+   */
+  identityMode?: 'context' | 'anonymous_installation';
+
   /** How often a non-empty queue is sent. Default 10s. */
   flushIntervalMs?: number;
 
   /** Events per request. The server refuses more than 100. */
   maxBatch?: number;
 
-  /** Events held before the oldest are dropped. Default 500. */
+  /** Best-effort events held before the oldest are dropped. Durable idempotent rows are never evicted. Default 500. */
   maxQueue?: number;
 
   /** Persists the outbox across process death. Use the same storage passed to initPulse. */
@@ -52,10 +64,13 @@ export interface TrackOptions {
   /** Per-request timeout. Default 10s. */
   timeoutMs?: number;
 
-  /** Maximum delivery attempts before an event is dropped. Default 10. */
+  /** Maximum delivery attempts before a best-effort event is dropped. Durable idempotent events retry until server ACK. Default 10. */
   maxAttempts?: number;
 
-  /** Return false until analytics consent exists. No event is retained before consent. */
+  /**
+   * Return false until analytics consent exists. No event is retained before consent. Consent is
+   * sampled at enqueue; an event already durably accepted remains eligible for later delivery.
+   */
   hasConsent?: () => boolean;
 
   /** Only these property keys may leave the process. */
@@ -87,6 +102,8 @@ interface QueuedEvent {
   time: string;
   props: Record<string, string>;
   attempts: number;
+  /** Caller-owned events are retained until the server ACKs their stable id. */
+  durable?: true;
 }
 
 const DEFAULT_FLUSH_MS = 10_000;
@@ -95,14 +112,18 @@ const DEFAULT_MAX_QUEUE = 500;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_MAX_ATTEMPTS = 10;
 const DEFAULT_STORAGE_KEY = 'pulse.events.v1';
+const ANALYTICS_INSTALLATION_ID_SUFFIX = '.analytics-installation-id';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 let options: TrackOptions | null = null;
 let queue: QueuedEvent[] = [];
+let analyticsInstallationId = '';
 let timer: ReturnType<typeof setInterval> | null = null;
 let sending = false;
 let nextAttemptAt = 0;
 let lifecycleSubscription: { remove: () => void } | null = null;
 let trackingGeneration = 0;
+const asynchronousStorageAdapters = new WeakSet<object>();
 
 /** Turns a config url into the track url; leaves an explicit track url alone. */
 function trackUrl(url: string): string {
@@ -116,6 +137,9 @@ export function configureTracking(opts: TrackOptions): void {
   disposeTracking();
   options = opts;
   queue = readQueue(opts);
+  analyticsInstallationId = opts.identityMode === 'anonymous_installation'
+    ? resolveAnalyticsInstallationId(opts)
+    : '';
   nextAttemptAt = 0;
   startTimer();
   lifecycleSubscription = opts.appState?.addEventListener('change', (state) => {
@@ -129,10 +153,52 @@ export function configureTracking(opts: TrackOptions): void {
  * caller has to wrap.
  */
 export function track(event: string, props?: TrackedEventInput['props'], time?: Date): void {
-  if (!options || !event) return;
-  if (options.hasConsent?.() === false) {
+  void enqueueEvent(randomEventId(), event, props, time, false);
+}
+
+/**
+ * Durably enqueue one logical event with a caller-owned UUID. Replaying the same id is safe:
+ * Pulse's server/read model deduplicates it, while the local outbox avoids duplicate rows that
+ * are still pending. `true` means the event is present in persistent storage, not delivered yet;
+ * once acknowledged, Track keeps it in that outbox through retries and process restarts until a
+ * successful server response removes it transactionally.
+ */
+export function trackIdempotent(
+  eventId: string,
+  event: string,
+  props?: TrackedEventInput['props'],
+  time?: Date,
+): boolean {
+  const normalizedId = eventId.trim().toLowerCase();
+  if (!UUID_PATTERN.test(normalizedId)) return false;
+  return enqueueEvent(normalizedId, event, props, time, true);
+}
+
+function enqueueEvent(
+  eventId: string,
+  event: string,
+  props: TrackedEventInput['props'],
+  time: Date | undefined,
+  requirePersistentAck: boolean,
+): boolean {
+  if (!options || !event) return false;
+  try {
+    if (options.hasConsent?.() === false) {
+      options.onDropped?.(1, 'no-consent');
+      return false;
+    }
+  } catch {
     options.onDropped?.(1, 'no-consent');
-    return;
+    return false;
+  }
+
+  if (requirePersistentAck) {
+    // Probe with the unchanged queue before accepting caller-owned data. This discovers custom
+    // adapters that secretly return a Promise without ever placing the terminal event in Track;
+    // the upstream Links outbox remains the single source of truth.
+    if (!options.storage
+      || !supportsDurableSyncWrites(options.storage)
+      || !persistQueue()) return false;
   }
 
   const flat: Record<string, string> = {};
@@ -144,25 +210,81 @@ export function track(event: string, props?: TrackedEventInput['props'], time?:
     flat[key] = redact.has(key) ? '[REDACTED]' : (typeof value === 'string' ? value : String(value));
   }
 
-  queue.push({ id: randomEventId(), event, time: (time ?? new Date()).toISOString(), props: flat, attempts: 0 });
+  let occurredAt: string;
+  try {
+    occurredAt = (time ?? new Date()).toISOString();
+  } catch {
+    return false;
+  }
 
-  const maxQueue = options.maxQueue ?? DEFAULT_MAX_QUEUE;
-  if (queue.length > maxQueue) {
-    const dropped = queue.length - maxQueue;
-    queue = queue.slice(dropped);
-    options.onDropped?.(dropped, 'queue-full');
+  const existing = queue.find((queued) => queued.id === eventId);
+  if (existing) {
+    const sameLogicalEvent = existing.event === event
+      && existing.time === occurredAt
+      && JSON.stringify(existing.props) === JSON.stringify(flat);
+    if (!sameLogicalEvent) return false;
+    if (requirePersistentAck && existing.durable !== true) {
+      existing.durable = true;
+      if (!persistQueue()) {
+        delete existing.durable;
+        persistQueue();
+        return false;
+      }
+    }
+    return true;
   }
-  persistQueue();
+
+  const queueBeforeDurableEnqueue = requirePersistentAck ? [...queue] : null;
+  queue.push({
+    id: eventId,
+    event,
+    time: occurredAt,
+    props: flat,
+    attempts: 0,
+    ...(requirePersistentAck ? { durable: true as const } : {}),
+  });
+
+  const maxQueue = Math.max(0, options.maxQueue ?? DEFAULT_MAX_QUEUE);
+  let dropped = 0;
+  while (queue.length > maxQueue) {
+    // Never evict a previously acknowledged durable event to make room. When every queued row
+    // is durable, the newest enqueue is refused and its upstream outbox remains authoritative.
+    const bestEffortIndex = queue.findIndex((queued) => queued.durable !== true);
+    if (bestEffortIndex < 0) {
+      // The queue can already exceed a newly lowered max after restart. Refuse only the newest
+      // durable enqueue; previously acknowledged records must still reach the server.
+      const newestIndex = queue.findIndex((queued) => queued.id === eventId);
+      if (newestIndex >= 0) {
+        queue.splice(newestIndex, 1);
+        dropped += 1;
+      }
+      break;
+    }
+    const index = bestEffortIndex;
+    queue.splice(index, 1);
+    dropped += 1;
+  }
+  const retained = queue.some((queued) => queued.id === eventId);
+  const persisted = persistQueue();
+  if (requirePersistentAck && (!retained || !persisted)) {
+    queue = queueBeforeDurableEnqueue ?? queue;
+    // If an adapter revealed itself as asynchronous only on the second write, schedule a
+    // compensating best-effort mirror without the caller-owned event.
+    persistQueue();
+    return false;
+  }
+  if (dropped > 0) options.onDropped?.(dropped, 'queue-full');
 
   if (queue.length >= (options.maxBatch ?? DEFAULT_MAX_BATCH)) void flushEvents();
+  return retained && (!requirePersistentAck || persisted);
 }
 
 /**
  * Send what is queued. Returns how many events the server accepted.
  *
- * Failures put the batch back at the front of the queue rather than dropping it: the
- * usual cause is a network that is about to come back, and the usual moment is right
- * after launch, when the first events of a session are the ones a funnel needs most.
+ * The batch remains in the durable queue while HTTP is in flight and is removed only after a
+ * successful response is also persisted locally. This intentionally permits duplicate replay
+ * after a crash, while a caller-owned event id lets the server/read model deduplicate it.
  */
 export async function flushEvents(): Promise<number> {
   if (!options || sending || queue.length === 0 || Date.now() < nextAttemptAt) return 0;
@@ -170,15 +292,14 @@ export async function flushEvents(): Promise<number> {
   const opts = options;
   const requestGeneration = trackingGeneration;
   const ctx = opts.getContext?.() ?? {};
+  const anonymousInstallation = opts.identityMode === 'anonymous_installation';
 
-  // Without a device id the server cannot put the event in an arm, and an empty id
-  // would pool every such install into one. Held rather than dropped: the id usually
-  // arrives a moment after boot.
-  if (!ctx.deviceId) return 0;
+  // The legacy/default mode intentionally preserves the original experiment-event
+  // contract. Anonymous campaign events opt into a separate identity explicitly.
+  if (!anonymousInstallation && !ctx.deviceId) return 0;
+  const requestDeviceId = anonymousInstallation ? analyticsInstallationId : ctx.deviceId;
 
   const batch = queue.slice(0, opts.maxBatch ?? DEFAULT_MAX_BATCH);
-  queue = queue.slice(batch.length);
-  persistQueue();
   sending = true;
 
   const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
@@ -191,8 +312,10 @@ export async function flushEvents(): Promise<number> {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        deviceId: ctx.deviceId,
-        userId: ctx.userId,
+        deviceId: requestDeviceId,
+        // Anonymous mode deliberately omits the property rather than serializing an
+        // empty identifier. Context mode remains backwards compatible.
+        ...(anonymousInstallation ? {} : { userId: ctx.userId }),
         platform: ctx.platform,
         appVersion: ctx.appVersion,
         events: batch.map((e) => ({ id: e.id, event: e.event, time: e.time, props: e.props })),
@@ -201,11 +324,9 @@ export async function flushEvents(): Promise<number> {
     });
 
     if (!response.ok) {
-      // Rate limited or briefly down: keep the events, try on the next tick.
+      // Rate limited or briefly down: the batch never left the durable queue.
       if (requestGeneration === trackingGeneration && options === opts) {
-        requeueWithBackoff(batch, response.status);
-      } else {
-        restoreStaleBatch(opts, batch, response.status);
+        markBatchForRetry(batch, response.status);
       }
       if (response.status !== 429) opts.onError?.(new Error(`Pulse track failed: ${response.status}`));
       return 0;
@@ -215,11 +336,15 @@ export async function flushEvents(): Promise<number> {
     if (requestGeneration !== trackingGeneration || options !== opts) return body.accepted ?? 0;
     if (body.ignored && body.ignored.length > 0) opts.onIgnored?.(body.ignored);
     nextAttemptAt = 0;
-    persistQueue();
+    if (!acknowledgeBatch(opts, batch)) {
+      // The server may already have accepted the ids. Keep and replay them rather than creating
+      // the loss window between remote ACK and local deletion.
+      nextAttemptAt = Date.now() + retryDelayFor(batch);
+      opts.onError?.(new Error('Pulse track acknowledgement was not persisted'));
+    }
     return body.accepted ?? 0;
   } catch (error) {
-    if (requestGeneration === trackingGeneration && options === opts) requeueWithBackoff(batch);
-    else restoreStaleBatch(opts, batch);
+    if (requestGeneration === trackingGeneration && options === opts) markBatchForRetry(batch);
     opts.onError?.(error);
     return 0;
   } finally {
@@ -257,6 +382,7 @@ export function stopTracking(): void {
   disposeTracking();
   options = null;
   queue = [];
+  analyticsInstallationId = '';
   sending = false;
   nextAttemptAt = 0;
 }
@@ -270,65 +396,128 @@ function startTimer(): void {
   (timer as unknown as { unref?: () => void }).unref?.();
 }
 
-function requeueWithBackoff(batch: QueuedEvent[], status?: number): void {
+function markBatchForRetry(batch: QueuedEvent[], status?: number): void {
   if (!options) return;
   const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-  const retryable: QueuedEvent[] = [];
+  const batchIds = new Set(batch.map((event) => event.id));
   let dropped = 0;
-  for (const event of batch) {
-    const next = { ...event, attempts: event.attempts + 1 };
-    if (next.attempts >= maxAttempts && status !== 429) dropped++;
-    else retryable.push(next);
-  }
-  queue = [...retryable, ...queue];
+  queue = queue.flatMap((event) => {
+    if (!batchIds.has(event.id)) return [event];
+    const next = { ...event, attempts: Math.min(event.attempts + 1, 100_000) };
+    if (next.durable !== true && next.attempts >= maxAttempts && status !== 429) {
+      dropped += 1;
+      return [];
+    }
+    return [next];
+  });
   if (dropped > 0) options.onDropped?.(dropped, 'max-attempts');
-  const attempts = retryable.reduce((max, event) => Math.max(max, event.attempts), 1);
-  const base = Math.min(60_000, 1_000 * 2 ** Math.min(attempts - 1, 6));
-  nextAttemptAt = Date.now() + base + Math.floor(Math.random() * Math.max(1, base / 4));
+  nextAttemptAt = Date.now() + retryDelayFor(batch.map((event) => ({
+    ...event,
+    attempts: Math.min(event.attempts + 1, 100_000),
+  })));
   persistQueue();
 }
 
-/**
- * An old request may fail after another app has been configured. Its rows belong in
- * the old app's outbox, never in the new app's in-memory queue. When the same app was
- * merely reconfigured, merge them back into the live queue so it need not restart to
- * see them; otherwise persist directly under the captured app-scoped key.
- */
-function restoreStaleBatch(opts: TrackOptions, batch: QueuedEvent[], status?: number): void {
-  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-  const retryable: QueuedEvent[] = [];
-  let dropped = 0;
-  for (const event of batch) {
-    const next = { ...event, attempts: event.attempts + 1 };
-    if (next.attempts >= maxAttempts && status !== 429) dropped++;
-    else retryable.push(next);
+function acknowledgeBatch(opts: TrackOptions, batch: QueuedEvent[]): boolean {
+  const acknowledgedIds = new Set(batch.map((event) => event.id));
+  const remaining = queue.filter((event) => !acknowledgedIds.has(event.id));
+  if (!opts.storage) {
+    queue = remaining;
+    return true;
   }
-  if (dropped > 0) opts.onDropped?.(dropped, 'max-attempts');
-  if (retryable.length === 0) return;
-
-  const currentOptions = options;
-  const sameOutbox = currentOptions?.storage === opts.storage &&
-    currentOptions !== null && storageKey(currentOptions) === storageKey(opts);
-  if (sameOutbox) {
-    queue = [...retryable, ...queue].slice(-(options?.maxQueue ?? DEFAULT_MAX_QUEUE));
-    persistQueue();
-    return;
+  const includesDurable = batch.some((event) => event.durable === true);
+  // Never schedule a destructive outbox write through an adapter already known to be async.
+  // The server may have accepted this batch, but retaining it for a deduplicated replay is safer
+  // than losing it during the gap before an asynchronous deletion reaches disk.
+  if (!supportsDurableSyncWrites(opts.storage)) {
+    if (includesDurable) return false;
+    queue = remaining;
+    // Best-effort events keep the historical AsyncStorage behavior: the in-memory batch drains
+    // after 2xx and the mirror may replay after a crash, but it cannot block or resend forever.
+    writeStorageValue(
+      opts.storage,
+      storageKey(opts),
+      JSON.stringify(remaining),
+      opts.onError,
+      true,
+    );
+    return true;
   }
-
-  if (!opts.storage) return;
-  try {
-    const stored = readQueue(opts);
-    const restored = [...retryable, ...stored].slice(-(opts.maxQueue ?? DEFAULT_MAX_QUEUE));
-    opts.storage.set(storageKey(opts), JSON.stringify(restored));
-  } catch {
-    // Best effort only; a telemetry recovery must not affect the new app session.
+  const persisted = writeStorageValue(
+    opts.storage,
+    storageKey(opts),
+    JSON.stringify(remaining),
+    opts.onError,
+    false,
+  );
+  if (!persisted) {
+    if (!includesDurable && !supportsDurableSyncWrites(opts.storage)) {
+      queue = remaining;
+      writeStorageValue(
+        opts.storage,
+        storageKey(opts),
+        JSON.stringify(remaining),
+        opts.onError,
+        true,
+      );
+      return true;
+    }
+    if (!supportsDurableSyncWrites(opts.storage)) {
+      // A conditional thenable may already have scheduled deletion. Immediately schedule the
+      // unchanged durable outbox behind it so a normal ordered async adapter restores the record.
+      writeStorageValue(
+        opts.storage,
+        storageKey(opts),
+        JSON.stringify(queue),
+        opts.onError,
+        true,
+      );
+    }
+    return false;
   }
+  queue = remaining;
+  return true;
+}
+
+function retryDelayFor(batch: QueuedEvent[]): number {
+  const attempts = batch.reduce((max, event) => Math.max(max, event.attempts), 1);
+  const base = Math.min(60_000, 1_000 * 2 ** Math.min(Math.max(attempts - 1, 0), 6));
+  return base + Math.floor(Math.random() * Math.max(1, base / 4));
 }
 
 function storageKey(opts: TrackOptions): string {
   return opts.storageKey?.trim() || DEFAULT_STORAGE_KEY;
 }
 
+function analyticsInstallationIdStorageKey(opts: TrackOptions): string {
+  return `${storageKey(opts)}${ANALYTICS_INSTALLATION_ID_SUFFIX}`;
+}
+
+function resolveAnalyticsInstallationId(opts: TrackOptions): string {
+  if (opts.storage) {
+    try {
+      const stored = opts.storage.getString(analyticsInstallationIdStorageKey(opts))?.trim();
+      if (stored && UUID_PATTERN.test(stored)) return stored.toLowerCase();
+    } catch {
+      // A telemetry identifier can stay memory-only when storage is unavailable.
+    }
+  }
+
+  const generated = randomAnalyticsInstallationId();
+  if (opts.storage) {
+    // This identifier does not acknowledge delivery, so asynchronous best-effort persistence is
+    // acceptable. The helper still observes rejections and marks accidental thenable adapters.
+    writeStorageValue(
+      opts.storage,
+      analyticsInstallationIdStorageKey(opts),
+      generated,
+      opts.onError,
+      true,
+    );
+  }
+  return generated;
+}
+
 function readQueue(opts: TrackOptions): QueuedEvent[] {
   if (!opts.storage) return [];
   try {
@@ -336,27 +525,103 @@ function readQueue(opts: TrackOptions): QueuedEvent[] {
     if (!raw) return [];
     const parsed = JSON.parse(raw) as unknown;
     if (!Array.isArray(parsed)) return [];
-    return parsed.filter((item): item is QueuedEvent => Boolean(
+    const restored = parsed.filter((item): item is QueuedEvent => Boolean(
       item && typeof item === 'object' && typeof item.id === 'string' &&
       typeof item.event === 'string' && typeof item.time === 'string' &&
-      typeof item.props === 'object' && typeof item.attempts === 'number',
-    )).slice(-(opts.maxQueue ?? DEFAULT_MAX_QUEUE));
+      item.props && typeof item.props === 'object' && !Array.isArray(item.props) &&
+      typeof item.attempts === 'number' && Number.isSafeInteger(item.attempts) &&
+      item.attempts >= 0 && item.attempts <= 100_000 &&
+      ((item as QueuedEvent).durable === undefined || (item as QueuedEvent).durable === true),
+    ));
+    const maxQueue = Math.max(0, opts.maxQueue ?? DEFAULT_MAX_QUEUE);
+    if (restored.length <= maxQueue) return restored;
+    const selected = new Set<number>();
+    restored.forEach((event, index) => {
+      if (event.durable === true) selected.add(index);
+    });
+    // A lower max in a later app version may not erase already-ACKed durable rows. Fill any
+    // remaining capacity with the newest best-effort events, retaining original send order.
+    for (let index = restored.length - 1; index >= 0 && selected.size < maxQueue; index -= 1) {
+      if (restored[index]?.durable !== true) selected.add(index);
+    }
+    return restored.filter((_event, index) => selected.has(index));
   } catch {
     return [];
   }
 }
 
-function persistQueue(): void {
-  if (!options?.storage) return;
+function persistQueue(): boolean {
+  if (!options?.storage) return false;
+  // Best-effort track() still mirrors through AsyncStorage, but the return value stays false so
+  // trackIdempotent() cannot claim synchronous durability that the adapter has not provided.
+  return writeStorageValue(
+    options.storage,
+    storageKey(options),
+    JSON.stringify(queue),
+    options.onError,
+    true,
+  );
+}
+
+function supportsDurableSyncWrites(storage: ConfigStorage): boolean {
+  return storage.supportsDurableSyncWrites !== false
+    && !asynchronousStorageAdapters.has(storage as object);
+}
+
+function writeStorageValue(
+  storage: ConfigStorage,
+  key: string,
+  value: string,
+  onError: ((error: unknown) => void) | undefined,
+  allowKnownAsyncBestEffort: boolean,
+): boolean {
+  const declaredOrObservedAsync = !supportsDurableSyncWrites(storage);
+  if (declaredOrObservedAsync && !allowKnownAsyncBestEffort) return false;
   try {
-    options.storage.set(storageKey(options), JSON.stringify(queue));
-  } catch {
-    // Telemetry persistence must never become an app failure.
+    const result = (storage.set as unknown as (storageKey: string, stored: string) => unknown)(key, value);
+    if (isThenable(result)) {
+      asynchronousStorageAdapters.add(storage as object);
+      void Promise.resolve(result).catch((error) => reportStorageError(onError, error));
+      return false;
+    }
+    return !declaredOrObservedAsync;
+  } catch (error) {
+    reportStorageError(onError, error);
+    return false;
   }
 }
 
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+    ? typeof (value as { then?: unknown }).then === 'function'
+    : false;
+}
+
+function reportStorageError(
+  onError: ((error: unknown) => void) | undefined,
+  error: unknown,
+): void {
+  try { onError?.(error); } catch { /* telemetry diagnostics never become an app failure */ }
+}
+
 function randomEventId(): string {
   const cryptoLike = globalThis.crypto as { randomUUID?: () => string } | undefined;
   if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();
   return `evt-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
 }
+
+function randomAnalyticsInstallationId(): string {
+  const cryptoLike = globalThis.crypto as {
+    randomUUID?: () => string;
+    getRandomValues?: (values: Uint8Array) => Uint8Array;
+  } | undefined;
+  if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID().toLowerCase();
+
+  const bytes = new Uint8Array(16);
+  if (typeof cryptoLike?.getRandomValues === 'function') cryptoLike.getRandomValues(bytes);
+  else for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (value) => value.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}