@loro-dev/streams-crdt 0.6.0 → 0.7.0

package/dist/{stream-id-Do4h2lOD.d.ts → stream-id-CS7SzuLW.d.ts}

@@ -109,6 +109,8 @@ interface ReconnectConfig {
   readonly maxAttempts: number;
   readonly connectTimeoutMs: number;
   readonly pollTimeoutMs: number;
+  /** SSE inactivity timeout. Aborts and reconnects if no event arrives within this period. */
+  readonly liveInactivityTimeoutMs?: number;
 }
 //#endregion
 //#region src/types.d.ts
@@ -211,7 +213,21 @@ type TransportError = {
   readonly code: "unknown";
   readonly retryable: false;
   readonly message: string;
+} | {
+  readonly code: "payload_protection_error";
+  readonly retryable: false;
+  readonly reason: "plaintext_forbidden" | "missing_read_key" | "decrypt_failed" | "invalid_envelope" | "wrong_payload_kind" | "encrypt_failed";
+  readonly keyId?: string;
+  readonly message: string;
 };
+interface WriteOnlyAppendResult<TVersion extends JsonObject> {
+  /** Whether this call found and appended local CRDT updates. */
+  readonly appended: boolean;
+  /** Server tail offset returned by the append request. Omitted when `appended` is false. */
+  readonly nextOffset?: string;
+  /** Local CRDT version exported by this runtime's append-only path. */
+  readonly localVersion: TVersion;
+}
 /**
  * Result payload returned by `createStream()`.
  */
@@ -230,6 +246,13 @@ interface TransportDeleteStreamSuccess {
 interface TransportSyncSuccess<TVersion extends JsonObject = JsonObject> {
   readonly cursor: RemoteCursor<TVersion>;
 }
+/**
+ * Result payload returned by the internal snapshot upload test hook.
+ */
+interface TransportSnapshotUploadSuccess {
+  readonly snapshotOffset: string;
+  readonly snapshotByteLength: number;
+}
 /**
  * Optional parameters for a `join()` call.
  *
@@ -280,6 +303,54 @@ interface SnapshotCodec {
   readonly compress: SnapshotTransformHook;
   readonly decompress: SnapshotTransformHook;
 }
+type PayloadProtectionReadPolicy = "encrypted-only" | "allow-plaintext";
+type PayloadProtectionWritePolicy = "encrypt" | "plaintext";
+type PayloadProtectionScope = string | {
+  readonly bucketId: string;
+  readonly streamId: string;
+};
+interface PayloadProtectionKey {
+  readonly id: string;
+  readonly key: CryptoKey | Uint8Array;
+}
+type PayloadProtectionKeyProvider = () => MaybePromise<readonly PayloadProtectionKey[]>;
+interface PayloadProtectionEncryptionOptions {
+  /**
+   * Stable encryption context authenticated with every encrypted payload.
+   *
+   * Prefer bucket/stream identity or an application-stable string. Do not use
+   * a full gateway URL unless old encrypted bytes should become unreadable
+   * after host/proxy migration.
+   */
+  readonly scope: PayloadProtectionScope;
+  /** Key used for new encrypted writes. Required when writePolicy is "encrypt". */
+  readonly writeKey?: PayloadProtectionKey;
+  /**
+   * Keys accepted for remote encrypted reads.
+   *
+   * When omitted, `writeKey` is also used as the only read key.
+   */
+  readonly readKeys?: readonly PayloadProtectionKey[] | PayloadProtectionKeyProvider;
+}
+interface PayloadProtectionOptions {
+  /**
+   * Remote plaintext policy. Defaults to "encrypted-only" when
+   * E2EE is provided.
+   */
+  readonly readPolicy?: PayloadProtectionReadPolicy;
+  /**
+   * Local write policy. Defaults to "encrypt" when E2EE is provided.
+   */
+  readonly writePolicy?: PayloadProtectionWritePolicy;
+  readonly encryption?: PayloadProtectionEncryptionOptions;
+}
+type E2eeReadPolicy = PayloadProtectionReadPolicy;
+type E2eeWritePolicy = PayloadProtectionWritePolicy;
+type E2eeScope = PayloadProtectionScope;
+type E2eeKey = PayloadProtectionKey;
+type E2eeKeyProvider = PayloadProtectionKeyProvider;
+type E2eeEncryptionOptions = PayloadProtectionEncryptionOptions;
+type E2eeOptions = PayloadProtectionOptions;
 /**
  * Active live subscription returned by `join()`.
  *
@@ -293,6 +364,14 @@ interface TransportSubscription {
   readonly connected: boolean;
   /** Current room status. */
   readonly status: TransportRoomStatus;
+  /**
+   * The last transport error observed, if any.
+   *
+   * Updated when the room transitions to `"error"` or `"disconnected"`.
+   * Cleared on successful recovery. Callers can inspect this to decide
+   * whether to retry, surface auth failure, or mark the room as terminal.
+   */
+  readonly lastError?: TransportError;
   /** Registers a status listener. Returns an unsubscribe function. */
   readonly onStatusChange: (listener: (status: "connecting" | TransportRoomStatus) => void) => () => void;
   /**
@@ -307,6 +386,9 @@ interface TransportSubscription {
    *
    * The promise rejects if the flush encounters a non-recoverable error or
    * all subscriptions are closed before all pending changes are confirmed.
+   *
+   * If the initial join sync has failed and not yet recovered, the promise
+   * rejects immediately with a structured error indicating the failure.
    */
   readonly waitUntilSynced: () => Promise<void>;
 }
@@ -435,6 +517,16 @@ interface StreamsCrdtOptions<TVersion extends JsonObject> {
    * the server.
    */
   readonly snapshotCodec?: SnapshotCodec;
+  /**
+   * E2EE and mixed encrypted/plaintext payload behavior.
+   */
+  readonly e2ee?: E2eeOptions;
+  /**
+   * Deprecated alias for `e2ee`.
+   *
+   * Prefer `e2ee`. Passing both `e2ee` and `payloadProtection` is an error.
+   */
+  readonly payloadProtection?: PayloadProtectionOptions;
   readonly snapshotUpload?: SnapshotUploadOptions;
   readonly reconnectConfig?: Partial<ReconnectConfig>;
   readonly debug?: boolean;
@@ -443,9 +535,25 @@ interface StreamsCrdtLike<TVersion extends JsonObject> {
   createStream(): Promise<Result<TransportCreateStreamSuccess, TransportError>>;
   deleteStream(): Promise<Result<TransportDeleteStreamSuccess, TransportError>>;
   sync(): Promise<Result<TransportSyncSuccess<TVersion>, TransportError>>;
+  /**
+   * Appends only locally observed batches without reading remote state first.
+   *
+   * This is the write-only path for actors that may POST but may not bootstrap,
+   * catch up, or join live reads. It must not be mixed with `sync()`/`join()`
+   * on the same instance, and `close()` permanently disables it for that
+   * instance.
+   */
+  appendWriteOnly(): Promise<Result<WriteOnlyAppendResult<TVersion>, TransportError>>;
   join(params?: TransportJoinParams): Promise<Result<TransportSubscription, TransportError>>;
   /** Resets retry state and immediately attempts to reconnect all rooms. */
   rejoin(): void;
+  /**
+   * Closes the active join and releases transport-owned resources.
+   *
+   * If this instance was using `appendWriteOnly()`, closing also tears down the
+   * write-only subscription. Create a new instance to use the write-only path
+   * again later.
+   */
   close(): Promise<void>;
   getSnapshotOffset(): Promise<Result<string | null, TransportError>>;
   readonly streamUrl: string;
@@ -466,6 +574,10 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   private readonly cursorManager;
   private readonly volatileCursorManager;
   private readonly decodeSnapshot?;
+  private readonly encodeSnapshot?;
+  private readonly decodeUpdateItems?;
+  private readonly encodeUpdateItems?;
+  private readonly measureUpdateItemsByteLength?;
   private readonly reconnectConfig;
   private readonly debug;
   private readonly beforeRemoteCursorSave?;
@@ -473,6 +585,10 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   private readonly producerId;
   private producerEpoch;
   private nextProducerSeq;
+  private readonly pendingWriteOnly;
+  private writeOnlyCursor;
+  private unsubscribeWriteOnlyLocal?;
+  private writeOnlyDisabledReason?;
   private joinState?;
   private opQueue;
   /**
@@ -484,6 +600,8 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
    * Creates a transport for one stream URL and one local adapter instance.
    */
   constructor(options: StreamsCrdtOptions<TVersion>);
+  private composeSnapshotDecoder;
+  private composeSnapshotEncoder;
   /**
    * Stops any active live join and releases transport-owned state.
    */
@@ -492,16 +610,24 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
    * Resets the retry counter and immediately attempts to reconnect.
    *
    * Use this after device wake or network recovery to skip any pending
-   * backoff delay. No-op when the room is already joined or no join is active.
+   * backoff delay. No-op when the room is already fully healthy (both
+   * read and write sub-statuses are "ok") or no join is active.
    *
-   * If the room reached `"disconnected"` status (only possible with a finite
-   * `maxAttempts` config), this restarts the read loop.
+   * If the room reached `"disconnected"` or `"error"` status, this
+   * restarts the affected loop(s).
    */
   rejoin(): void;
   /**
    * Reads the latest remote snapshot offset, if the server exposes one.
    */
   getSnapshotOffset(): Promise<Result<string | null, TransportError>>;
+  /**
+   * Uploads a full adapter snapshot at the current remote tail.
+   *
+   * @internal Intended for end-to-end tests that must deterministically create
+   * a remote snapshot without waiting for the best-effort join() debounce.
+   */
+  uploadSnapshotForTesting(): Promise<Result<TransportSnapshotUploadSuccess, TransportError>>;
   /**
    * Explicitly creates the target stream.
    */
@@ -514,6 +640,14 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
    * Runs one bootstrap/catch-up cycle without entering live mode.
    */
   sync(): Promise<Result<TransportSyncSuccess<TVersion>, TransportError>>;
+  /**
+   * Appends local CRDT updates without reading the stream first.
+   *
+   * Use this for write-only actors whose auth token may POST to the stream but
+   * may not bootstrap, catch up, or join live reads. The method does not save a
+   * RemoteCursorStore cursor and does not apply remote updates.
+   */
+  appendWriteOnly(): Promise<Result<WriteOnlyAppendResult<TVersion>, TransportError>>;
   /**
    * Replays remote state, flushes queued local updates, then enters live read mode.
    */
@@ -529,6 +663,11 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   private catchup;
   private catchupOrGone;
   private appendLocalBatch;
+  /**
+   * Ensures the target stream exists, creating it if necessary.
+   * Tolerates 409 Conflict (stream already created concurrently).
+   */
+  private ensureStreamExists;
   private exportUpdates;
   private applyBootstrapItems;
   private applyRemoteItems;
@@ -550,7 +689,9 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
    *
    * Returns `undefined` when the queue is empty.
    */
+  private drainQueuedBatch;
   private drainPendingBatch;
+  private drainPendingWriteOnlyBatch;
   private flushPendingLocal;
   /**
    * Decrements all sync waiters by the number of flushed batches and
@@ -560,12 +701,28 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   /** Rejects and removes all sync waiters. */
   private rejectSyncWaiters;
   private saveRemoteCursor;
-  private setJoinStatus;
+  private setReadSubStatus;
+  private setWriteSubStatus;
+  private recomputeJoinStatus;
+  private computeOverallStatus;
   private enqueueExclusive;
+  private measureAppendBodyByteLength;
+  private disableWriteOnlyMode;
   private logDebug;
   private logError;
 }
 //#endregion
+//#region src/payload-protection.d.ts
+type PayloadProtectionFailureReason = "plaintext_forbidden" | "missing_read_key" | "decrypt_failed" | "invalid_envelope" | "wrong_payload_kind" | "encrypt_failed";
+declare class PayloadProtectionError extends Error {
+  readonly reason: PayloadProtectionFailureReason;
+  readonly keyId?: string;
+  constructor(reason: PayloadProtectionFailureReason, message: string, options?: {
+    readonly keyId?: string;
+    readonly cause?: unknown;
+  });
+}
+//#endregion
 //#region src/stream-id.d.ts
 /**
  * Validates a stream id accepted by `createStreamUrl()`.
@@ -584,5 +741,5 @@ declare function createStreamUrl(input: {
   baseUrl?: string;
 }): string;
 //#endregion
-export { RemoteCursorSaveSource as A, TransportSyncSuccess as C, IndexedDbRemoteCursorStore as D, InMemoryRemoteCursorStore as E, createInitialRemoteCursor as M, IndexedDbRemoteCursorStoreOptions as O, TransportSubscription as S, BeforeRemoteCursorSaveHook as T, TransportCreateStreamSuccess as _, CrdtAdapter as a, TransportJoinParams as b, JsonObject as c, SnapshotCodec as d, SnapshotTransformHook as f, StreamsCrdtOptions as g, StreamsAuthProvider as h, StreamsCrdt as i, RemoteCursorStore as j, RemoteCursor as k, JsonValue as l, StreamsAuthContext as m, isValidBucketId as n, CrdtUpdateBatch as o, SnapshotUploadOptions as p, isValidRillId as r, IsolatedCrdtAdapter as s, createStreamUrl as t, Result as u, TransportDeleteStreamSuccess as v, BeforeRemoteCursorSaveContext as w, TransportRoomStatus as x, TransportError as y };
-//# sourceMappingURL=stream-id-Do4h2lOD.d.ts.map
+export { StreamsAuthProvider as A, WriteOnlyAppendResult as B, PayloadProtectionScope as C, SnapshotTransformHook as D, SnapshotCodec as E, TransportJoinParams as F, IndexedDbRemoteCursorStoreOptions as G, BeforeRemoteCursorSaveHook as H, TransportRoomStatus as I, RemoteCursorStore as J, RemoteCursor as K, TransportSnapshotUploadSuccess as L, TransportCreateStreamSuccess as M, TransportDeleteStreamSuccess as N, SnapshotUploadOptions as O, TransportError as P, TransportSubscription as R, PayloadProtectionReadPolicy as S, Result as T, InMemoryRemoteCursorStore as U, BeforeRemoteCursorSaveContext as V, IndexedDbRemoteCursorStore as W, createInitialRemoteCursor as Y, JsonValue as _, StreamsCrdt as a, PayloadProtectionKeyProvider as b, E2eeEncryptionOptions as c, E2eeOptions as d, E2eeReadPolicy as f, JsonObject as g, IsolatedCrdtAdapter as h, PayloadProtectionError as i, StreamsCrdtOptions as j, StreamsAuthContext as k, E2eeKey as l, E2eeWritePolicy as m, isValidBucketId as n, CrdtAdapter as o, E2eeScope as p, RemoteCursorSaveSource as q, isValidRillId as r, CrdtUpdateBatch as s, createStreamUrl as t, E2eeKeyProvider as u, PayloadProtectionEncryptionOptions as v, PayloadProtectionWritePolicy as w, PayloadProtectionOptions as x, PayloadProtectionKey as y, TransportSyncSuccess as z };
+//# sourceMappingURL=stream-id-CS7SzuLW.d.ts.map