@loro-dev/streams-crdt 0.8.2 → 0.8.4

package/dist/{stream-id-Bi5rAZfP.d.ts → stream-id-JuJ1JqCX.d.ts}

@@ -168,50 +168,154 @@ type Result<T, E> = {
  */
 type TransportRoomStatus = "joined" | "reconnecting" | "disconnected" | "error";
 /**
- * Discriminated error union for `createStream()`, `deleteStream()`, `sync()`, and `join()`.
+ * Discriminated error union for `createStream()`, `deleteStream()`, `sync()`,
+ * `join()`, and `appendWriteOnly()`.
  *
- * - `stream_not_found` — the target stream does not exist (404).
- * - `auth_failed` — the auth token was rejected (401/403).
- * - `protocol_error` — unexpected server response or framing error.
- * - `network_error` — fetch-level failure (DNS, connection refused, etc.).
- * - `timeout` — connect or poll deadline exceeded.
- * - `gone` — the server indicated the stream was deleted or moved (410).
+ * Every variant has a `code` discriminator and a `retryable: boolean`. Variants
+ * that originate from an HTTP response also carry `status`, `message`, and
+ * (when the server sent one) the raw response `body` so applications can
+ * surface backend diagnostics directly to end users.
+ *
+ * Codes:
+ * - `stream_not_found` — 404; the target stream does not exist. Create it first.
+ * - `auth_failed` — 401/403 from the server; refresh the token and retry.
+ * - `auth_provider_error` — the user-supplied auth callback threw. Treated
+ *   as transient (retryable) so a hiccupping auth backend doesn't terminate
+ *   live mode. For permanent missing-credential cases, return `undefined`
+ *   from your auth callback instead of throwing.
+ * - `protocol_error` — 400/405/409 or malformed response; treat as a bug.
+ * - `network_error` — fetch-level failure (DNS, connection refused). Retry.
+ * - `timeout` — connect or poll deadline exceeded. Retry.
+ * - `gone` — 410; persisted cursor is no longer valid. Bootstrap from scratch.
  * - `apply_incomplete` — a CRDT adapter could not fully apply remote data.
- * - `internal_error` — adapter or runtime logic failed locally.
- * - `unknown` — catch-all for unexpected errors.
+ * - `server_error` — 5xx; transient backend failure, retry with backoff.
+ * - `internal_error` — local adapter/runtime failure (not from the network).
+ * - `unknown` — uncategorized error.
+ * - `payload_protection_error` — payload encryption/decryption failed.
+ *
+ * In live mode, `join()`'s read/write loops automatically retry every
+ * `retryable: true` error using the configured backoff. Operation-level methods
+ * (`sync()`, `createStream()`, `appendWriteOnly()`) return after a single
+ * attempt — applications decide whether to retry based on the `retryable`
+ * flag.
+ */
+type TransportError =
+/**
+ * The target stream does not exist on the server. Use
+ * `transport.createStream()` to create it (or pass `createIfMissing: true`
+ * to `sync()`).
  */
-type TransportError = {
+{
   readonly code: "stream_not_found";
   readonly retryable: false;
-} | {
+  readonly status: 404;
+  readonly message: string; /** Raw HTTP response body, when readable. */
+  readonly body?: string;
+}
+/**
+ * The auth token was rejected by the server. Refresh credentials and call
+ * the operation again — `retryable` is false because retrying with the same
+ * token will keep failing.
+ */
+| {
   readonly code: "auth_failed";
   readonly retryable: false;
   readonly status?: 401 | 403;
   readonly message: string;
-} | {
+  readonly body?: string;
+}
+/**
+ * The user-supplied auth callback threw. Treated as transient because the
+ * callback typically fetches a token from a backend that may flake. The
+ * live read/write loops retry these automatically. `cause` is the original
+ * thrown value — surface its message to logs but treat the failure as
+ * retryable from the runtime's point of view.
+ *
+ * For "user is permanently logged out" cases, return `undefined` from the
+ * auth callback instead of throwing — that lets the request go out with
+ * no `Authorization` header and the server returns a real 401
+ * (`auth_failed`, retryable: false).
+ */
+| {
+  readonly code: "auth_provider_error";
+  readonly retryable: true;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+/**
+ * The server rejected the request (400/405/409) or sent a malformed
+ * response. Indicates a client/server contract bug; do not retry blindly.
+ */
+| {
   readonly code: "protocol_error";
   readonly retryable: false;
   readonly status?: number;
   readonly message: string;
-} | {
+  readonly body?: string;
+}
+/**
+ * A `fetch` failure (DNS, connection refused, TLS error, etc.). Safe to
+ * retry after a short delay.
+ */
+| {
   readonly code: "network_error";
   readonly retryable: true;
   readonly message: string;
-} | {
+}
+/**
+ * A connect or poll deadline was exceeded. `phase` indicates which one.
+ * Safe to retry.
+ */
+| {
   readonly code: "timeout";
   readonly retryable: true;
   readonly phase: "connect" | "poll";
   readonly message: string;
-} | {
+}
+/**
+ * The server indicated the persisted cursor is no longer valid (410). The
+ * runtime will bootstrap from scratch on the next `join()`/`sync()` —
+ * surface this to the user only if you maintain your own retry loop.
+ */
+| {
   readonly code: "gone";
   readonly retryable: true;
+  readonly status: 410;
   readonly message: string;
-} | {
+  readonly body?: string;
+}
+/**
+ * The CRDT adapter could not fully apply remote updates due to missing
+ * dependencies. The runtime keeps the partial state and will catch up once
+ * the missing updates arrive.
+ */
+| {
   readonly code: "apply_incomplete";
   readonly retryable: true;
   readonly reason: "loro_pending_updates";
   readonly message: string;
-} | {
+}
+/**
+ * A 5xx response from the backend. Likely transient — the live read/write
+ * loops retry automatically with exponential backoff (default cap 30s, with
+ * jitter). When the server provides a `Retry-After` header, the runtime
+ * honors it. `requestId` (when present) is suitable for surfacing to end
+ * users for support tickets.
+ */
+| {
+  readonly code: "server_error";
+  readonly retryable: true;
+  readonly status: number;
+  readonly message: string; /** Raw HTTP response body, when readable. */
+  readonly body?: string; /** Request id extracted from headers like `x-request-id`, `cf-ray`, etc. */
+  readonly requestId?: string; /** Server-suggested backoff in milliseconds, parsed from `Retry-After`. */
+  readonly retryAfterMs?: number;
+}
+/**
+ * The CRDT adapter or local runtime threw an unexpected error (not a
+ * network failure). Indicates a bug; not retried automatically.
+ */
+| {
   readonly code: "internal_error";
   readonly retryable: false;
   readonly message: string;
@@ -874,4 +978,4 @@ declare function createStreamUrl(input: {
 }): string;
 //#endregion
 export { IndexedDbRemoteCursorStoreOptions as $, PayloadProtectionReadPolicy as A, TransportCreateStreamSuccess as B, IsolatedCrdtAdapter as C, PayloadProtectionKey as D, PayloadProtectionEncryptionOptions as E, SnapshotTransformHook as F, TransportSnapshotUploadSuccess as G, TransportError as H, SnapshotUploadOptions as I, WriteOnlyAppendResult as J, TransportSubscription as K, StreamsAuthContext as L, PayloadProtectionWritePolicy as M, Result as N, PayloadProtectionKeyProvider as O, SnapshotCodec as P, IndexedDbRemoteCursorStore as Q, StreamsAuthProvider as R, EphemeralStreamSubscription as S, JsonValue as T, TransportJoinParams as U, TransportDeleteStreamSuccess as V, TransportRoomStatus as W, BeforeRemoteCursorSaveHook as X, BeforeRemoteCursorSaveContext as Y, InMemoryRemoteCursorStore as Z, E2eeScope as _, EphemeralStreamCrdt as a, EphemeralStreamCrdtOptions as b, CrdtApplyOutcome as c, CrdtUpdateBatch as d, RemoteCursor as et, E2eeEncryptionOptions as f, E2eeReadPolicy as g, E2eeOptions as h, PayloadProtectionError as i, PayloadProtectionScope as j, PayloadProtectionOptions as k, CrdtApplyReturn as l, E2eeKeyProvider as m, isValidBucketId as n, RemoteCursorStore as nt, StreamsCrdt as o, E2eeKey as p, TransportSyncSuccess as q, isValidRillId as r, createInitialRemoteCursor as rt, CrdtAdapter as s, createStreamUrl as t, RemoteCursorSaveSource as tt, CrdtUnresolvedSpan as u, E2eeWritePolicy as v, JsonObject as w, EphemeralStreamJoinParams as x, EphemeralStreamAdaptor as y, StreamsCrdtOptions as z };
-//# sourceMappingURL=stream-id-Bi5rAZfP.d.ts.map
+//# sourceMappingURL=stream-id-JuJ1JqCX.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loro-dev/streams-crdt",
   "description": "Transport/runtime layer for synchronizing CRDT state over Durable Streams.",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "license": "MIT",
   "author": "Loro Team",
   "homepage": "https://streams.loro.dev",
@@ -50,10 +50,10 @@
     }
   },
   "dependencies": {
-    "@loro-dev/streams-client": "0.5.0"
+    "@loro-dev/streams-client": "0.5.1"
   },
   "peerDependencies": {
-    "@loro-dev/flock-wasm": "^0.2.0",
+    "@loro-dev/flock-wasm": "^0.3.0",
     "loro-crdt": "^1.10.3"
   },
   "peerDependenciesMeta": {
@@ -66,7 +66,7 @@
   },
   "devDependencies": {
     "@bokuweb/zstd-wasm": "^0.0.27",
-    "@loro-dev/flock-wasm": "^0.2.0",
+    "@loro-dev/flock-wasm": "^0.3.0",
     "fake-indexeddb": "^6.2.5",
     "loro-crdt": "^1.10.3",
     "tsdown": "^0.21.4",