@loro-dev/streams-crdt 0.8.2 → 0.8.4

package/README.md

@@ -37,19 +37,28 @@ if (!result.ok) {
   // result.error is a TransportError with a discriminated `code` field.
   switch (result.error.code) {
     case "stream_not_found":
-      // The stream doesn't exist yet — create it first.
+      // 404 — the stream doesn't exist yet. Create it first.
       break;
     case "auth_failed":
-      // Token expired or unauthorized.
+      // 401/403 from the server — refresh credentials and retry.
       break;
-    case "protocol_error":
-    case "internal_error":
-      // Non-retryable: bad server response or local runtime/adapter failure.
+    case "auth_provider_error":
+      // Your auth callback threw. The live loop will retry automatically.
+      // For permanent logout, return undefined from the callback instead.
+      break;
+    case "server_error":
+      // 5xx — transient backend failure. The live loop retries automatically;
+      // for one-shot calls (sync/createStream/etc.) you decide whether to
+      // retry. `retryAfterMs` honors the server's Retry-After hint.
       break;
     case "network_error":
     case "timeout":
       // Transient — safe to retry.
       break;
+    case "protocol_error":
+    case "internal_error":
+      // Non-retryable: bad server response or local runtime/adapter failure.
+      break;
     default:
       console.error("transport error:", result.error);
   }
@@ -68,11 +77,73 @@ if (!result.ok && result.error.retryable) {
 }
 ```
 
+#### Surfacing errors to end users
+
+HTTP-derived variants (`server_error`, `auth_failed`, `protocol_error`,
+`stream_not_found`, `gone`) carry the response details so apps can show
+actionable messages without parsing the `message` string:
+
+```ts
+const err = result.error;
+if (err.code === "server_error") {
+  toast.error(`Server error ${err.status}${err.requestId ? ` (req: ${err.requestId})` : ""}`);
+  console.error("backend body:", err.body);
+  // err.retryAfterMs may suggest a backoff if the server set Retry-After.
+}
+```
+
+| Code                   | `status` | `message` | `body` | Other                          |
+| ---------------------- | -------- | --------- | ------ | ------------------------------ |
+| `stream_not_found`     | 404      | yes       | yes    | —                              |
+| `auth_failed`          | 401/403  | yes       | yes    | —                              |
+| `protocol_error`       | yes      | yes       | yes    | —                              |
+| `gone`                 | 410      | yes       | yes    | —                              |
+| `server_error`         | 5xx      | yes       | yes    | `requestId?`, `retryAfterMs?`  |
+| `timeout`              | —        | yes       | —      | `phase: "connect" \| "poll"`   |
+| `network_error`        | —        | yes       | —      | —                              |
+| `auth_provider_error`  | —        | yes       | —      | `cause?` (original thrown value) |
+| `internal_error`       | —        | yes       | —      | —                              |
+| `apply_incomplete`     | —        | yes       | —      | `reason: "loro_pending_updates"` |
+
+#### Operation-level retries vs. live-mode retries
+
+- `sync()`, `createStream()`, `deleteStream()`, `appendWriteOnly()` return
+  after a **single** attempt. The application is responsible for retrying
+  `retryable` errors.
+- After `join()` succeeds, the live read/write loops automatically reconnect
+  on every `retryable: true` error using exponential backoff
+  (`[0, 0.5s, 1s, 2s, 4s, 8s, 15s, 30s]` with ±20% jitter; cap 30s). When a
+  5xx response includes `Retry-After`, the runtime waits at least that long.
+  Non-retryable errors transition the subscription to `status: "error"`;
+  call `transport.rejoin()` after fixing the cause (e.g., refreshing the auth
+  token) to reset retry state and reconnect.
+
 > **Why `Result` instead of `throw`?** Transport failures (network errors,
 > auth expiry, missing streams) are expected at runtime, not exceptional.
 > Wrapping them in `Result` makes the error path explicit in the type system
 > so callers cannot accidentally ignore failures with a missing `try/catch`.
 
+#### Migration notes
+
+For most callers nothing changes — `if (!result.ok) { handle(result.error); }`
+keeps working, and `result.error.retryable` is still the right gate for
+"safe to retry?".
+
+Only adjust if any of these apply:
+
+- **Your auth callback throws on permanent failure** (e.g., user is logged
+  out). Throwing is now treated as a transient error and retried in live
+  mode. **Return `undefined` instead** so the server returns 401 and you get
+  the terminal `auth_failed`. See "What if the auth callback throws?" below.
+- **You construct `TransportError` literals** (e.g., in tests or fixtures).
+  `stream_not_found` now requires `status: 404` + `message`; `gone` now
+  requires `status: 410`. TypeScript will flag these.
+- **You exhaustively switch on `code` with a `: never` default.** Add a case
+  for `auth_provider_error` (and optionally `server_error` if you handled
+  5xx via `unknown`/`internal_error` before).
+- **You used `"message" in error` to defensively narrow.** All variants now
+  carry `message`; the guard is no longer needed.
+
 ## Quick Start (Loro)
 
 ```ts
@@ -324,6 +395,32 @@ const transport = new StreamsCrdt({
 If your callback already returns a fresh token every time, you can ignore the
 `context` argument.
 
+### What if the auth callback throws?
+
+Throwing from the callback is treated as a **transient** failure. The runtime
+wraps the error as `auth_provider_error` (`retryable: true`) so a hiccupping
+auth backend doesn't terminate the live read/write loops — they retry under
+the same exponential backoff used for `server_error` and `network_error`.
+
+For the "user is permanently logged out" case, **return `undefined`** (or
+`null`/empty string) instead of throwing. The request goes out without an
+`Authorization` header, the server returns 401, and you receive the
+non-retryable `auth_failed` instead — which the application typically routes
+to a sign-in page.
+
+```ts
+auth: async () => {
+  try {
+    return await fetchTokenFromAuthBackend(); // network → throw → retry
+  } catch (e) {
+    if (isPermanentLogoutError(e)) {
+      return undefined; // → server 401 → auth_failed (terminal)
+    }
+    throw e; // → auth_provider_error (retryable)
+  }
+}
+```
+
 ## End-to-End Encryption (E2EE)
 
 `e2ee` enables end-to-end encryption for CRDT update batches and snapshots

package/dist/flock.d.ts

@@ -1,4 +1,4 @@
-import { $ as IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-Bi5rAZfP.js";
+import { $ as IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-JuJ1JqCX.js";
 import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 } from "@loro-dev/flock-wasm";
 
 //#region src/flock.d.ts

package/dist/flock.js

@@ -1,4 +1,4 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-BjmGvObf.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-BBE3LRAQ.js";
 import { Flock } from "@loro-dev/flock-wasm";
 //#region src/flock.ts
 function isAfter(entry, current) {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-Bi5rAZfP.js";
+import { $ as IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-JuJ1JqCX.js";
 export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-BjmGvObf.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-BBE3LRAQ.js";
 export { PayloadProtectionError as E2eeError, PayloadProtectionError, EphemeralStreamCrdt, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, StreamsCrdt, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/loro.d.ts

@@ -1,4 +1,4 @@
-import { $ as IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-Bi5rAZfP.js";
+import { $ as IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-JuJ1JqCX.js";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/loro.d.ts

package/dist/loro.js

@@ -1,4 +1,4 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-BjmGvObf.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-BBE3LRAQ.js";
 import { LoroDoc, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 //#region src/loro.ts
 function batchImportUpdates(doc, updates) {

package/dist/{stream-id-BjmGvObf.js → stream-id-BBE3LRAQ.js}

@@ -129,7 +129,8 @@ const DEFAULT_RECONNECT_CONFIG = {
 		2e3,
 		4e3,
 		8e3,
-		15e3
+		15e3,
+		3e4
 	],
 	jitterFraction: .2,
 	maxAttempts: Infinity,
@@ -149,11 +150,15 @@ function applyJitter(baseMs, fraction) {
 /**
 * Compute the retry delay for a given attempt number.
 * Uses the delays table from config, clamping at the last entry.
+*
+* If `minDelayMs` is provided (e.g. from a Retry-After hint), the result is
+* clamped to be at least that value before jitter, so honoring the server's
+* backoff request never falls below what we'd already wait.
 */
-function computeRetryDelay(attempt, config = DEFAULT_RECONNECT_CONFIG) {
+function computeRetryDelay(attempt, config = DEFAULT_RECONNECT_CONFIG, minDelayMs) {
 	const { delays, jitterFraction } = config;
-	const base = delays[Math.min(attempt, delays.length - 1)];
-	return applyJitter(base, jitterFraction);
+	const scheduled = delays[Math.min(attempt, delays.length - 1)];
+	return applyJitter(typeof minDelayMs === "number" && minDelayMs > scheduled ? minDelayMs : scheduled, jitterFraction);
 }
 //#endregion
 //#region src/items.ts
@@ -477,9 +482,16 @@ function createProducerId() {
 }
 var HttpError = class extends Error {
 	status;
-	constructor(message, status) {
+	requestId;
+	retryAfterMs;
+	/** Raw response body text, when readable. Empty bodies are stored as undefined. */
+	body;
+	constructor(message, status, options) {
 		super(message);
 		this.status = status;
+		if (options?.requestId !== void 0) this.requestId = options.requestId;
+		if (options?.retryAfterMs !== void 0) this.retryAfterMs = options.retryAfterMs;
+		if (options?.body !== void 0 && options.body.length > 0) this.body = options.body;
 	}
 };
 var TimeoutError = class extends Error {
@@ -498,6 +510,22 @@ var ProtocolError = class extends Error {
 		this.status = status;
 	}
 };
+/**
+* Wraps any error thrown by a user-supplied auth provider callback.
+*
+* The runtime treats these as retryable so transient credential-fetch failures
+* (e.g. a hiccupping auth backend) do not terminate the live read/write loops.
+* For permanent "user is logged out" cases, the auth provider should return
+* `undefined` instead of throwing — that lets the request go out without an
+* `Authorization` header so the server returns a real 401 (`auth_failed`).
+*/
+var AuthProviderError = class extends Error {
+	cause;
+	constructor(message, options) {
+		super(message);
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
 function isObject(value) {
 	return typeof value === "object" && value != null;
 }
@@ -603,6 +631,12 @@ function classifyFetchError(err) {
 		retriable: true,
 		atMs: Date.now()
 	};
+	if (err instanceof AuthProviderError) return {
+		code: "auth_provider",
+		message,
+		retriable: true,
+		atMs: Date.now()
+	};
 	if (status === 401 || status === 403) return {
 		code: "auth_failed",
 		message,
@@ -621,6 +655,12 @@ function classifyFetchError(err) {
 		retriable: false,
 		atMs: Date.now()
 	};
+	if (typeof status === "number" && status >= 500 && status < 600) return {
+		code: "server",
+		message,
+		retriable: true,
+		atMs: Date.now()
+	};
 	if (err instanceof ProtocolError) return {
 		code: "protocol",
 		message,
@@ -662,15 +702,28 @@ function toTransportError(error) {
 		reason: "loro_pending_updates",
 		message: error instanceof Error ? error.message : String(error)
 	};
-	if (isStreamNotFoundError(error)) return {
-		code: "stream_not_found",
-		retryable: false
+	if (error instanceof AuthProviderError) return {
+		code: "auth_provider_error",
+		retryable: true,
+		message: error.message,
+		...error.cause !== void 0 && { cause: error.cause }
 	};
+	if (isStreamNotFoundError(error)) {
+		const httpError = error;
+		return {
+			code: "stream_not_found",
+			retryable: false,
+			status: 404,
+			message: httpError.message,
+			...httpError.body !== void 0 && { body: httpError.body }
+		};
+	}
 	if (error instanceof HttpError && (error.status === 401 || error.status === 403)) return {
 		code: "auth_failed",
 		retryable: false,
 		status: error.status,
-		message: error.message
+		message: error.message,
+		...error.body !== void 0 && { body: error.body }
 	};
 	if (error instanceof HttpError && [
 		400,
@@ -680,7 +733,8 @@ function toTransportError(error) {
 		code: "protocol_error",
 		retryable: false,
 		status: error.status,
-		message: error.message
+		message: error.message,
+		...error.body !== void 0 && { body: error.body }
 	};
 	if (error instanceof ProtocolError) return {
 		code: "protocol_error",
@@ -697,7 +751,18 @@ function toTransportError(error) {
 	if (error instanceof HttpError && error.status === 410) return {
 		code: "gone",
 		retryable: true,
-		message: error.message
+		status: 410,
+		message: error.message,
+		...error.body !== void 0 && { body: error.body }
+	};
+	if (error instanceof HttpError && error.status >= 500 && error.status < 600) return {
+		code: "server_error",
+		retryable: true,
+		status: error.status,
+		message: error.message,
+		...error.body !== void 0 && { body: error.body },
+		...error.requestId !== void 0 && { requestId: error.requestId },
+		...error.retryAfterMs !== void 0 && { retryAfterMs: error.retryAfterMs }
 	};
 	if (isPayloadProtectionError(error)) return {
 		code: "payload_protection_error",
@@ -744,7 +809,13 @@ function normalizeAuthProvider(auth) {
 		return async () => token.length === 0 ? void 0 : token;
 	}
 	return async (context) => {
-		const token = (await auth(context))?.trim() ?? "";
+		let value;
+		try {
+			value = await auth(context);
+		} catch (cause) {
+			throw new AuthProviderError(cause instanceof Error ? cause.message : `auth provider threw: ${String(cause)}`, { cause });
+		}
+		const token = value?.trim() ?? "";
 		return token.length === 0 ? void 0 : token;
 	};
 }
@@ -1073,8 +1144,12 @@ var StreamsTransportClient = class {
 		return headers;
 	}
 	async responseToEphemeralFailure(response, context) {
-		const message = await response.text().catch(() => "");
-		return new HttpError(message.length > 0 ? `${context} failed: ${message}` : `${context} failed with status ${response.status}`, response.status);
+		const bodyText = await response.text().catch(() => "");
+		return new HttpError(bodyText.length > 0 ? `${context} failed: ${bodyText}` : `${context} failed with status ${response.status}`, response.status, {
+			requestId: extractRequestIdFromResponseHeaders(response.headers),
+			retryAfterMs: parseRetryAfterMs(response.headers.get("retry-after") ?? void 0),
+			body: bodyText.length > 0 ? bodyText : void 0
+		});
 	}
 	ephemeralReadEndpoint() {
 		const target = new URL(this.streamUrl);
@@ -1089,12 +1164,16 @@ var StreamsTransportClient = class {
 			case "not_found":
 			case "conflict":
 			case "gone":
-			case "rate_limited": return new HttpError(error.message, error.status);
+			case "rate_limited": return new HttpError(error.message, error.status, { body: error.bodyText });
 			case "timeout": return new TimeoutError(error.phase, error.phase === "poll" ? this.reconnectConfig.pollTimeoutMs : this.reconnectConfig.connectTimeoutMs);
 			case "network_error": return error.cause instanceof TypeError ? error.cause : new TypeError(error.message);
 			case "protocol_error": return new ProtocolError(error.message, error.status);
 			case "unknown":
-				if (typeof error.status === "number") return new HttpError(error.message, error.status);
+				if (typeof error.status === "number") return new HttpError(error.message, error.status, {
+					requestId: extractRequestIdFromHeaders(error.headers),
+					retryAfterMs: parseRetryAfterMs(error.headers?.["retry-after"]),
+					body: error.bodyText
+				});
 				if (error.cause instanceof TypeError) return error.cause;
 				if (error.cause instanceof Error) return error.cause;
 				return new Error(error.message);
@@ -1207,6 +1286,41 @@ var StreamsTransportClient = class {
 		};
 	}
 };
+const REQUEST_ID_HEADER_NAMES = [
+	"x-request-id",
+	"x-amzn-trace-id",
+	"cf-ray",
+	"x-trace-id"
+];
+function extractRequestIdFromHeaders(headers) {
+	if (headers == null) return;
+	const lowerCased = {};
+	for (const [key, value] of Object.entries(headers)) lowerCased[key.toLowerCase()] = value;
+	for (const name of REQUEST_ID_HEADER_NAMES) {
+		const value = lowerCased[name];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+function extractRequestIdFromResponseHeaders(headers) {
+	for (const name of REQUEST_ID_HEADER_NAMES) {
+		const value = headers.get(name);
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+function parseRetryAfterMs(value) {
+	if (value == null) return;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return;
+	const numeric = Number(trimmed);
+	if (Number.isFinite(numeric)) {
+		if (numeric < 0) return;
+		return Math.round(numeric * 1e3);
+	}
+	const parsed = Date.parse(trimmed);
+	if (Number.isNaN(parsed)) return;
+	const delta = parsed - Date.now();
+	return delta > 0 ? delta : void 0;
+}
 //#endregion
 //#region src/ephemeral-runtime.ts
 function createNoopAdapter() {
@@ -3060,7 +3174,7 @@ var StreamsCrdt = class StreamsCrdt {
 					this.setReadSubStatus(state, "disconnected");
 					return;
 				}
-				const delay = computeRetryDelay(state.retryAttempt, this.reconnectConfig);
+				const delay = computeRetryDelay(state.retryAttempt, this.reconnectConfig, error instanceof HttpError ? error.retryAfterMs : void 0);
 				state.retryAttempt += 1;
 				await sleep(delay, state.retrySleepController.signal);
 			}
@@ -3146,7 +3260,7 @@ var StreamsCrdt = class StreamsCrdt {
 						return;
 					}
 					this.setWriteSubStatus(state, "reconnecting");
-					const delay = computeRetryDelay(attempts, this.reconnectConfig);
+					const delay = computeRetryDelay(attempts, this.reconnectConfig, error instanceof HttpError ? error.retryAfterMs : void 0);
 					attempts += 1;
 					await sleep(delay, state.retrySleepController.signal);
 				}
@@ -3278,4 +3392,4 @@ function createStreamUrl(input) {
 //#endregion
 export { InMemoryRemoteCursorStore as a, EphemeralStreamCrdt as c, StreamsCrdt as i, PayloadProtectionError as l, isValidBucketId as n, IndexedDbRemoteCursorStore as o, isValidRillId as r, createInitialRemoteCursor as s, createStreamUrl as t };
 
-//# sourceMappingURL=stream-id-BjmGvObf.js.map
+//# sourceMappingURL=stream-id-BBE3LRAQ.js.map