@xmtp/node-sdk 6.2.0-dev.999b077 → 6.2.0-dev.e7edced

package/dist/index.js

@@ -1,73 +1,45 @@
-import { BackendBuilder, generateInboxId as generateInboxId$1, getInboxIdByIdentity, contentTypeIntent, contentTypeActions, contentTypeWalletSendCalls, contentTypeLeaveRequest, contentTypeReadReceipt, contentTypeGroupUpdated, contentTypeTransactionReference, contentTypeMultiRemoteAttachment, contentTypeRemoteAttachment, contentTypeAttachment, contentTypeReaction, contentTypeReply, contentTypeMarkdown, contentTypeText, UnstableChangeCallbacks, createClientWithBackend, revokeInstallationsSignatureRequest, applySignatureRequest, fetchInboxStatesByInboxIds, verifySignedWithPublicKey, isAddressAuthorized, isInstallationAuthorized, Backend } from '@xmtp/node-bindings';
+import { BackendBuilder, AuthCallback, generateInboxId as generateInboxId$1, getInboxIdByIdentity, contentTypeIntent, contentTypeActions, contentTypeWalletSendCalls, contentTypeLeaveRequest, contentTypeReadReceipt, contentTypeGroupUpdated, contentTypeTransactionReference, contentTypeMultiRemoteAttachment, contentTypeRemoteAttachment, contentTypeAttachment, contentTypeReaction, contentTypeReply, contentTypeMarkdown, contentTypeText, UnstableChangeCallbacks, createClientWithBackend, revokeInstallationsSignatureRequest, applySignatureRequest, fetchInboxStatesByInboxIds, verifySignedWithPublicKey, isAddressAuthorized, isInstallationAuthorized, fetchServerConfiguration, Backend } from '@xmtp/node-bindings';
 export { ActionStyle, BackupElementSelectionOption, ConsentEntityType, ConsentState, ContentType, ConversationType, DeliveryStatus, GroupMembershipState, GroupMessageKind, GroupPermissionsOptions, IdentifierKind, ListConversationsOrderBy, LogLevel, MessageSortBy, MetadataField, PermissionLevel, PermissionPolicy, PermissionUpdateType, ReactionAction, ReactionSchema, SortDirection, WorkerKind, contentTypeActions, contentTypeAttachment, contentTypeGroupUpdated, contentTypeIntent, contentTypeLeaveRequest, contentTypeMarkdown, contentTypeMultiRemoteAttachment, contentTypeReaction, contentTypeReadReceipt, contentTypeRemoteAttachment, contentTypeReply, contentTypeText, contentTypeTransactionReference, contentTypeWalletSendCalls, decryptAttachment, encodeActions, encodeAttachment, encodeIntent, encodeMarkdown, encodeMultiRemoteAttachment, encodeReaction, encodeReadReceipt, encodeRemoteAttachment, encodeText, encodeTransactionReference, encodeWalletSendCalls, encryptAttachment, flushTelemetry, initLogging } from '@xmtp/node-bindings';
-import { randomBytes } from 'node:crypto';
 import { contentTypeToString } from '@xmtp/content-type-primitives';
+import { randomBytes } from 'node:crypto';
 import { isPromise } from 'node:util/types';
 import { join } from 'node:path';
 import process from 'node:process';
 
-/**
- * Pre-configured URLs for the XMTP network based on the environment
- *
- * @deprecated Use `createBackend()` instead.
- * @constant
- * @property {string} local - The local URL for the XMTP network
- * @property {string} dev - The development URL for the XMTP network
- * @property {string} production - The production URL for the XMTP network
- */
-const ApiUrls = {
-    local: "http://localhost:5556",
-    dev: "https://grpc.dev.xmtp.network:443",
-    production: "https://grpc.production.xmtp.network:443",
-};
-/**
- * Pre-configured URLs for the XMTP history sync service based on the environment
- *
- * @constant
- * @property {string} local - The local URL for the XMTP history sync service
- * @property {string} dev - The development URL for the XMTP history sync service
- * @property {string} production - The production URL for the XMTP history sync service
- */
-const HistorySyncUrls = {
-    local: "http://localhost:5558",
-    dev: "https://message-history.dev.ephemera.network",
-    production: "https://message-history.production.ephemera.network",
-    "testnet-staging": "https://message-history.dev.ephemera.network",
-    "testnet-dev": "https://message-history.dev.ephemera.network",
-    testnet: "https://message-history.dev.ephemera.network",
-    mainnet: "https://message-history.production.ephemera.network",
+/** Keep callback failures and invalid credentials out of error messages. */
+const readCredential = async (callback) => {
+    try {
+        const credential = await callback();
+        if (typeof credential.value !== "string" ||
+            (credential.name !== undefined && typeof credential.name !== "string") ||
+            !Number.isSafeInteger(credential.expiresAtSeconds)) {
+            throw new Error();
+        }
+        return {
+            name: credential.name,
+            value: credential.value,
+            expiresAtSeconds: credential.expiresAtSeconds,
+        };
+    }
+    catch {
+        throw new Error("auth callback failed");
+    }
 };
 
-const envMap = {
-    local: "Local" /* BindingsEnv.Local */,
-    dev: "Dev" /* BindingsEnv.Dev */,
-    production: "Production" /* BindingsEnv.Production */,
-    "testnet-staging": "TestnetStaging" /* BindingsEnv.TestnetStaging */,
-    "testnet-dev": "TestnetDev" /* BindingsEnv.TestnetDev */,
-    testnet: "Testnet" /* BindingsEnv.Testnet */,
-    mainnet: "Mainnet" /* BindingsEnv.Mainnet */,
-};
-const reverseEnvMap = {
-    ["Local" /* BindingsEnv.Local */]: "local",
-    ["Dev" /* BindingsEnv.Dev */]: "dev",
-    ["Production" /* BindingsEnv.Production */]: "production",
-    ["TestnetStaging" /* BindingsEnv.TestnetStaging */]: "testnet-staging",
-    ["TestnetDev" /* BindingsEnv.TestnetDev */]: "testnet-dev",
-    ["Testnet" /* BindingsEnv.Testnet */]: "testnet",
-    ["Mainnet" /* BindingsEnv.Mainnet */]: "mainnet",
-};
-const envToString = (env) => {
-    return reverseEnvMap[env];
-};
 const createBackend = async (options) => {
-    const env = options?.env ?? "dev";
-    const builder = new BackendBuilder(envMap[env]);
-    if (options?.apiUrl)
-        builder.setApiUrl(options.apiUrl);
-    if (options?.gatewayHost)
-        builder.setGatewayHost(options.gatewayHost);
-    if (options?.appVersion)
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Validate options from JavaScript callers.
+    if (!options?.backendUrl?.trim()) {
+        throw new Error("backendUrl is required");
+    }
+    const builder = new BackendBuilder(options.backendUrl);
+    if (options.env !== undefined)
+        builder.setEnv(options.env);
+    if (options.appVersion !== undefined)
         builder.setAppVersion(options.appVersion);
+    if (options.authCallback) {
+        const callback = options.authCallback;
+        builder.authCallback(new AuthCallback(() => readCredential(callback)));
+    }
     return builder.build();
 };
 
@@ -173,6 +145,13 @@ function nsToDate(ns) {
     return new Date(Number(ns / 1000000n));
 }
 
+const decodeFailures = new WeakMap();
+/** Reject failed registered codecs at delivery without changing legacy reads. */
+const assertMessageDecodedForDelivery = (message) => {
+    const failure = decodeFailures.get(message);
+    if (failure)
+        throw failure.error;
+};
 const getContentFromDecodedMessageContent = (content) => {
     switch (content.type) {
         case "Text" /* DecodedMessageContentType.Text */: {
@@ -303,6 +282,8 @@ const getContentTypeFromDecodedMessageContent = (content) => {
  * @property {bigint} sentAtNs - Timestamp when the message was sent (in nanoseconds)
  */
 class DecodedMessage {
+    /** Database-local position of this delivery. Absent for ordinary history reads. */
+    deliveryCursor;
     content;
     contentType;
     conversationId;
@@ -331,8 +312,15 @@ class DecodedMessage {
         this.fallback = message.fallback ?? undefined;
         this.kind = message.kind;
         this.deliveryStatus = message.deliveryStatus;
+        const decodeChild = (child) => {
+            const decoded = new DecodedMessage(codecRegistry, child);
+            const failure = decodeFailures.get(decoded);
+            if (failure && !decodeFailures.has(this))
+                decodeFailures.set(this, failure);
+            return decoded;
+        };
         this.numReplies = message.numReplies;
-        this.reactions = message.reactions.map((reaction) => new DecodedMessage(codecRegistry, reaction));
+        this.reactions = message.reactions.map((reaction) => decodeChild(reaction));
         this.content =
             getContentFromDecodedMessageContent(message.content) ??
                 undefined;
@@ -347,6 +335,8 @@ class DecodedMessage {
                             replyContent = codec.decode(replyContent);
                         }
                         catch (error) {
+                            if (!decodeFailures.has(this))
+                                decodeFailures.set(this, { error });
                             if (error instanceof Error) {
                                 console.warn(`Error decoding custom content: ${error.message}`);
                             }
@@ -361,7 +351,7 @@ class DecodedMessage {
                     content: replyContent,
                     contentType: getContentTypeFromDecodedMessageContent(reply.content),
                     inReplyTo: reply.inReplyTo
-                        ? new DecodedMessage(codecRegistry, reply.inReplyTo)
+                        ? decodeChild(reply.inReplyTo)
                         : null,
                 };
                 break;
@@ -375,6 +365,8 @@ class DecodedMessage {
                             this.content = codec.decode(customContent);
                         }
                         catch (error) {
+                            if (!decodeFailures.has(this))
+                                decodeFailures.set(this, { error });
                             if (error instanceof Error) {
                                 console.warn(`Error decoding custom content: ${error.message}`);
                             }
@@ -395,430 +387,258 @@ class DecodedMessage {
     }
 }
 
-/**
- * AsyncStream provides an async iterable interface for streaming data.
- *
- * This class implements a producer-consumer pattern where:
- * - Producers can push values using the `push()` method
- * - Consumers can iterate over values asynchronously using `for await` loops or `next()`
- * - Values are queued internally when no consumers are waiting
- * - Consumers are resolved immediately when values are available
- * - The stream can be terminated using `done()`, `return()`, or `end()`
- *
- * @example
- * ```typescript
- * const stream = new AsyncStream<string>();
- *
- * stream.push("hello");
- * stream.push("world");
- *
- * for await (const value of stream) {
- *   console.log(value); // "hello", "world"
- * }
- * ```
- */
-class AsyncStream {
-    isDone = false;
-    #pendingResolves = [];
-    #queue;
-    onDone;
-    onReturn;
-    constructor() {
-        this.#queue = [];
-        this.isDone = false;
-    }
-    flush() {
-        while (this.#pendingResolves.length > 0) {
-            const nextResolve = this.#pendingResolves.shift();
-            if (nextResolve) {
-                nextResolve({ done: true, value: undefined });
-            }
+/** One pending item. Construction selects callback mode or next-request acknowledgement. */
+class MessageStream {
+    #reader;
+    #convert;
+    #options;
+    #onValue;
+    #pending;
+    #reading = false;
+    #done = false;
+    #closing;
+    #cursor;
+    constructor(reader, convert, options = {}) {
+        this.#reader = reader;
+        this.#convert = convert;
+        this.#options = options;
+        this.#onValue = options.onValue;
+        if (this.#onValue) {
+            // Callback mode has no caller waiting on next(). Errors reach onError before cleanup.
+            void this.#read().catch(() => undefined);
         }
     }
-    done() {
-        this.flush();
-        this.#queue = [];
-        this.#pendingResolves = [];
-        this.isDone = true;
-        this.onDone?.();
+    get isDone() {
+        return this.#done;
     }
-    push = (value) => {
-        if (this.isDone) {
-            return;
+    get deliveredCursor() {
+        return this.#cursor;
+    }
+    #hasEnded() {
+        return this.#done;
+    }
+    next = () => {
+        if (this.#onValue) {
+            return Promise.reject(new Error("Cannot call next() on a message stream in callback mode"));
         }
-        const nextResolve = this.#pendingResolves.shift();
-        if (nextResolve) {
-            nextResolve({
-                done: false,
-                value,
-            });
+        return this.#read();
+    };
+    async #acknowledgePending() {
+        const pending = this.#pending;
+        if (pending) {
+            // Keep the token until success so close can reject a failed acknowledgement.
+            await pending.acknowledge();
+            if (this.#pending === pending)
+                this.#pending = undefined;
+        }
+    }
+    async #read() {
+        if (this.#hasEnded())
+            return { done: true, value: undefined };
+        if (this.#reading)
+            throw new Error("A message read is already pending");
+        this.#reading = true;
+        try {
+            await this.#acknowledgePending();
+            while (!this.#hasEnded()) {
+                const item = await this.#reader.nextDelivery();
+                if (item === undefined || item === null) {
+                    await this.return();
+                    break;
+                }
+                if (this.#hasEnded()) {
+                    await item.acknowledgement.reject();
+                    break;
+                }
+                this.#pending = item.acknowledgement;
+                // A codec that throws must not advance the cursor. The message is
+                // retained and a later reader, or the same client with the codec
+                // registered, must still see it. Acknowledging here would skip a
+                // message nothing has read. This matches the undefined case below:
+                // both mean this client could not decode the message, so both hold
+                // the item rather than discarding it.
+                const value = await this.#convert(item.message, item.cursor);
+                if (this.#hasEnded())
+                    break;
+                const checked = item.acknowledgement.checkOwner();
+                const valid = typeof checked === "boolean" ? checked : await checked;
+                if (this.#hasEnded())
+                    break;
+                if (!valid) {
+                    this.#pending = undefined;
+                    await item.acknowledgement.reject();
+                    continue;
+                }
+                if (value === undefined) {
+                    // The converter could not produce a value. That includes a failed
+                    // lookup, so it is not safe to acknowledge: skipping here would
+                    // advance the durable cursor past a message nothing has read.
+                    // Report it and stop, leaving the item replayable.
+                    throw new Error("The retained message could not be decoded");
+                }
+                // Do not await between the final ownership check and the app handoff.
+                this.#cursor = item.cursor;
+                if (this.#onValue) {
+                    await this.#onValue(value);
+                    if (this.#hasEnded())
+                        break;
+                    await this.#acknowledgePending();
+                }
+                else {
+                    return { done: false, value };
+                }
+            }
+            return { done: true, value: undefined };
         }
-        else {
-            this.#queue.push(value);
+        catch (error) {
+            if (!this.#hasEnded()) {
+                try {
+                    // A handler that throws must not replace the real failure. The
+                    // caller needs the original cause to know why the stream ended.
+                    this.#options.onError?.(error);
+                }
+                catch {
+                    // Reported through the rethrow below.
+                }
+                finally {
+                    await this.return();
+                }
+            }
+            throw error;
         }
-    };
-    next = () => {
-        if (this.isDone) {
-            return Promise.resolve({ done: true, value: undefined });
+        finally {
+            this.#reading = false;
         }
-        if (this.#queue.length > 0) {
-            return Promise.resolve({
-                done: false,
-                value: this.#queue.shift(),
-            });
+    }
+    async #close(pending) {
+        const invoke = (action) => {
+            try {
+                return Promise.resolve(action());
+            }
+            catch (error) {
+                return Promise.reject(error instanceof Error
+                    ? error
+                    : new Error("Message stream close failed", { cause: error }));
+            }
+        };
+        // Invoke close before any await so it fences pending reads and host handoffs.
+        const results = await Promise.allSettled([
+            invoke(() => this.#reader.close()),
+            invoke(() => pending?.reject()),
+        ]);
+        try {
+            for (const result of results) {
+                if (result.status === "rejected")
+                    throw result.reason;
+            }
+            return { done: true, value: undefined };
         }
-        return new Promise((resolve) => {
-            this.#pendingResolves.push(resolve);
-        });
-    };
+        finally {
+            this.#options.onEnd?.();
+        }
+    }
     return = () => {
-        this.onReturn?.();
-        this.done();
-        return Promise.resolve({
-            done: true,
-            value: undefined,
-        });
+        if (this.#done) {
+            return this.#closing ?? Promise.resolve({ done: true, value: undefined });
+        }
+        this.#done = true;
+        const pending = this.#pending;
+        this.#pending = undefined;
+        this.#closing = this.#close(pending);
+        return this.#closing;
     };
-    end = () => this.return();
+    end = this.return;
+    updateScope = (groupIds) => this.#reader.updateScope(groupIds);
+    updateFilter = (conversationType, consentStates) => this.#reader.updateFilter(conversationType, consentStates);
+    catchUpSnapshot = () => this.#reader.catchUpSnapshot();
+    catchUpChanged = () => this.#reader.catchUpChanged();
     [Symbol.asyncIterator]() {
         return this;
     }
 }
-const usableProperties = [
-    "end",
-    "isDone",
-    "next",
-    "return",
-    Symbol.asyncIterator,
-];
-const isUsableProperty = (prop) => {
-    return usableProperties.includes(prop);
+
+/** A notification failure with a stable error code. */
+class NotificationError extends Error {
+    code;
+    constructor(code, options) {
+        super(code, options);
+        this.code = code;
+        this.name = "NotificationError";
+    }
+}
+const toBindingNotificationConfig = (config) => {
+    const { channel, ...rules } = config;
+    return {
+        ...rules,
+        channel: channel.type,
+        ...(channel.type === "http"
+            ? { url: channel.url, signingKey: Array.from(channel.signingKey) }
+            : { token: channel.token }),
+    };
 };
-/**
- * Creates a read-only proxy for AsyncStream instances that restricts access to consumer-only methods.
- *
- * This proxy only exposes the following properties and methods:
- * - `next()`: Get the next value from the stream
- * - `end()`: Terminate the stream and stop iteration
- * - `return()`: Same as end(), terminates the stream
- * - `isDone`: Boolean indicating if the stream has been terminated
- * - `Symbol.asyncIterator`: Enables `for await` loop iteration
- *
- * Producer methods like `push()`, `done()`, and `flush()` are hidden to prevent
- * consumers from accidentally modifying the stream state.
- *
- * @param stream - The AsyncStream instance to create a proxy for
- * @returns A read-only proxy that implements AsyncStreamProxy<T>
- *
- * @example
- * ```typescript
- * const stream = new AsyncStream<string>();
- * const proxy = createAsyncStreamProxy(stream);
- *
- * stream.push("hello");
- * stream.push("world");
- *
- * for await (const value of proxy) {
- *   console.log(value); // "hello", "world"
- * }
- * ```
- */
-function createAsyncStreamProxy(stream) {
-    return new Proxy(stream, {
-        get(target, prop, receiver) {
-            if (isUsableProperty(prop)) {
-                return Reflect.get(target, prop, receiver);
-            }
-        },
-        set() {
-            return true;
-        },
-        has(_target, prop) {
-            return isUsableProperty(prop);
-        },
-        ownKeys() {
-            return usableProperties;
-        },
-        getOwnPropertyDescriptor(target, prop) {
-            if (isUsableProperty(prop)) {
-                return {
-                    enumerable: true,
-                    configurable: true,
-                    value: Reflect.get(target, prop),
-                };
+const toNotificationState = (value) => {
+    switch (value.state) {
+        case 0 /* NotificationStateKind.Disabled */:
+            return { state: "disabled" };
+        case 1 /* NotificationStateKind.Enabled */:
+            return { state: "enabled" };
+        case 2 /* NotificationStateKind.Failed */: {
+            const codes = {
+                [0 /* NotificationFailure.PermissionDenied */]: "PermissionDenied",
+                [1 /* NotificationFailure.InvalidArgument */]: "InvalidArgument",
+                [2 /* NotificationFailure.OutOfRange */]: "OutOfRange",
+                [3 /* NotificationFailure.Unimplemented */]: "Unimplemented",
+                [4 /* NotificationFailure.ChannelNotConfigured */]: "ChannelNotConfigured",
+            };
+            if (value.failure == null) {
+                throw new Error("Notification failure is missing its error");
             }
-            return undefined;
-        },
-    });
-}
+            return {
+                state: "failed",
+                error: new NotificationError(`NotificationError::${codes[value.failure]}`),
+            };
+        }
+    }
+};
+const toBindingNotificationOverride = (value) => {
+    switch (value) {
+        case "enabled":
+            return 0 /* BindingNotificationOverride.Enabled */;
+        case "disabled":
+            return 1 /* BindingNotificationOverride.Disabled */;
+        case "default":
+            return 2 /* BindingNotificationOverride.Default */;
+    }
+};
+const throwNotificationError = (error) => {
+    if (error instanceof Error) {
+        const code = /^\[(NotificationError::[^\]]+)\]/.exec(error.message)?.[1];
+        if (code)
+            throw new NotificationError(code, { cause: error });
+    }
+    throw error;
+};
 
-const DEFAULT_RETRY_DELAY = 60_000; // milliseconds
-const DEFAULT_RETRY_ATTEMPTS = 10;
 /**
- * Creates a stream from a stream function
- *
- * If the stream fails, an attempt will be made to restart it.
- *
- * Ending the stream is terminal: no callbacks are invoked and no native
- * stream is created after the stream ends.
- *
- * This function is not intended to be used directly.
+ * Represents a conversation
  *
- * @param streamFunction - The stream function to create a stream from
- * @param streamValueMutator - An optional function to mutate the value emitted from the stream
- * @param options - The options for the stream
- * @param args - Additional arguments to pass to the stream function
- * @returns An async iterable stream proxy
- * @throws {StreamInvalidRetryAttemptsError} if the retryAttempts option is less than 0 and retryOnFail is true
- * @throws {StreamFailedError} if the stream fails and can't be restarted
+ * This class is not intended to be initialized directly.
  */
-const createStream = async (streamFunction, streamValueMutator, options) => {
-    const { onEnd, onError, onFail, onRestart, onRetry, onValue, retryAttempts = DEFAULT_RETRY_ATTEMPTS, retryDelay = DEFAULT_RETRY_DELAY, retryOnFail = true, } = options ?? {};
-    // retry attempts must be greater than 0
-    if (retryOnFail && retryAttempts < 0) {
-        throw new StreamInvalidRetryAttemptsError();
-    }
-    const asyncStream = new AsyncStream();
-    // lifecycle state, owned by this wrapper
-    let stopped = false;
-    // reading the flag through a function call defeats TS control-flow
-    // narrowing, which cannot see the closure mutation across awaits
-    const isStopped = () => stopped;
-    let currentCloser;
-    let retryTimer;
-    let retryInFlight = false;
-    // set when a restart's native stream closes during its own creation, so the
-    // completed attempt reschedules instead of installing an already-dead closer
-    let closePendingDuringRestart = false;
-    // read through a call so no-unnecessary-condition cannot narrow the flag to
-    // a constant; handleNativeClose mutates it across an await
-    const isClosePending = () => closePendingDuringRestart;
-    // the retry budget is monotonic: it is never reset for the lifetime of
-    // this wrapper, so restarts are bounded even across successful restarts
-    let remainingRetries = retryAttempts;
-    // terminal transition: cancel any pending retry, close the active native
-    // stream, and notify onEnd exactly once
-    const stop = () => {
-        if (isStopped()) {
-            return;
-        }
-        stopped = true;
-        closePendingDuringRestart = false;
-        if (retryTimer !== undefined) {
-            clearTimeout(retryTimer);
-            retryTimer = undefined;
-        }
-        currentCloser?.end();
-        currentCloser = undefined;
-        onEnd?.();
-    };
-    // registered before any async work so ending the stream is always terminal,
-    // even while a retry is pending or a native stream is being created
-    asyncStream.onDone = stop;
-    const fail = (error) => {
-        if (isStopped()) {
-            return;
-        }
-        // the terminal transition must run even if onError throws, otherwise a
-        // throwing consumer callback leaves the stream open and hangs next()
-        try {
-            onError?.(error);
-        }
-        finally {
-            void asyncStream.end();
-        }
-    };
-    const streamCallback = (error, value) => {
-        // an ended stream must not invoke any callbacks
-        if (isStopped()) {
-            return;
-        }
-        // if a stream error occurs, call the onError callback
-        if (error) {
-            onError?.(error);
-            return;
-        }
-        // ensure the value is not undefined
-        if (value !== undefined) {
-            try {
-                // if a streamValueMutator is provided, mutate the value
-                if (streamValueMutator) {
-                    const mutatedValue = streamValueMutator(value);
-                    if (isPromise(mutatedValue)) {
-                        void mutatedValue
-                            .then((mutatedValue) => {
-                            // the stream may have ended while the value was mutating
-                            if (!isStopped() && mutatedValue !== undefined) {
-                                asyncStream.push(mutatedValue);
-                                onValue?.(mutatedValue);
-                            }
-                        })
-                            .catch((error) => {
-                            if (!isStopped()) {
-                                onError?.(error);
-                            }
-                        });
-                    }
-                    else {
-                        // a synchronous mutator may have ended the stream; gate delivery
-                        // on the stopped flag to match the async branch above
-                        if (!isStopped() && mutatedValue !== undefined) {
-                            asyncStream.push(mutatedValue);
-                            onValue?.(mutatedValue);
-                        }
-                    }
-                }
-                else {
-                    asyncStream.push(value);
-                    onValue?.(value);
-                }
-            }
-            catch (error) {
-                onError?.(error);
-            }
-        }
-    };
-    const scheduleRetry = () => {
-        // at most one retry may be in flight per wrapper
-        if (isStopped() || retryInFlight) {
-            return;
-        }
-        if (remainingRetries <= 0) {
-            fail(new StreamFailedError(retryAttempts));
-            return;
-        }
-        retryInFlight = true;
-        retryTimer = setTimeout(() => {
-            retryTimer = undefined;
-            void attemptRestart();
-        }, retryDelay);
-    };
-    const attemptRestart = async () => {
-        if (isStopped()) {
-            retryInFlight = false;
-            return;
-        }
-        // scope the pending-close flag to this attempt: a close recorded while the
-        // retry timer was merely pending belongs to the stream that scheduled it
-        closePendingDuringRestart = false;
-        remainingRetries -= 1;
-        onRetry?.(retryAttempts - remainingRetries, retryAttempts);
-        if (isStopped()) {
-            // onRetry may have ended the stream; do not open a native stream after
-            // termination
-            retryInFlight = false;
-            return;
-        }
-        try {
-            // attempt to restart the stream
-            const streamCloser = await streamFunction(streamCallback, handleNativeClose);
-            if (isStopped()) {
-                // the stream ended while the native stream was being created
-                streamCloser.end();
-                retryInFlight = false;
-                return;
-            }
-            await streamCloser.waitForReady();
-            if (isStopped()) {
-                streamCloser.end();
-                retryInFlight = false;
-                return;
-            }
-            if (isClosePending()) {
-                // the replacement stream closed during its own creation; discard it
-                // and schedule a fresh attempt instead of installing a dead closer
-                closePendingDuringRestart = false;
-                streamCloser.end();
-                retryInFlight = false;
-                scheduleRetry();
-                return;
-            }
-            currentCloser = streamCloser;
-            retryInFlight = false;
-            // stream restarted, call the onRestart callback
-            onRestart?.();
-        }
-        catch (error) {
-            retryInFlight = false;
-            if (isStopped()) {
-                return;
-            }
-            closePendingDuringRestart = false;
-            onError?.(error);
-            scheduleRetry();
-        }
-    };
-    const handleNativeClose = () => {
-        // ending the stream closes the native stream, which still triggers this
-        // callback; only an unexpected close is a failure
-        if (isStopped()) {
-            return;
-        }
-        currentCloser = undefined;
-        onFail?.();
-        if (retryOnFail) {
-            // a native close during an in-flight restart is dropped by the
-            // single-flight guard; record it so the completed attempt reschedules
-            // instead of installing a stream that already died
-            if (retryInFlight) {
-                closePendingDuringRestart = true;
-                return;
-            }
-            scheduleRetry();
-        }
-        else {
-            fail(new StreamFailedError(0));
-        }
-    };
-    try {
-        // create the stream
-        const streamCloser = await streamFunction(streamCallback, handleNativeClose);
-        if (isStopped()) {
-            streamCloser.end();
-        }
-        else {
-            await streamCloser.waitForReady();
-            if (isStopped()) {
-                streamCloser.end();
-            }
-            else {
-                currentCloser = streamCloser;
-            }
-        }
-    }
-    catch (error) {
-        onError?.(error);
-        if (retryOnFail) {
-            scheduleRetry();
-        }
-        else {
-            fail(new StreamFailedError(0));
-        }
-    }
-    // return a proxy for the async stream
-    return createAsyncStreamProxy(asyncStream);
-};
-
-/**
- * Represents a conversation
- *
- * This class is not intended to be initialized directly.
- */
-class Conversation {
-    #client;
-    #codecRegistry;
-    #conversation;
-    /**
-     * Creates a new conversation instance
-     *
-     * @param client - The client instance managing the conversation
-     * @param codecRegistry - The codec registry instance
-     * @param conversation - The underlying conversation instance
-     */
-    constructor(client, codecRegistry, conversation) {
-        this.#client = client;
-        this.#codecRegistry = codecRegistry;
-        this.#conversation = conversation;
+class Conversation {
+    #client;
+    #codecRegistry;
+    #conversation;
+    /**
+     * Creates a new conversation instance
+     *
+     * @param client - The client instance managing the conversation
+     * @param codecRegistry - The codec registry instance
+     * @param conversation - The underlying conversation instance
+     */
+    constructor(client, codecRegistry, conversation) {
+        this.#client = client;
+        this.#codecRegistry = codecRegistry;
+        this.#conversation = conversation;
     }
     /**
      * Gets the unique identifier for this conversation
@@ -832,6 +652,16 @@ class Conversation {
     get isActive() {
         return this.#conversation.isActive();
     }
+    /** Override notification rules, or reset the override with "default". */
+    setNotifications(value) {
+        return Promise.resolve().then(() => {
+            this.#conversation.setNotifications(toBindingNotificationOverride(value));
+        });
+    }
+    /** Read the effective notification value for this conversation. */
+    notificationsEnabled() {
+        return Promise.resolve().then(() => this.#conversation.notificationsEnabled());
+    }
     /**
      * Gets the inbox ID that added this client's inbox to the conversation
      */
@@ -851,7 +681,7 @@ class Conversation {
         return nsToDate(this.createdAtNs);
     }
     get topic() {
-        return `/xmtp/mls/1/g-${this.id}/proto`;
+        return `00${this.id}`;
     }
     pausedForVersion() {
         return this.#conversation.pausedForVersion() ?? undefined;
@@ -893,26 +723,31 @@ class Conversation {
         return this.#conversation.sync();
     }
     /**
-     * Creates a stream for new messages in this conversation
+     * Reads retained messages after the default acknowledgement position.
+     * Set `from` to replay after a cursor without changing default progress.
+     * Set `onValue` for callback mode, or request items with the iterator.
+     * Core owns network recovery. Legacy retry options and `disableSync` do not apply.
      *
-     * @param options - Optional stream options
+     * @param options - Optional delivery callbacks and replay cursor
      * @returns Stream instance for new messages
      */
     async stream(options) {
-        const stream = async (callback, onFail) => {
-            if (!options?.disableSync) {
-                await this.sync();
-            }
-            return this.#conversation.stream(callback, onFail);
-        };
-        const convertMessage = (value) => {
+        const reader = await this.#conversation.messageReader(options?.from);
+        const convertMessage = (value, cursor) => {
             const enrichedMessage = this.#client.conversations.getMessageById(value.id);
-            if (enrichedMessage === undefined) {
-                console.warn(`Streamed message with ID "${value.id}" not found`);
+            if (enrichedMessage !== undefined) {
+                assertMessageDecodedForDelivery(enrichedMessage);
+                enrichedMessage.deliveryCursor = cursor;
             }
             return enrichedMessage;
         };
-        return createStream(stream, convertMessage, options);
+        return new MessageStream(reader, convertMessage, options);
+    }
+    messageHistorySnapshot(limit) {
+        return this.#conversation.messageHistorySnapshot(limit);
+    }
+    beginningDeliveryCursor() {
+        return this.#conversation.beginningDeliveryCursor();
     }
     /**
      * Decodes, decrypts, and persists a raw envelope from a group message stream.
@@ -1414,16 +1249,420 @@ class Group extends Conversation {
     async requestRemoval() {
         return this.#conversation.leaveGroup();
     }
-    /**
-     * Checks if the current user has requested to leave the group
-     *
-     * @returns Boolean
-     */
-    isPendingRemoval() {
-        return (this.#conversation.membershipState() ===
-            4 /* GroupMembershipState.PendingRemove */);
+    /**
+     * Checks if the current user has requested to leave the group
+     *
+     * @returns Boolean
+     */
+    isPendingRemoval() {
+        return (this.#conversation.membershipState() ===
+            4 /* GroupMembershipState.PendingRemove */);
+    }
+}
+
+/**
+ * AsyncStream provides an async iterable interface for streaming data.
+ *
+ * This class implements a producer-consumer pattern where:
+ * - Producers can push values using the `push()` method
+ * - Consumers can iterate over values asynchronously using `for await` loops or `next()`
+ * - Values are queued internally when no consumers are waiting
+ * - Consumers are resolved immediately when values are available
+ * - The stream can be terminated using `done()`, `return()`, or `end()`
+ *
+ * @example
+ * ```typescript
+ * const stream = new AsyncStream<string>();
+ *
+ * stream.push("hello");
+ * stream.push("world");
+ *
+ * for await (const value of stream) {
+ *   console.log(value); // "hello", "world"
+ * }
+ * ```
+ */
+class AsyncStream {
+    isDone = false;
+    #pendingResolves = [];
+    #queue;
+    onDone;
+    onReturn;
+    constructor() {
+        this.#queue = [];
+        this.isDone = false;
+    }
+    flush() {
+        while (this.#pendingResolves.length > 0) {
+            const nextResolve = this.#pendingResolves.shift();
+            if (nextResolve) {
+                nextResolve({ done: true, value: undefined });
+            }
+        }
+    }
+    done() {
+        this.flush();
+        this.#queue = [];
+        this.#pendingResolves = [];
+        this.isDone = true;
+        this.onDone?.();
+    }
+    push = (value) => {
+        if (this.isDone) {
+            return;
+        }
+        const nextResolve = this.#pendingResolves.shift();
+        if (nextResolve) {
+            nextResolve({
+                done: false,
+                value,
+            });
+        }
+        else {
+            this.#queue.push(value);
+        }
+    };
+    next = () => {
+        if (this.isDone) {
+            return Promise.resolve({ done: true, value: undefined });
+        }
+        if (this.#queue.length > 0) {
+            return Promise.resolve({
+                done: false,
+                value: this.#queue.shift(),
+            });
+        }
+        return new Promise((resolve) => {
+            this.#pendingResolves.push(resolve);
+        });
+    };
+    return = () => {
+        this.onReturn?.();
+        this.done();
+        return Promise.resolve({
+            done: true,
+            value: undefined,
+        });
+    };
+    end = () => this.return();
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+const usableProperties = [
+    "end",
+    "isDone",
+    "next",
+    "return",
+    Symbol.asyncIterator,
+];
+const isUsableProperty = (prop) => {
+    return usableProperties.includes(prop);
+};
+/**
+ * Creates a read-only proxy for AsyncStream instances that restricts access to consumer-only methods.
+ *
+ * This proxy only exposes the following properties and methods:
+ * - `next()`: Get the next value from the stream
+ * - `end()`: Terminate the stream and stop iteration
+ * - `return()`: Same as end(), terminates the stream
+ * - `isDone`: Boolean indicating if the stream has been terminated
+ * - `Symbol.asyncIterator`: Enables `for await` loop iteration
+ *
+ * Producer methods like `push()`, `done()`, and `flush()` are hidden to prevent
+ * consumers from accidentally modifying the stream state.
+ *
+ * @param stream - The AsyncStream instance to create a proxy for
+ * @returns A read-only proxy that implements AsyncStreamProxy<T>
+ *
+ * @example
+ * ```typescript
+ * const stream = new AsyncStream<string>();
+ * const proxy = createAsyncStreamProxy(stream);
+ *
+ * stream.push("hello");
+ * stream.push("world");
+ *
+ * for await (const value of proxy) {
+ *   console.log(value); // "hello", "world"
+ * }
+ * ```
+ */
+function createAsyncStreamProxy(stream) {
+    return new Proxy(stream, {
+        get(target, prop, receiver) {
+            if (isUsableProperty(prop)) {
+                return Reflect.get(target, prop, receiver);
+            }
+        },
+        set() {
+            return true;
+        },
+        has(_target, prop) {
+            return isUsableProperty(prop);
+        },
+        ownKeys() {
+            return usableProperties;
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (isUsableProperty(prop)) {
+                return {
+                    enumerable: true,
+                    configurable: true,
+                    value: Reflect.get(target, prop),
+                };
+            }
+            return undefined;
+        },
+    });
+}
+
+const DEFAULT_RETRY_DELAY = 60_000; // milliseconds
+const DEFAULT_RETRY_ATTEMPTS = 10;
+/**
+ * Creates a stream from a stream function
+ *
+ * If the stream fails, an attempt will be made to restart it.
+ *
+ * Ending the stream is terminal: no callbacks are invoked and no native
+ * stream is created after the stream ends.
+ *
+ * This function is not intended to be used directly.
+ *
+ * @param streamFunction - The stream function to create a stream from
+ * @param streamValueMutator - An optional function to mutate the value emitted from the stream
+ * @param options - The options for the stream
+ * @returns An async iterable stream proxy
+ * @throws {StreamInvalidRetryAttemptsError} if the retryAttempts option is less than 0 and retryOnFail is true
+ * @throws {StreamFailedError} if the stream fails and can't be restarted
+ */
+const createStream = async (streamFunction, streamValueMutator, options) => {
+    const { onEnd, onError, onFail, onRestart, onRetry, onValue, retryAttempts = DEFAULT_RETRY_ATTEMPTS, retryDelay = DEFAULT_RETRY_DELAY, retryOnFail = true, } = options ?? {};
+    // retry attempts must be greater than 0
+    if (retryOnFail && retryAttempts < 0) {
+        throw new StreamInvalidRetryAttemptsError();
+    }
+    const asyncStream = new AsyncStream();
+    // lifecycle state, owned by this wrapper
+    let stopped = false;
+    // reading the flag through a function call defeats TS control-flow
+    // narrowing, which cannot see the closure mutation across awaits
+    const isStopped = () => stopped;
+    let currentCloser;
+    let retryTimer;
+    let retryInFlight = false;
+    // set when a restart's native stream closes during its own creation, so the
+    // completed attempt reschedules instead of installing an already-dead closer
+    let closePendingDuringRestart = false;
+    // read through a call so no-unnecessary-condition cannot narrow the flag to
+    // a constant; handleNativeClose mutates it across an await
+    const isClosePending = () => closePendingDuringRestart;
+    // the retry budget is monotonic: it is never reset for the lifetime of
+    // this wrapper, so restarts are bounded even across successful restarts
+    let remainingRetries = retryAttempts;
+    // terminal transition: cancel any pending retry, close the active native
+    // stream, and notify onEnd exactly once
+    const stop = () => {
+        if (isStopped()) {
+            return;
+        }
+        stopped = true;
+        closePendingDuringRestart = false;
+        if (retryTimer !== undefined) {
+            clearTimeout(retryTimer);
+            retryTimer = undefined;
+        }
+        currentCloser?.end();
+        currentCloser = undefined;
+        onEnd?.();
+    };
+    // registered before any async work so ending the stream is always terminal,
+    // even while a retry is pending or a native stream is being created
+    asyncStream.onDone = stop;
+    const fail = (error) => {
+        if (isStopped()) {
+            return;
+        }
+        // the terminal transition must run even if onError throws, otherwise a
+        // throwing consumer callback leaves the stream open and hangs next()
+        try {
+            onError?.(error);
+        }
+        finally {
+            void asyncStream.end();
+        }
+    };
+    const handleAsyncError = (error) => {
+        if (!isStopped()) {
+            onError?.(error);
+        }
+    };
+    const streamCallback = (error, value) => {
+        // an ended stream must not invoke any callbacks
+        if (isStopped()) {
+            return;
+        }
+        // if a stream error occurs, call the onError callback
+        if (error) {
+            onError?.(error);
+            return;
+        }
+        // ensure the value is not undefined
+        if (value !== undefined) {
+            try {
+                // if a streamValueMutator is provided, mutate the value
+                if (streamValueMutator) {
+                    const mutatedValue = streamValueMutator(value);
+                    if (isPromise(mutatedValue)) {
+                        void mutatedValue
+                            .then((mutatedValue) => {
+                            // the stream may have ended while the value was mutating
+                            if (!isStopped() && mutatedValue !== undefined) {
+                                asyncStream.push(mutatedValue);
+                                return onValue?.(mutatedValue);
+                            }
+                        })
+                            .catch(handleAsyncError);
+                    }
+                    else {
+                        // a synchronous mutator may have ended the stream; gate delivery
+                        // on the stopped flag to match the async branch above
+                        if (!isStopped() && mutatedValue !== undefined) {
+                            asyncStream.push(mutatedValue);
+                            void Promise.resolve(onValue?.(mutatedValue)).catch(handleAsyncError);
+                        }
+                    }
+                }
+                else {
+                    asyncStream.push(value);
+                    void Promise.resolve(onValue?.(value)).catch(handleAsyncError);
+                }
+            }
+            catch (error) {
+                onError?.(error);
+            }
+        }
+    };
+    const scheduleRetry = () => {
+        // at most one retry may be in flight per wrapper
+        if (isStopped() || retryInFlight) {
+            return;
+        }
+        if (remainingRetries <= 0) {
+            fail(new StreamFailedError(retryAttempts));
+            return;
+        }
+        retryInFlight = true;
+        retryTimer = setTimeout(() => {
+            retryTimer = undefined;
+            void attemptRestart();
+        }, retryDelay);
+    };
+    const attemptRestart = async () => {
+        if (isStopped()) {
+            retryInFlight = false;
+            return;
+        }
+        // scope the pending-close flag to this attempt: a close recorded while the
+        // retry timer was merely pending belongs to the stream that scheduled it
+        closePendingDuringRestart = false;
+        remainingRetries -= 1;
+        onRetry?.(retryAttempts - remainingRetries, retryAttempts);
+        if (isStopped()) {
+            // onRetry may have ended the stream; do not open a native stream after
+            // termination
+            retryInFlight = false;
+            return;
+        }
+        try {
+            // attempt to restart the stream
+            const streamCloser = await streamFunction(streamCallback, handleNativeClose);
+            if (isStopped()) {
+                // the stream ended while the native stream was being created
+                streamCloser.end();
+                retryInFlight = false;
+                return;
+            }
+            await streamCloser.waitForReady();
+            if (isStopped()) {
+                streamCloser.end();
+                retryInFlight = false;
+                return;
+            }
+            if (isClosePending()) {
+                // the replacement stream closed during its own creation; discard it
+                // and schedule a fresh attempt instead of installing a dead closer
+                closePendingDuringRestart = false;
+                streamCloser.end();
+                retryInFlight = false;
+                scheduleRetry();
+                return;
+            }
+            currentCloser = streamCloser;
+            retryInFlight = false;
+            // stream restarted, call the onRestart callback
+            onRestart?.();
+        }
+        catch (error) {
+            retryInFlight = false;
+            if (isStopped()) {
+                return;
+            }
+            closePendingDuringRestart = false;
+            onError?.(error);
+            scheduleRetry();
+        }
+    };
+    const handleNativeClose = () => {
+        // ending the stream closes the native stream, which still triggers this
+        // callback; only an unexpected close is a failure
+        if (isStopped()) {
+            return;
+        }
+        currentCloser = undefined;
+        onFail?.();
+        if (retryOnFail) {
+            // a native close during an in-flight restart is dropped by the
+            // single-flight guard; record it so the completed attempt reschedules
+            // instead of installing a stream that already died
+            if (retryInFlight) {
+                closePendingDuringRestart = true;
+                return;
+            }
+            scheduleRetry();
+        }
+        else {
+            fail(new StreamFailedError(0));
+        }
+    };
+    try {
+        // create the stream
+        const streamCloser = await streamFunction(streamCallback, handleNativeClose);
+        if (isStopped()) {
+            streamCloser.end();
+        }
+        else {
+            await streamCloser.waitForReady();
+            if (isStopped()) {
+                streamCloser.end();
+            }
+            else {
+                currentCloser = streamCloser;
+            }
+        }
+    }
+    catch (error) {
+        onError?.(error);
+        if (retryOnFail) {
+            scheduleRetry();
+        }
+        else {
+            fail(new StreamFailedError(0));
+        }
     }
-}
+    // return a proxy for the async stream
+    return createAsyncStreamProxy(asyncStream);
+};
 
 /**
  * Manages conversations
@@ -1447,14 +1686,14 @@ class Conversations {
         this.#conversations = conversations;
     }
     get topic() {
-        return `/xmtp/mls/1/w-${this.#client.installationId}/proto`;
+        return `01${this.#client.installationId}`;
     }
     /**
      * Retrieves a conversation by its ID
      *
      * @param id - The conversation ID to look up
      * @returns The conversation if found, undefined otherwise
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#conversation-helper-methods
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     async getConversationById(id) {
         try {
@@ -1479,7 +1718,7 @@ class Conversations {
      *
      * @param inboxId - The inbox ID to look up
      * @returns The DM if found, undefined otherwise
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#conversation-helper-methods
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     getDmByInboxId(inboxId) {
         try {
@@ -1496,7 +1735,7 @@ class Conversations {
      *
      * @param identifier - The identifier to look up
      * @returns Promise that resolves with the DM, if found
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#conversation-helper-methods
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     async fetchDmByIdentifier(identifier) {
         const inboxId = await this.#client.fetchInboxIdByIdentifier(identifier);
@@ -1510,7 +1749,7 @@ class Conversations {
      *
      * @param id - The message ID to look up
      * @returns The decoded message if found, undefined otherwise
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#conversation-helper-methods
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     getMessageById(id) {
         try {
@@ -1527,7 +1766,7 @@ class Conversations {
      *
      * @param options - Optional group creation options
      * @returns The new group
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#optimistically-create-a-new-group-chat
+     * @see https://docs.xmtp.org/sdk/conversations/#optimistically-create-a-group
      */
     createGroupOptimistic(options) {
         const group = this.#conversations.createGroupOptimistic(options);
@@ -1539,7 +1778,7 @@ class Conversations {
      * @param identifiers - Array of identifiers for group members
      * @param options - Optional group creation options
      * @returns The new group
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#create-a-new-group-chat
+     * @see https://docs.xmtp.org/sdk/conversations/#create-a-group
      */
     async createGroupWithIdentifiers(identifiers, options) {
         const group = await this.#conversations.createGroupByIdentity(identifiers, options);
@@ -1552,7 +1791,7 @@ class Conversations {
      * @param inboxIds - Array of inbox IDs for group members
      * @param options - Optional group creation options
      * @returns The new group
-     * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#create-a-new-group-chat
+     * @see https://docs.xmtp.org/sdk/conversations/#create-a-group
      */
     async createGroup(inboxIds, options) {
         const group = await this.#conversations.createGroup(inboxIds, options);
@@ -1565,7 +1804,7 @@ class Conversations {
      * @param identifier - Identifier for the DM recipient
      * @param options - Optional DM creation options
      * @returns The new DM
-     * @see https://docs.xmtp.org/agents/build-agents/create-conversations#by-ethereum-address-1
+     * @see https://docs.xmtp.org/sdk/conversations/#create-a-dm
      */
     async createDmWithIdentifier(identifier, options) {
         const group = await this.#conversations.createDmByIdentity(identifier, options);
@@ -1578,7 +1817,7 @@ class Conversations {
      * @param inboxId - Inbox ID for the DM recipient
      * @param options - Optional DM creation options
      * @returns The new DM
-     * @see https://docs.xmtp.org/agents/build-agents/create-conversations#by-inbox-id-1
+     * @see https://docs.xmtp.org/sdk/conversations/#create-a-dm
      */
     async createDm(inboxId, options) {
         const group = await this.#conversations.createDm(inboxId, options);
@@ -1590,7 +1829,7 @@ class Conversations {
      *
      * @param options - Optional filtering and pagination options
      * @returns Array of conversations
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/list
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     async list(options) {
         const groups = this.#conversations.list(options);
@@ -1613,7 +1852,7 @@ class Conversations {
      *
      * @param options - Optional filtering and pagination options
      * @returns Array of groups
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/list#list-existing-conversations
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     listGroups(options) {
         const groups = this.#conversations.list({
@@ -1630,7 +1869,7 @@ class Conversations {
      *
      * @param options - Optional filtering and pagination options
      * @returns Array of DMs
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/list#list-existing-conversations
+     * @see https://docs.xmtp.org/sdk/conversations/
      */
     listDms(options) {
         const groups = this.#conversations.list({
@@ -1646,7 +1885,7 @@ class Conversations {
      * Synchronizes conversations for the current client from the network
      *
      * @returns Promise that resolves when sync is complete
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/sync-and-syncall
+     * @see https://docs.xmtp.org/sdk/sync/
      */
     async sync() {
         return this.#conversations.sync();
@@ -1657,7 +1896,7 @@ class Conversations {
      *
      * @param consentStates - Optional array of consent states to filter by
      * @returns Promise that resolves when sync is complete
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/sync-and-syncall#sync-all-new-welcomes-conversations-messages-and-preferences
+     * @see https://docs.xmtp.org/sdk/sync/
      */
     async syncAll(consentStates) {
         return this.#conversations.syncAll(consentStates);
@@ -1668,7 +1907,7 @@ class Conversations {
      * @param options - Optional stream options
      * @param options.conversationType - Optional conversation type to filter by
      * @returns Stream instance for new conversations
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/stream#stream-new-group-chat-and-dm-conversations
+     * @see https://docs.xmtp.org/sdk/stream/#stream-methods
      */
     async stream(options) {
         const stream = async (callback, onFail) => {
@@ -1697,7 +1936,7 @@ class Conversations {
      *
      * @param options - Optional stream options
      * @returns Stream instance for new group conversations
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/stream#stream-new-group-chat-and-dm-conversations
+     * @see https://docs.xmtp.org/sdk/stream/#stream-methods
      */
     async streamGroups(options) {
         const stream = async (callback, onFail) => {
@@ -1716,7 +1955,7 @@ class Conversations {
      *
      * @param options - Optional stream options
      * @returns Stream instance for new DM conversations
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/stream#stream-new-group-chat-and-dm-conversations
+     * @see https://docs.xmtp.org/sdk/stream/#stream-methods
      */
     async streamDms(options) {
         const stream = async (callback, onFail) => {
@@ -1731,37 +1970,42 @@ class Conversations {
         return createStream(stream, convertConversation, options);
     }
     /**
-     * Creates a stream for all new messages
+     * Reads retained messages after each group's default acknowledgement position.
+     * Set `from` to replay after a cursor without changing default progress.
+     * Set `onValue` for callback mode, or request items with the iterator.
+     * Core owns network recovery. Legacy retry options and `disableSync` do not apply.
      *
      * @param options - Optional stream options
      * @param options.conversationType - Optional conversation type to filter by
      * @param options.consentStates - Optional array of consent states to filter by
      * @returns Stream instance for new messages
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/stream#stream-new-group-chat-and-dm-messages
+     * @see https://docs.xmtp.org/sdk/stream/#stream-methods
      */
     async streamAllMessages(options) {
-        const streamAllMessages = async (callback, onFail) => {
-            if (!options?.disableSync) {
-                await this.syncAll(options?.consentStates);
-            }
-            return this.#conversations.streamAllMessages(callback, onFail, options?.conversationType, options?.consentStates);
-        };
-        const convertMessage = (value) => {
+        const reader = await this.#conversations.messageReader(options?.groupIds, options?.conversationType, options?.consentStates, options?.from);
+        const convertMessage = (value, cursor) => {
             const enrichedMessage = this.getMessageById(value.id);
-            if (enrichedMessage === undefined) {
-                console.warn(`Streamed message with ID "${value.id}" not found`);
+            if (enrichedMessage !== undefined) {
+                assertMessageDecodedForDelivery(enrichedMessage);
+                enrichedMessage.deliveryCursor = cursor;
             }
             return enrichedMessage;
         };
-        return createStream(streamAllMessages, convertMessage, options);
+        return new MessageStream(reader, convertMessage, options);
+    }
+    messageHistorySnapshot(limit, options) {
+        return this.#conversations.messageHistorySnapshot(limit, options?.groupIds, options?.conversationType, options?.consentStates);
+    }
+    beginningDeliveryCursor() {
+        return this.#conversations.beginningDeliveryCursor();
     }
     /**
-     * Creates a stream for all new group messages
+     * Reads retained group messages with default progress or an explicit replay cursor.
      *
      * @param options - Optional stream options
      * @param options.consentStates - Optional array of consent states to filter by
      * @returns Stream instance for new group messages
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/stream#stream-new-group-chat-and-dm-messages
+     * @see https://docs.xmtp.org/sdk/stream/#stream-methods
      */
     async streamAllGroupMessages(options) {
         return this.streamAllMessages({
@@ -1771,12 +2015,12 @@ class Conversations {
         });
     }
     /**
-     * Creates a stream for all new DM messages
+     * Reads retained DM messages with default progress or an explicit replay cursor.
      *
      * @param options - Optional stream options
      * @param options.consentStates - Optional array of consent states to filter by
      * @returns Stream instance for new DM messages
-     * @see https://docs.xmtp.org/chat-apps/list-stream-sync/stream#stream-new-group-chat-and-dm-messages
+     * @see https://docs.xmtp.org/sdk/stream/#stream-methods
      */
     async streamAllDmMessages(options) {
         return this.streamAllMessages({
@@ -1825,7 +2069,7 @@ class Conversations {
      * Gets the HMAC keys for all conversations
      *
      * @returns The HMAC keys for all conversations
-     * @see https://docs.xmtp.org/chat-apps/push-notifs/push-notifs#get-hmac-keys-for-a-conversation
+     * @see https://docs.xmtp.org/sdk/push-notifications/
      */
     hmacKeys() {
         return this.#conversations.hmacKeys();
@@ -1963,18 +2207,150 @@ class Preferences {
     }
 }
 
+/**
+ * Typed failures for the deployment configuration a backend publishes
+ * (spec 006 §7, CFG-083).
+ *
+ * The bindings report every one of these as an `Error` whose message begins
+ * with `[ClientError::<Variant>]`. Matching on that string is what this module
+ * removes: each of the six documented codes becomes its own class, so an app
+ * writes `error instanceof BackendMismatchError` instead of a regular
+ * expression over a message that may be reworded.
+ *
+ * Every class keeps the binding's message and the original error as `cause`,
+ * so the identifiers, versions, scopes, or chain the core reported are still
+ * readable for diagnostics.
+ */
+/**
+ * Base class of the six configuration failures. Catch this to handle any of
+ * them; catch a subclass to handle one.
+ */
+class ServerConfigurationError extends Error {
+    code;
+    constructor(
+    /** The stable code the bindings reported, e.g. `ClientError::AuthRequired`. */
+    code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "ServerConfigurationError";
+    }
+}
+/**
+ * The configuration could not be read: the deployment did not answer, answered
+ * `UNIMPLEMENTED` because it predates spec 006, or the copy could not be
+ * stored.
+ */
+class ConfigurationUnavailableError extends ServerConfigurationError {
+    constructor(message, options) {
+        super("ClientError::ConfigurationUnavailable", message, options);
+        this.name = "ConfigurationUnavailableError";
+    }
+}
+/**
+ * The deployment answered with a configuration no client can use: an empty or
+ * malformed identifier, an unparseable minimum version, or a chain that is not
+ * a CAIP-2 identifier. Nothing is stored.
+ */
+class ConfigurationInvalidError extends ServerConfigurationError {
+    constructor(message, options) {
+        super("ClientError::ConfigurationInvalid", message, options);
+        this.name = "ConfigurationInvalidError";
+    }
+}
+/**
+ * This database is bound to a different deployment. The identifier the backend
+ * published is not the one the database was created against. Recovery is a
+ * database created for the deployment the app now uses.
+ */
+class BackendMismatchError extends ServerConfigurationError {
+    constructor(message, options) {
+        super("ClientError::BackendMismatch", message, options);
+        this.name = "BackendMismatchError";
+    }
+}
+/** The deployment requires a newer libxmtp than this SDK is built on. */
+class ClientVersionTooOldError extends ServerConfigurationError {
+    constructor(message, options) {
+        super("ClientError::ClientVersionTooOld", message, options);
+        this.name = "ClientVersionTooOldError";
+    }
+}
+/**
+ * The deployment requires authentication and no credential source was
+ * configured. The message carries the scopes it requires.
+ */
+class AuthRequiredError extends ServerConfigurationError {
+    constructor(message, options) {
+        super("ClientError::AuthRequired", message, options);
+        this.name = "AuthRequiredError";
+    }
+}
+/**
+ * A smart contract wallet signature names a chain the deployment does not
+ * verify on. Raised before any network call, and only for signatures the app
+ * supplied.
+ */
+class ChainNotAcceptedError extends ServerConfigurationError {
+    constructor(message, options) {
+        super("ClientError::ChainNotAccepted", message, options);
+        this.name = "ChainNotAcceptedError";
+    }
+}
+const configurationCode = /^\[(ClientError::[A-Za-z]+)\]\s*([\s\S]*)$/;
+const build = (code, message, options) => {
+    switch (code) {
+        case "ClientError::ConfigurationUnavailable":
+            return new ConfigurationUnavailableError(message, options);
+        case "ClientError::ConfigurationInvalid":
+            return new ConfigurationInvalidError(message, options);
+        case "ClientError::BackendMismatch":
+            return new BackendMismatchError(message, options);
+        case "ClientError::ClientVersionTooOld":
+            return new ClientVersionTooOldError(message, options);
+        case "ClientError::AuthRequired":
+            return new AuthRequiredError(message, options);
+        case "ClientError::ChainNotAccepted":
+            return new ChainNotAcceptedError(message, options);
+        default:
+            return undefined;
+    }
+};
+/**
+ * Classifies an error from any SDK call as one of the six configuration
+ * failures, or `undefined` when it is something else.
+ *
+ * Use this where the SDK hands back the raw error, for instance a
+ * `ChainNotAcceptedError` raised deep inside a call that supplies a smart
+ * contract wallet signature.
+ */
+const toServerConfigurationError = (error) => {
+    if (!(error instanceof Error))
+        return undefined;
+    const match = configurationCode.exec(error.message);
+    if (!match)
+        return undefined;
+    return build(match[1], match[2], { cause: error });
+};
+/**
+ * Rethrows an error as its typed configuration failure, or unchanged when it
+ * is not one.
+ */
+const throwServerConfigurationError = (error) => {
+    throw toServerConfigurationError(error) ?? error;
+};
+
 const networkOptionKeys = [
     "env",
-    "apiUrl",
-    "gatewayHost",
+    "backendUrl",
     "appVersion",
+    "authCallback",
 ];
 const hasBackend = (options) => {
     return "backend" in options;
 };
 const resolveBackend$1 = async (options) => {
     if (!options) {
-        return createBackend();
+        throw new Error("backendUrl is required");
     }
     if (hasBackend(options)) {
         // Validate that no NetworkOptions fields are also set
@@ -1992,7 +2368,13 @@ const createClient = async (identifier, options) => {
     const backend = await resolveBackend$1(options);
     const inboxId = (await getInboxIdForIdentifier(backend, identifier)) ||
         generateInboxId(identifier, options?.nonce);
-    const env = envToString(backend.env);
+    const env = backend.env ?? "default";
+    // `env` only labels the database file, so it must stay one path component.
+    // Without this a value such as "../other" would move the database outside
+    // the working directory.
+    if (env === "" || /[/\\]/.test(env) || env === "." || env === "..") {
+        throw new Error("env must be a single path component");
+    }
     let dbPath;
     if (options?.dbPath === undefined) {
         // Default: auto-generated path
@@ -2011,6 +2393,8 @@ const createClient = async (identifier, options) => {
         level: options?.loggingLevel ?? "Off" /* LogLevel.Off */,
         stdoutLevel: options?.stdoutLoggingLevel,
         otelEndpoint: options?.otelEndpoint,
+        otelServiceName: options?.otelServiceName,
+        otelSampleRatio: options?.otelSampleRatio,
         resourceAttributes: options?.resourceAttributes,
     };
     const deviceSyncWorkerMode = options?.disableDeviceSync
@@ -2035,19 +2419,21 @@ const createClient = async (identifier, options) => {
     return { client, env };
 };
 
-/**
- * Resolves a `Backend` instance from either a `Backend` or an `XmtpEnv` string.
- *
- * @param envOrBackend - A `Backend` instance, or an `XmtpEnv` string
- * @param gatewayHost - Optional gateway host (only used when `envOrBackend` is an `XmtpEnv`)
- * @returns A `Backend` instance
- */
-const resolveBackend = async (envOrBackend, gatewayHost) => {
-    if (envOrBackend instanceof Backend) {
-        return envOrBackend;
+/** Resolve a backend from explicit network options or an existing backend. */
+const resolveBackend = async (optionsOrBackend) => {
+    if (optionsOrBackend instanceof Backend) {
+        return optionsOrBackend;
     }
-    return createBackend({ env: envOrBackend, gatewayHost });
+    return createBackend(optionsOrBackend);
 };
+/**
+ * Read a backend URL and app version from a bare URL, network options, or an
+ * existing backend. `fetchServerConfiguration` builds no backend of its own,
+ * so it needs the two values rather than a `Backend`.
+ */
+const resolveEndpoint = (target) => typeof target === "string"
+    ? { backendUrl: target }
+    : { backendUrl: target.backendUrl, appVersion: target.appVersion };
 const createEphemeralIdentifier = () => ({
     identifier: `0x${randomBytes(20).toString("hex")}`,
     identifierKind: 0 /* IdentifierKind.Ethereum */,
@@ -2096,7 +2482,10 @@ class Client {
             return;
         }
         this.#identifier = identifier;
-        const { client, env } = await createClient(identifier, this.#options);
+        // A build resolves the deployment configuration before any identity work,
+        // so its six failures (spec 006 CFG-041, CFG-044, CFG-052, CFG-060,
+        // CFG-062) surface here and are raised as their own types (CFG-083).
+        const { client, env } = await createClient(identifier, this.#options).catch(throwServerConfigurationError);
         this.#client = client;
         this.#env = env;
         const conversations = this.#client.conversations();
@@ -2116,7 +2505,7 @@ class Client {
         const client = new Client(options);
         client.#signer = signer;
         await client.init(identifier);
-        if (!options?.disableAutoRegister) {
+        if (!options.disableAutoRegister) {
             await client.register();
         }
         return client;
@@ -2152,12 +2541,12 @@ class Client {
         return this.#client?.appVersion();
     }
     /**
-     * Gets the XMTP environment the client is connected to
+     * Gets the label used for the default database file name
      *
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
     get env() {
-        if (!this.#env) {
+        if (this.#env === undefined) {
             throw new ClientNotInitializedError();
         }
         return this.#env;
@@ -2297,7 +2686,12 @@ class Client {
         const identifier = await finalSigner.getIdentifier();
         switch (finalSigner.type) {
             case "SCW":
-                await signatureRequest.addScwSignature(identifier, signature, finalSigner.getChainId(), finalSigner.getBlockNumber?.());
+                // The deployment publishes the chains it verifies on, so a signature
+                // for any other chain is rejected here, before any network call
+                // (spec 006 CFG-069, CFG-070).
+                await signatureRequest
+                    .addScwSignature(identifier, signature, finalSigner.getChainId(), finalSigner.getBlockNumber?.())
+                    .catch(throwServerConfigurationError);
                 break;
             case "EOA":
                 await signatureRequest.addEcdsaSignature(signature);
@@ -2537,15 +2931,21 @@ class Client {
         await this.unsafe_addSignature(signatureRequest);
         await this.unsafe_applySignatureRequest(signatureRequest);
     }
-    static async revokeInstallations(signer, inboxId, installationIds, envOrBackend, gatewayHost) {
-        const backend = await resolveBackend(envOrBackend, gatewayHost);
+    /** Revoke installations with an explicit backend or network options. */
+    static async revokeInstallations(signer, inboxId, installationIds, optionsOrBackend) {
+        const backend = await resolveBackend(optionsOrBackend);
         const identifier = await signer.getIdentifier();
         const signatureRequest = await revokeInstallationsSignatureRequest(backend, identifier, inboxId, installationIds);
         const signatureText = await signatureRequest.signatureText();
         const signature = await signer.signMessage(signatureText);
         switch (signer.type) {
             case "SCW":
-                await signatureRequest.addScwSignature(identifier, signature, signer.getChainId(), signer.getBlockNumber?.());
+                // Same chain restriction as the instance path: the deployment's
+                // accepted chains reject any other one here, before the network call
+                // (spec 006 CFG-069, CFG-070).
+                await signatureRequest
+                    .addScwSignature(identifier, signature, signer.getChainId(), signer.getBlockNumber?.())
+                    .catch(throwServerConfigurationError);
                 break;
             case "EOA":
                 await signatureRequest.addEcdsaSignature(signature);
@@ -2668,12 +3068,14 @@ class Client {
             return false;
         }
     }
-    static async fetchInboxStates(inboxIds, envOrBackend, gatewayHost) {
-        const backend = await resolveBackend(envOrBackend, gatewayHost);
+    /** Fetch inbox states with an explicit backend or network options. */
+    static async fetchInboxStates(inboxIds, optionsOrBackend) {
+        const backend = await resolveBackend(optionsOrBackend);
         return fetchInboxStatesByInboxIds(backend, inboxIds);
     }
-    static async fetchLatestInboxUpdatesCount(inboxIds, envOrBackend, gatewayHost) {
-        const backend = await resolveBackend(envOrBackend, gatewayHost);
+    /** Fetch inbox update counts with an explicit backend or network options. */
+    static async fetchLatestInboxUpdatesCount(inboxIds, optionsOrBackend) {
+        const backend = await resolveBackend(optionsOrBackend);
         // The node-bindings Client is a napi-rs class with no explicit close/free
         // method. Release is non-deterministic: once this reference goes out of
         // scope, JS GC will eventually invoke the Rust Drop impl and reclaim the
@@ -2687,9 +3089,9 @@ class Client {
         const result = await client.fetchInboxUpdatesCount(inboxIds, true);
         return toInboxUpdatesCountMap(result);
     }
-    /* eslint-enable @typescript-eslint/unified-signatures */
-    static async canMessage(identifiers, envOrBackend) {
-        const backend = await resolveBackend(envOrBackend);
+    /** Check identifiers with an explicit backend or network options. */
+    static async canMessage(identifiers, optionsOrBackend) {
+        const backend = await resolveBackend(optionsOrBackend);
         const canMessageMap = new Map();
         for (const identifier of identifiers) {
             const inboxId = await getInboxIdForIdentifier(backend, identifier);
@@ -2714,12 +3116,14 @@ class Client {
             return false;
         }
     }
-    static async isAddressAuthorized(inboxId, address, envOrBackend, gatewayHost) {
-        const backend = await resolveBackend(envOrBackend, gatewayHost);
+    /** Check address authorization with an explicit backend or network options. */
+    static async isAddressAuthorized(inboxId, address, optionsOrBackend) {
+        const backend = await resolveBackend(optionsOrBackend);
         return await isAddressAuthorized(backend, inboxId, address);
     }
-    static async isInstallationAuthorized(inboxId, installation, envOrBackend, gatewayHost) {
-        const backend = await resolveBackend(envOrBackend, gatewayHost);
+    /** Check installation authorization with an explicit backend or network options. */
+    static async isInstallationAuthorized(inboxId, installation, optionsOrBackend) {
+        const backend = await resolveBackend(optionsOrBackend);
         return await isInstallationAuthorized(backend, inboxId, installation);
     }
     /**
@@ -2734,75 +3138,6 @@ class Client {
             excludeDisappearingMessages: false,
         };
     }
-    /**
-     * Get the default server URL based on the environment
-     */
-    #getDefaultServerUrl() {
-        const env = this.env;
-        return HistorySyncUrls[env];
-    }
-    /**
-     * Send a sync request to other devices on the network
-     *
-     * @param options - Archive options specifying what to sync (defaults to consent and messages)
-     * @param serverUrl - The server URL for the sync request (defaults to environment-specific URL)
-     * @returns Promise that resolves when the sync request is sent
-     */
-    async sendSyncRequest(options, serverUrl) {
-        if (!this.#client) {
-            throw new ClientNotInitializedError();
-        }
-        const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
-        const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
-        return this.#client
-            .deviceSync()
-            .sendSyncRequest(resolvedOptions, resolvedServerUrl);
-    }
-    /**
-     * Send a sync archive to the sync group
-     *
-     * @param pin - The pin used for reference when importing
-     * @param options - Archive options specifying what to sync (defaults to consent and messages)
-     * @param serverUrl - The server URL for the sync archive (defaults to environment-specific URL)
-     * @returns Promise that resolves when the sync archive is sent
-     */
-    async sendSyncArchive(pin, options, serverUrl) {
-        if (!this.#client) {
-            throw new ClientNotInitializedError();
-        }
-        const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
-        const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
-        return this.#client
-            .deviceSync()
-            .sendSyncArchive(resolvedOptions, resolvedServerUrl, pin);
-    }
-    /**
-     * Process a sync archive that matches the pin given
-     *
-     * @param archivePin - Optional pin to match. If not provided, processes the last archive sent
-     * @returns Promise that resolves when the archive is processed
-     */
-    async processSyncArchive(archivePin) {
-        if (!this.#client) {
-            throw new ClientNotInitializedError();
-        }
-        return this.#client.deviceSync().processSyncArchive(archivePin);
-    }
-    /**
-     * List the archives available for import in the sync group
-     *
-     * You may need to manually sync the sync group before calling
-     * this function to see recently uploaded archives.
-     *
-     * @param daysCutoff - Number of days to look back for archives
-     * @returns Array of available archive information
-     */
-    listAvailableArchives(daysCutoff) {
-        if (!this.#client) {
-            throw new ClientNotInitializedError();
-        }
-        return this.#client.deviceSync().listAvailableArchives(daysCutoff);
-    }
     /**
      * Archive application elements to file for later restoration
      *
@@ -2857,7 +3192,230 @@ class Client {
         }
         return this.#client.deviceSync().syncAllDeviceSyncGroups();
     }
+    /** Enable notifications and register the delivery channel. */
+    async enableNotifications(config) {
+        if (!this.#client)
+            throw new ClientNotInitializedError();
+        try {
+            return toNotificationState(await this.#client.enableNotifications(toBindingNotificationConfig(config)));
+        }
+        catch (error) {
+            return throwNotificationError(error);
+        }
+    }
+    /** Disable notifications. Per-conversation overrides remain stored. */
+    async disableNotifications() {
+        if (!this.#client)
+            throw new ClientNotInitializedError();
+        try {
+            await this.#client.disableNotifications();
+        }
+        catch (error) {
+            throwNotificationError(error);
+        }
+    }
+    /** Read the local state without a backend request. */
+    notificationState() {
+        return Promise.resolve().then(() => {
+            if (!this.#client)
+                throw new ClientNotInitializedError();
+            return toNotificationState(this.#client.notificationState());
+        });
+    }
+    /**
+     * What the deployment published about itself, as this client resolved it
+     * when it was built (spec 006 CFG-030, CFG-080).
+     *
+     * Reads memory and makes no backend request. The value never changes for the
+     * life of the client: a background refresh rewrites the stored copy, and a
+     * new value takes effect at the next build.
+     *
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    serverConfiguration() {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.serverConfiguration();
+    }
+    /**
+     * Fetch the deployment configuration now, rewrite the stored copy, and
+     * return what was fetched (spec 006 CFG-082).
+     *
+     * The snapshot this client holds is unchanged; use it to observe a change an
+     * operator has made without restarting.
+     *
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     * @throws {ConfigurationUnavailableError} if the deployment did not answer
+     * @throws {ConfigurationInvalidError} if it published an unusable configuration
+     * @throws {BackendMismatchError} if it published a different identifier
+     * @throws {ClientVersionTooOldError} if it now requires a newer libxmtp
+     */
+    async refreshServerConfiguration() {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client
+            .refreshServerConfiguration()
+            .catch(throwServerConfigurationError);
+    }
+    /**
+     * Read what a deployment publishes about itself with no database, no client,
+     * and no credential (spec 006 CFG-081, CFG-045).
+     *
+     * Lets an app learn `auth.enabled`, `auth.requiredScopes`, and the accepted
+     * smart contract wallet chains before it decides how to build a client.
+     * Nothing is stored and no identifier binding is applied.
+     *
+     * @param target - A backend URL, network options, or an existing backend
+     * @throws {ConfigurationUnavailableError} if the deployment did not answer
+     * @throws {ConfigurationInvalidError} if it published an unusable configuration
+     */
+    static async fetchServerConfiguration(target) {
+        const { backendUrl, appVersion } = resolveEndpoint(target);
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Validate options from JavaScript callers.
+        if (!backendUrl?.trim()) {
+            throw new Error("backendUrl is required");
+        }
+        return fetchServerConfiguration(backendUrl, appVersion).catch(throwServerConfigurationError);
+    }
 }
 
-export { AccountAlreadyAssociatedError, ApiUrls, Client, ClientNotInitializedError, Conversation, Conversations, DecodedMessage, Dm, Group, HistorySyncUrls, InboxReassignError, MissingContentTypeError, SignerUnavailableError, StreamFailedError, StreamInvalidRetryAttemptsError, createBackend, envToString, generateInboxId, getInboxIdForIdentifier, isActions, isAttachment, isGroupUpdated, isHexString, isIntent, isLeaveRequest, isMarkdown, isMultiRemoteAttachment, isReaction, isReadReceipt, isRemoteAttachment, isReply, isText, isTextReply, isTransactionReference, isWalletSendCalls, validHex };
+const streamFailureMarker = "\n[XMTP_STREAM_FAILURE_V1]";
+const maxCursor = (1n << 64n) - 1n;
+/**
+ * Reads structured progress from a stream, sync, or publication error.
+ * All sequence values are exact bigints. Invalid or absent details return undefined.
+ * A published-but-unconfirmed error does not mean that publication failed.
+ */
+const getStreamFailureDetails = (error) => {
+    try {
+        const message = typeof error === "string" ? error : readObject(error).message;
+        if (typeof message !== "string")
+            return undefined;
+        const marker = message.lastIndexOf(streamFailureMarker);
+        if (marker === -1)
+            return undefined;
+        const details = readObject(JSON.parse(message.slice(marker + streamFailureMarker.length)));
+        return {
+            kind: readChoice(details.kind, [
+                "barrier",
+                "published_but_unconfirmed",
+                "catch_up",
+            ]),
+            code: readString(details.code),
+            message: readString(details.message),
+            retryable: readBoolean(details.retryable),
+            intentId: readNullable(details.intentId, readIntentId),
+            publishedIntentIds: readArray(details.publishedIntentIds, readIntentId),
+            summary: readNullable(details.summary, (value) => {
+                const summary = readObject(value);
+                return {
+                    messages: readCursor(summary.messages),
+                    conversations: readCursor(summary.conversations),
+                    failed: readCursor(summary.failed),
+                    completed: readBoolean(summary.completed),
+                };
+            }),
+            barriers: readArray(details.barriers, readBarrier),
+        };
+    }
+    catch {
+        return undefined;
+    }
+};
+const readBarrier = (value) => {
+    const barrier = readObject(value);
+    return {
+        reason: readChoice(barrier.reason, ["blocked", "deadline", "cancelled"]),
+        unfinished: readArray(barrier.unfinished, (value) => {
+            const topic = readObject(value);
+            return {
+                topic: readTopic(topic.topic),
+                target: readNullable(topic.target, readCursor),
+                received: readCursor(topic.received),
+                processed: readCursor(topic.processed),
+                unresolvedWelcomes: readArray(topic.unresolvedWelcomes, readCursor),
+                inactive: readBoolean(topic.inactive),
+                cause: readNullable(topic.cause, (value) => {
+                    const cause = readObject(value);
+                    return {
+                        kind: readChoice(cause.kind, [
+                            "target_pending",
+                            "receipt_pending",
+                            "processing_pending",
+                            "blocked",
+                            "storage",
+                            "receiver",
+                            "invalid_topic",
+                        ]),
+                        code: readNullable(cause.code, readString),
+                        message: readString(cause.message),
+                        retryable: readBoolean(cause.retryable),
+                    };
+                }),
+            };
+        }),
+    };
+};
+const readObject = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Invalid stream failure object");
+    }
+    return value;
+};
+const readString = (value) => {
+    if (typeof value !== "string")
+        throw new Error("Invalid stream failure text");
+    return value;
+};
+const readBoolean = (value) => {
+    if (typeof value !== "boolean")
+        throw new Error("Invalid stream failure flag");
+    return value;
+};
+const readChoice = (value, choices) => {
+    const choice = choices.find((choice) => choice === value);
+    if (choice === undefined)
+        throw new Error("Invalid stream failure kind");
+    return choice;
+};
+const readNullable = (value, read) => (value === null ? null : read(value));
+const readArray = (value, read) => {
+    if (!Array.isArray(value))
+        throw new Error("Invalid stream failure list");
+    return value.map(read);
+};
+const readCursor = (value) => {
+    const cursor = readString(value);
+    if (!/^(0|[1-9][0-9]*)$/.test(cursor)) {
+        throw new Error("Invalid stream failure sequence");
+    }
+    const number = BigInt(cursor);
+    if (number > maxCursor)
+        throw new Error("Stream failure sequence is too large");
+    return number;
+};
+const readIntentId = (value) => {
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < -2147483648 ||
+        value > 2147483647) {
+        throw new Error("Invalid stream failure intent ID");
+    }
+    return value;
+};
+const readTopic = (value) => {
+    const hex = readString(value);
+    if (!/^(?:[0-9a-fA-F]{2})*$/.test(hex)) {
+        throw new Error("Invalid stream failure topic");
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < bytes.length; index++) {
+        bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+};
+
+export { AccountAlreadyAssociatedError, AuthRequiredError, BackendMismatchError, ChainNotAcceptedError, Client, ClientNotInitializedError, ClientVersionTooOldError, CodecRegistry, ConfigurationInvalidError, ConfigurationUnavailableError, Conversation, Conversations, DebugInformation, DecodedMessage, Dm, Group, InboxReassignError, MessageStream, MissingContentTypeError, NotificationError, Preferences, ServerConfigurationError, SignerUnavailableError, StreamFailedError, StreamInvalidRetryAttemptsError, createBackend, generateInboxId, getInboxIdForIdentifier, getStreamFailureDetails, isActions, isAttachment, isGroupUpdated, isHexString, isIntent, isLeaveRequest, isMarkdown, isMultiRemoteAttachment, isReaction, isReadReceipt, isRemoteAttachment, isReply, isText, isTextReply, isTransactionReference, isWalletSendCalls, throwServerConfigurationError, toServerConfigurationError, validHex };
 //# sourceMappingURL=index.js.map