From 845f9337cb07182221f569365246583d74baf0c5 Mon Sep 17 00:00:00 2001 From: rygine Date: Mon, 21 Aug 2023 20:59:37 +0000 Subject: [PATCH] deploy: 149c5a3974c0a62b8773fa71bd73751e693a1581 --- functions/getAttachment.html | 2 +- functions/getDbInstance.html | 2 +- functions/getMessageByXmtpID.html | 2 +- functions/getOriginalMessageFromReply.html | 2 +- functions/getReactionsByXmtpID.html | 2 +- functions/getReadReceipt.html | 2 +- functions/hasReaction.html | 2 +- functions/hasReadReceipt.html | 2 +- functions/hasReply.html | 2 +- functions/isValidAddress.html | 2 +- functions/processUnprocessedMessages.html | 2 +- functions/toCachedMessage.html | 2 +- functions/useCanMessage.html | 2 +- functions/useClient.html | 2 +- functions/useConversation.html | 2 +- functions/useConversations.html | 2 +- functions/useDb.html | 2 +- functions/useLastMessage.html | 2 +- functions/useMessages.html | 2 +- functions/useReactions.html | 2 +- functions/useReply.html | 2 +- functions/useResendMessage.html | 2 +- functions/useSendMessage.html | 2 +- functions/useStartConversation.html | 2 +- functions/useStreamAllMessages.html | 2 +- functions/useStreamConversations.html | 2 +- functions/useStreamMessages.html | 2 +- index.html | 318 ++++++++++++++----- types/CachedAttachmentsMetadata.html | 2 +- types/CachedConversation.html | 2 +- types/CachedConversationWithId.html | 2 +- types/CachedConversationsTable.html | 2 +- types/CachedMessage.html | 2 +- types/CachedMessageWithId.html | 2 +- types/CachedMessagesTable.html | 2 +- types/CachedReaction.html | 2 +- types/CachedReactionsMetadata.html | 2 +- types/CachedReactionsTable.html | 2 +- types/CachedReadReceiptMetadata.html | 2 +- types/CachedRepliesMetadata.html | 2 +- types/ProcessUnprocessedMessagesOptions.html | 2 +- variables/attachmentContentTypeConfig.html | 2 +- variables/reactionContentTypeConfig.html | 2 +- variables/readReceiptContentTypeConfig.html | 2 +- variables/replyContentTypeConfig.html | 2 +- variables/textContentTypeConfig.html | 2 +- 46 files changed, 286 insertions(+), 122 deletions(-) diff --git a/functions/getAttachment.html b/functions/getAttachment.html index d659a1a7..61d110de 100644 --- a/functions/getAttachment.html +++ b/functions/getAttachment.html @@ -33,7 +33,7 @@

Returns +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/attachment.ts:29
    • diff --git a/functions/getDbInstance.html b/functions/getDbInstance.html index 27da055c..29fbf666 100644 --- a/functions/getDbInstance.html +++ b/functions/getDbInstance.html @@ -29,7 +29,7 @@
    Optional Returns Dexie
    +
  • Defined in packages/react-sdk/src/helpers/caching/db.ts:75
    • diff --git a/functions/getMessageByXmtpID.html b/functions/getMessageByXmtpID.html index 57730e2f..10754636 100644 --- a/functions/getMessageByXmtpID.html +++ b/functions/getMessageByXmtpID.html @@ -38,7 +38,7 @@

    Returns Promise<

    +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:88
    • diff --git a/functions/getOriginalMessageFromReply.html b/functions/getOriginalMessageFromReply.html index a0582787..6eb4a1f0 100644 --- a/functions/getOriginalMessageFromReply.html +++ b/functions/getOriginalMessageFromReply.html @@ -38,7 +38,7 @@

    Returns Promise<

    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reply.ts:71
    • diff --git a/functions/getReactionsByXmtpID.html b/functions/getReactionsByXmtpID.html index 23570156..917d5d30 100644 --- a/functions/getReactionsByXmtpID.html +++ b/functions/getReactionsByXmtpID.html @@ -38,7 +38,7 @@

    Returns Promise<

    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reaction.ts:106
    • diff --git a/functions/getReadReceipt.html b/functions/getReadReceipt.html index fc07cf6a..750a9760 100644 --- a/functions/getReadReceipt.html +++ b/functions/getReadReceipt.html @@ -34,7 +34,7 @@

    Returns undefined

    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/readReceipt.ts:26
    • diff --git a/functions/hasReaction.html b/functions/hasReaction.html index b9181771..86a5ed80 100644 --- a/functions/hasReaction.html +++ b/functions/hasReaction.html @@ -33,7 +33,7 @@

    Returns boolean

    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reaction.ts:139
    • diff --git a/functions/hasReadReceipt.html b/functions/hasReadReceipt.html index e8b14d04..51b9a90a 100644 --- a/functions/hasReadReceipt.html +++ b/functions/hasReadReceipt.html @@ -33,7 +33,7 @@

    Returns boolean

    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/readReceipt.ts:39
    • diff --git a/functions/hasReply.html b/functions/hasReply.html index 96413ed9..b99544ba 100644 --- a/functions/hasReply.html +++ b/functions/hasReply.html @@ -33,7 +33,7 @@

    Returns boolean

    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reply.ts:61
    • diff --git a/functions/isValidAddress.html b/functions/isValidAddress.html index a3482c12..2a8da630 100644 --- a/functions/isValidAddress.html +++ b/functions/isValidAddress.html @@ -33,7 +33,7 @@

    Returns boolean

    +
  • Defined in packages/react-sdk/src/helpers/isValidAddress.ts:7
    • diff --git a/functions/processUnprocessedMessages.html b/functions/processUnprocessedMessages.html index 3eafc97f..2ece15c2 100644 --- a/functions/processUnprocessedMessages.html +++ b/functions/processUnprocessedMessages.html @@ -29,7 +29,7 @@
    __namedParameters: Returns Promise<void>
    +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:465
    • diff --git a/functions/toCachedMessage.html b/functions/toCachedMessage.html index a069cf59..29f345fb 100644 --- a/functions/toCachedMessage.html +++ b/functions/toCachedMessage.html @@ -65,7 +65,7 @@
    walletAddressxmtpID: string
    +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:53
    • diff --git a/functions/useCanMessage.html b/functions/useCanMessage.html index eeb1fb4f..527b2f42 100644 --- a/functions/useCanMessage.html +++ b/functions/useCanMessage.html @@ -87,7 +87,7 @@
    errorisLoading: boolean
    +
  • Defined in packages/react-sdk/src/hooks/useCanMessage.ts:10
    • diff --git a/functions/useClient.html b/functions/useClient.html index 437318f9..cc9255ab 100644 --- a/functions/useClient.html +++ b/functions/useClient.html @@ -74,7 +74,7 @@
    isLoadingsigner: undefined | null | Signer
    +
  • Defined in packages/react-sdk/src/hooks/useClient.ts:29
    • diff --git a/functions/useConversation.html b/functions/useConversation.html index 931eee16..9ddca403 100644 --- a/functions/useConversation.html +++ b/functions/useConversation.html @@ -91,7 +91,7 @@
    Rest Returns Promise<boolean>
    +
  • Defined in packages/react-sdk/src/hooks/useConversation.ts:56
    • diff --git a/functions/useConversations.html b/functions/useConversations.html index 1b05606e..1ff5b3a7 100644 --- a/functions/useConversations.html +++ b/functions/useConversations.html @@ -37,7 +37,7 @@
    errorisLoading: boolean
    +
  • Defined in packages/react-sdk/src/hooks/useConversations.ts:25
    • diff --git a/functions/useDb.html b/functions/useDb.html index 1c4aba31..2d7af713 100644 --- a/functions/useDb.html +++ b/functions/useDb.html @@ -36,7 +36,7 @@

    Returns Promise<
    db: Dexie

    +
  • Defined in packages/react-sdk/src/hooks/useDb.ts:9
    • diff --git a/functions/useLastMessage.html b/functions/useLastMessage.html index 6ec16e0c..e199ce24 100644 --- a/functions/useLastMessage.html +++ b/functions/useLastMessage.html @@ -29,7 +29,7 @@
    topic: Returns undefined | CachedMessage<any, ContentTypeMetadata>
    +
  • Defined in packages/react-sdk/src/hooks/useLastMessage.ts:8
    • diff --git a/functions/useMessages.html b/functions/useMessages.html index 21c25861..ea087b18 100644 --- a/functions/useMessages.html +++ b/functions/useMessages.html @@ -40,7 +40,7 @@
    isLoadingmessages: CachedMessage<any, ContentTypeMetadata>[]
    +
  • Defined in packages/react-sdk/src/hooks/useMessages.ts:25
    • diff --git a/functions/useReactions.html b/functions/useReactions.html index 82175344..17e863d2 100644 --- a/functions/useReactions.html +++ b/functions/useReactions.html @@ -29,7 +29,7 @@
    Optional Returns CachedReaction[]
    +
  • Defined in packages/react-sdk/src/hooks/useReactions.ts:9
    • diff --git a/functions/useReply.html b/functions/useReply.html index 3a964ef0..56d0032e 100644 --- a/functions/useReply.html +++ b/functions/useReply.html @@ -32,7 +32,7 @@

    Returns { originalMessage: undefined | CachedMessage

    +
  • Defined in packages/react-sdk/src/hooks/useReply.ts:9
    • diff --git a/functions/useResendMessage.html b/functions/useResendMessage.html index bd01cb90..231ec43a 100644 --- a/functions/useResendMessage.html +++ b/functions/useResendMessage.html @@ -47,7 +47,7 @@
    message: Returns Promise<DecodedMessage>
    +
  • Defined in packages/react-sdk/src/hooks/useResendMessage.ts:9
    • diff --git a/functions/useSendMessage.html b/functions/useSendMessage.html index d9dfd2c0..0536358b 100644 --- a/functions/useSendMessage.html +++ b/functions/useSendMessage.html @@ -58,7 +58,7 @@
    Optional Returns Promise<DecodedMessage>
    +
  • Defined in packages/react-sdk/src/hooks/useSendMessage.ts:17
    • diff --git a/functions/useStartConversation.html b/functions/useStartConversation.html index 56f0620f..ff6ec0e9 100644 --- a/functions/useStartConversation.html +++ b/functions/useStartConversation.html @@ -58,7 +58,7 @@
    Optional Returns Promise<{
        cachedConversation: undefined | CachedConversationWithId;
        cachedMessage: undefined;
        conversation: undefined;
    } | {
        cachedConversation: CachedConversationWithId;
        cachedMessage: CachedMessage;
        conversation: Conversation;
    }>
    +
  • Defined in packages/react-sdk/src/hooks/useStartConversation.ts:15
    • diff --git a/functions/useStreamAllMessages.html b/functions/useStreamAllMessages.html index a6b8fa7b..fbf7dfe7 100644 --- a/functions/useStreamAllMessages.html +++ b/functions/useStreamAllMessages.html @@ -60,7 +60,7 @@

    Returns { error: null | Error

    +
  • Defined in packages/react-sdk/src/hooks/useStreamAllMessages.ts:15
    • diff --git a/functions/useStreamConversations.html b/functions/useStreamConversations.html index c505faa6..1bab7fee 100644 --- a/functions/useStreamConversations.html +++ b/functions/useStreamConversations.html @@ -33,7 +33,7 @@

    Returns { error: null | Error

    +
  • Defined in packages/react-sdk/src/hooks/useStreamConversations.ts:19
    • diff --git a/functions/useStreamMessages.html b/functions/useStreamMessages.html index ad133b63..777d9234 100644 --- a/functions/useStreamMessages.html +++ b/functions/useStreamMessages.html @@ -34,7 +34,7 @@

    Returns { error: null | Error

    +
  • Defined in packages/react-sdk/src/hooks/useStreamMessages.ts:22
    • diff --git a/index.html b/index.html index 185efe69..f01d7f17 100644 --- a/index.html +++ b/index.html @@ -12,124 +12,266 @@

    @xmtp/react-sdk

    -

    React XMTP client SDK

    Status

    +

    React XMTP client SDK

    Status

    This package provides the XMTP client SDK for React.

    -

    This SDK is in beta status and ready for you to start building with.

    -

    However, we do not recommend using beta software in production apps. Software in this status may change based on feedback.

    -

    To keep up with the latest SDK developments, see the Issues tab in this repo.

    -

    To learn more about XMTP and get answers to frequently asked questions, see the XMTP documentation.

    -

    x-red-sm

    -

    What's inside?

    Hooks

    These hooks are mostly bindings to the xmtp-js SDK that expose the underlying data in a React way.

    +

    To keep up with the latest SDK developments, see the Issues tab in this repo.

    +

    To learn more about XMTP and get answers to frequently asked questions, see the XMTP documentation.

    +

    What's inside?

    Hooks

    These hooks are mostly bindings to the xmtp-js SDK that expose the underlying data in a React way.

    Requirements

    • Node 18+
    • React 16.14+
    -

    Install

    # npm
    npm install @xmtp/react-sdk@preview

    # pnpm
    pnpm install @xmtp/react-sdk@preview

    # yarn
    yarn add @xmtp/react-sdk@preview
+
    Install
    # npm
    npm install @xmtp/react-sdk

    # pnpm
    pnpm install @xmtp/react-sdk

    # yarn
    yarn add @xmtp/react-sdk
 
    
 
    Create React App
    Requires the Buffer polyfill. See below.
    
-
    If you see a lot of warnings related to source maps, see this issue to learn more.
    
+
    If you see a lot of warnings related to source maps, see this issue to learn more.
    
 
    Vite
    Requires the Buffer polyfill. See below.
    
-
    Buffer polyfill
    The Node Buffer API must be polyfilled in some cases. To do so, add the buffer dependency to your project and then polyfill it in your entry file.
    
+
    Buffer polyfill
    The Node Buffer API must be polyfilled in some cases. To do so, add the buffer dependency to your project and then polyfill it in your entry file.
    
 
    Example
    
-
    import { Buffer } from "buffer";

    window.Buffer = window.Buffer ?? Buffer;
+
    import { Buffer } from "buffer";

    window.Buffer = window.Buffer ?? Buffer;
 
    
-
    Usage
    Add the provider
    To use the provided hooks, you must wrap your app with an XMTPProvider. This gives the hooks access to the XMTP client.
    
+
    Reference docs
    Access the XMTP React SDK reference documentation.
    
+
    Local-first architecture
    This client SDK uses a local-first architecture to help you build a production-grade and performant app. Using this local-first architecture, the client prioritizes using the local cache on the device where it’s running.
    
+
    For example, the client initially retrieves existing message data from the XMTP network and places it in the device’s local cache. As needed, the client asynchronously loads new and updated message data to the local cache. You then build your app to get message data from the local cache, which provides faster load times than getting data directly from the XMTP network.
    
+
    Here’s an overview of how your app frontend, local cache, client SDK, and the XMTP network work together in this local-first approach:
    
+Diagram illustrating local-first architecture
+
+
    Usage
    Add the provider
    To use the provided hooks, you must wrap your app with an XMTPProvider. This gives the hooks access to the XMTP client instance.
    
+
    
+
    Note
    There’s only one client instance per provider.
    
+
    
 
    Example
    
-
    createRoot(document.getElementById("root") as HTMLElement).render(
      <StrictMode>
        <XMTPProvider>
          <App />
        </XMTPProvider>
      </StrictMode>,
    );
+
    import { XMTPProvider } from "@xmtp/react-sdk";

    createRoot(document.getElementById("root") as HTMLElement).render(
      <StrictMode>
        <XMTPProvider>
          <App />
        </XMTPProvider>
      </StrictMode>,
    );
 
    
-
    Create a client
    The useClient hook allows you to initialize, disconnect, and access the XMTP client instance. It also exposes the error and loading states of the client.
    
-
    The hook requires passing in a connected wallet that implements the Signer interface.
    
-
    To learn more about this process, see Create a client in the xmtp-js SDK docs.
    
+
    Create a client
    The useClient hook allows you to initialize, access, and disconnect the XMTP client instance. It also exposes the error and loading states of the client.
    
+
    Initializing the client requires passing in a connected wallet that implements the Signer interface.
    
 
    Type
    
-
    import { Client } from "@xmtp/react-sdk";

    type InitClientArgs = {
      keys?: Uint8Array;
      options?: Partial<ClientOptions>;
      signer?: Signer | null;
    };

    const useClient: () => {
      client: Client | undefined;
      disconnect: () => void;
      error: unknown;
      initialize: (args?: InitClientArgs) => Promise<void>;
      isLoading: boolean;
    };
+
    import { Client } from "@xmtp/react-sdk";

    type InitClientArgs = {
      keys?: Uint8Array;
      options?: Partial<ClientOptions>;
      signer?: Signer | null;
    };

    const useClient: () => {
      client: Client | undefined;
      disconnect: () => void;
      error: unknown;
      initialize: (args?: InitClientArgs) => Promise<void>;
      isLoading: boolean;
    };
 
    
 
    Example
    
 
    export const CreateClient: React.FC<{ signer: Signer }> = ({ signer }) => {
      const { client, error, isLoading, initialize } = useClient();

      const handleConnect = useCallback(async () => {
        await initialize({ signer });
      }, [initialize]);

      if (error) {
        return "An error occurred while initializing the client";
      }

      if (isLoading) {
        return "Awaiting signatures...";
      }

      if (!client) {
        return (
          <button type="button" onClick={handleConnect}>
            Connect to XMTP
          </button>
        );
      }

      return "Connected to XMTP";
    };
 
    
-
    Configure the client
    To learn more about client configuration options, see Configure the client in the xmtp-js SDK docs.
    
-
    Create a client with private keys
    Manually handling private keys is not recommended unless a use case requires it.
    
-
    To learn more, see Manually handle private key storage in the xmtp-js SDK docs.
    
+
    Configure the client
    The client's network connection and key storage method can be configured with these optional parameters of Client.create:
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    ParameterDefaultDescription
    appVersionundefinedAdd a client app version identifier that's included with API requests.
    For example, you can use the following format: appVersion: APP_NAME + '/' + APP_VERSION.
    Setting this value provides telemetry that shows which apps are using the XMTP client SDK. This information can help XMTP developers provide app support, especially around communicating important SDK updates, including deprecations and required upgrades.
    envdevConnect to the specified XMTP network environment. Valid values include dev, production, or local. For important details about working with these environments, see XMTP production and dev network environments.
    apiUrlundefinedManually specify an API URL to use. If specified, value of env will be ignored.
    keystoreProviders[StaticKeystoreProvider, NetworkKeystoreProvider, KeyGeneratorKeystoreProvider]Override the default behavior of how the client creates a Keystore with a custom provider. This can be used to get the user's private keys from a different storage mechanism.
    persistConversationstrueMaintain a cache of previously seen V2 conversations in the storage provider (defaults to LocalStorage).
    skipContactPublishingfalseDo not publish the user's contact bundle to the network on client creation. Designed to be used in cases where the client session is short-lived (for example, decrypting a push notification), and where it is known that a client instance has been instantiated with this flag set to false at some point in the past.
    codecs[TextCodec]Add codecs to support additional content types.
    maxContentSize100MMaximum message content size in bytes.
    preCreateIdentityCallbackundefinedpreCreateIdentityCallback is a function that will be called immediately before a Create Identity wallet signature is requested from the user.
    preEnableIdentityCallbackundefinedpreEnableIdentityCallback is a function that will be called immediately before an Enable Identity wallet signature is requested from the user.
    
+
    Create a client with private keys
    Manually handling private keys is not recommended unless a use case requires it.
    
+
    The SDK will handle key storage for the user by encrypting the private key bundle using a signature generated from the wallet, and storing the encrypted payload on the XMTP network. This can be awkward for some server-side applications, where you may only want to give the application access to the XMTP keys but not your wallet keys. Mobile applications may also want to store keys in a secure enclave rather than rely on decrypting the remote keys on the network each time the application starts up.
    
+
    You can export the unencrypted key bundle using the static method Client.getKeys, save it somewhere secure, and then provide those keys at a later time to initialize a new client using the exported XMTP identity.
    
+
    The keys returned by getKeys should be treated with the utmost care as compromise of these keys will allow an attacker to impersonate the user on the XMTP network. Ensure these keys are stored somewhere secure and encrypted.
    
 
    Example
    
 
    import { Client, useClient } from "@xmtp/react-sdk";
    import type { Signer } from "@xmtp/react-sdk";

    export const CreateClientWithKeys: React.FC<{ signer: Signer }> = ({ signer }) => {
      const { initialize } = useClient();

      // initialize client on mount
      useEffect(() => {
        const init = async () => {
          // get the keys using a valid Signer
          const keys = await Client.getKeys(signer);
          // create a client using keys returned from getKeys
          await initialize({ keys, signer });
        };
        void init();
      }, []);

      return (
        ...
      );
    };
 
    
-
    List existing conversations
    The useConversations hook fetches all conversations with the current wallet on mount. It also exposes error and loading states.
    
+
    Check if an address is on the network
    The useCanMessage hook exposes both the client and static instances of the canMessage method. To check if a blockchain address is registered on the network before instantiating a client instance, use the canMessageStatic export.
    
 
    Type
    
-
    import type { Conversation } from "@xmtp/react-sdk";

    const useConversations: () => {
      conversations: Conversation[];
      error: unknown;
      isLoading: boolean;
    };
+
    type NetworkOptions = {
      env: "local" | "dev" | "production";
      apiUrl: string | undefined;
      appVersion?: string;
    };

    const useCanMessage: () => {
      canMessage: {
        (peerAddress: string): Promise<boolean>;
        (peerAddress: string[]): Promise<boolean[]>;
      };
      canMessageStatic: {
        (peerAddress: string, opts?: Partial<NetworkOptions>): Promise<boolean>;
        (peerAddress: string[], opts?: Partial<NetworkOptions>): Promise<boolean[]>;
      };
    };
+
    
+
    Example
    
+
    import { useCanMessage } from "@xmtp/react-sdk";

    export const CanMessage: React.FC = () => {
      const [peerAddress, setPeerAddress] = useState("");
      const [isOnNetwork, setIsOnNetwork] = useState(false);
      const [isLoading, setIsLoading] = useState(false);

      const { canMessage } = useCanMessage();

      const handleAddressChange = useCallback((e: React.KeyboardEvent<HTMLInputElement>) => {
        setPeerAddress(e.target.value);
      }, []);

      const handleCheckAddress = useCallback(async (e: FormEvent) => {
          e.preventDefault();
          if (isValidAddress(peerAddress)) {
            setIsLoading(true);
            setIsOnNetwork(await canMessage(peerAddress));
            setIsLoading(false);
          } else {
            setIsOnNetwork(false);
          }
        };
        void checkAddress();
      }, [peerAddress]);

      return (
        <form onSubmit={handleCheckAddress}>
          <input
            name="addressInput"
            type="text"
            onChange={handleAddressChange}
            disabled={isLoading}
          />
        </form>
      );
    };
+
    
+
    Handle conversations
    List existing conversations
    The useConversations hook fetches all conversations with the current wallet on mount. It also exposes error and loading states.
    
+
    Types
    
+
    import type { ContentTypeMetadata } from "@xmtp/react-sdk";

    type CachedConversation<M = ContentTypeMetadata> = {
      context?: InvitationContext;
      createdAt: Date;
      id?: number;
      isReady: boolean;
      metadata?: M;
      peerAddress: string;
      topic: string;
      updatedAt: Date;
      walletAddress: string;
    };

    const useConversations: (options?: UseConversationsOptions) => {
      conversations: CachedConversation<ContentTypeMetadata>[];
      error: Error | null;
      isLoading: boolean;
    };
 
    
 
    Example
    
 
    export const ListConversations: React.FC = () => {
      const { conversations, error, isLoading } = useConversations();

      if (error) {
        return "An error occurred while loading conversations";
      }

      if (isLoading) {
        return "Loading conversations...";
      }

      return (
        ...
      );
    };
 
    
-
    To learn more, see List existing conversations in the xmtp-js SDK docs.
    
-
    Listen for new conversations
    The useStreamConversations hook listens for new conversations in real-time and calls the passed callback when a new conversation is created. It also exposes an error state.
    
+
    Listen for new conversations
    The useStreamConversations hook listens for new conversations in real-time and calls the passed callback when a new conversation is created. It also exposes an error state.
    
 
    Type
    
-
    import type { Conversation } from "@xmtp/react-sdk";

    const useStreamConversations: (
      onConversation: (conversation: Conversation) => void,
    ) => {
      error: unknown;
    };
+
    import type { Conversation } from "@xmtp/react-sdk";

    const useStreamConversations: (
      onConversation: (conversation: Conversation) => void,
    ) => {
      error: unknown;
    };
 
    
 
    Example
    
 
    import { useCallback, useState } from "react";
    import { useStreamConversations } from "@xmtp/react-sdk";
    import type { Conversation } from "@xmtp/react-sdk";

    export const NewConversations: React.FC = () => {
      // track streamed conversations
      const [streamedConversations, setStreamedConversations] = useState<
        Conversation[]
      >([]);

      // callback to handle incoming conversations
      const onConversation = useCallback(
        (conversation: Conversation) => {
          setStreamedConversations((prev) => [...prev, conversation]);
        },
        [],
      );
      const { error } = useStreamConversations(onConversation);

      if (error) {
        return "An error occurred while streaming conversations";
      }

      return (
        ...
      );
    };
 
    
-
    To learn more, see Listen for new conversations in the xmtp-js SDK docs.
    
-
    Start a new conversation
    The useStartConversation hook starts a new conversation and sends an initial message to it.
    
+
    Start a new conversation
    The useStartConversation hook starts a new conversation and sends an initial message to it.
    
 
    Type
    
-
    import type {
      Conversation,
      InvitationContext,
      SendOptions,
    } from "@xmtp/react-sdk";

    const useStartConversation: <T = string>(
      options?: InvitationContext,
    ) => (
      peerAddress: string,
      message: T,
      sendOptions?: SendOptions,
    ) => Promise<Conversation | undefined>;
+
    const useStartConversation: (options?: UseStartConversation) => {
        error: unknown;
        isLoading: boolean;
        startConversation: <T = string>(peerAddress: string, content: T, contentType?: ContentTypeId, sendOptions?: SendMessageOptions) => Promise<{
            cachedConversation: CachedConversationWithId | undefined;
            cachedMessage: undefined;
            conversation: undefined;
        } | {
            ...;
        }>;
    }
 
    
 
    Example
    
 
    import { isValidAddress, useStartConversation } from "@xmtp/react-sdk";
    import { useCallback, useState } from "react";

    export const StartConversation: React.FC = () => {
      const [peerAddress, setPeerAddress] = useState("");
      const [message, setMessage] = useState("");
      const [isLoading, setIsLoading] = useState(false);

      const startConversation = useStartConversation();

      const handleAddressChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => {
          setPeerAddress(e.target.value);
        },
        [],
      );

      const handleMessageChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => {
          setMessage(e.target.value);
        },
        [],
      );

      const handleStartConversation = useCallback(
        async (e: React.FormEvent) => {
          e.preventDefault();
          if (peerAddress && message) {
            setIsLoading(true);
            const conversation = await startConversation(peerAddress, message);
            setIsLoading(false);
          }
        },
        [message, peerAddress, startConversation],
      );

      return (
        <form onSubmit={handleStartConversation}>
          <input
            name="addressInput"
            type="text"
            onChange={handleAddressChange}
            disabled={isLoading}
          />
          <input
            name="messageInput"
            type="text"
            onChange={handleMessageChange}
            disabled={isLoading || !isValidAddress(peerAddress)}
          />
        </form>
      );
    };
 
    
-
    Send messages
    The useSendMessage hook sends a new message into a conversation.
    
-
    Type
    
-
    import type { Conversation, SendOptions } from "@xmtp/react-sdk";

    const useSendMessage: <T = string>(
      conversation: Conversation,
      options?: SendOptions,
    ) => (message: T, optionsOverride?: SendOptions) => Promise<void>;
+
    Handle messages
    List messages in a conversation
    The useMessages hook fetches a list of all messages within a conversation on mount. It also exposes loading and error states and whether there are more messages based on the options passed.
    
+
    Types
    
+
    import type {
      ContentTypeMetadata,
      CachedConversation,
      DecodedMessage,
      SendOptions,
    } from "@xmtp/react-sdk";

    type CachedMessage<C = any, M = ContentTypeMetadata> = {
      content: C;
      contentBytes?: Uint8Array;
      contentFallback?: string;
      contentType: string;
      conversationTopic: string;
      hasSendError: boolean;
      id?: number;
      isSending: boolean;
      metadata?: M;
      senderAddress: string;
      sendOptions?: SendOptions;
      sentAt: Date;
      status: "unprocessed" | "processed";
      uuid: string;
      walletAddress: string;
      xmtpID: string;
    };

    type UseMessagesOptions = OnError & {
      /**
       * Callback function to execute when new messages are fetched
       */
      onMessages?: (messages: DecodedMessage[]) => void;
    };

    const useMessages: (
      conversation: CachedConversation,
      options?: UseMessagesOptions,
    ) => {
      error: Error | null;
      isLoading: boolean;
      messages: CachedMessage<any, ContentTypeMetadata>[];
    };
 
    
 
    Example
    
-
    import { useSendMessage } from "@xmtp/react-sdk";
    import type { Conversation } from "@xmtp/react-sdk";
    import { useCallback, useState } from "react";

    export const SendMessage: React.FC<{ conversation: Conversation }> = ({
      conversation,
    }) => {
      const [peerAddress, setPeerAddress] = useState("");
      const [message, setMessage] = useState("");
      const [isSending, setIsSending] = useState(false);
      const sendMessage = useSendMessage(conversation);

      const handleAddressChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => {
          setPeerAddress(e.target.value);
        },
        [],
      );

      const handleMessageChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => {
          setMessage(e.target.value);
        },
        [],
      );

      const handleSendMessage = useCallback(
        async (e: React.FormEvent) => {
          e.preventDefault();
          if (peerAddress && isValidAddress(peerAddress) && message) {
            setIsLoading(true);
            await sendMessage(message);
            setIsLoading(false);
          }
        },
        [message, peerAddress, sendMessage],
      );

      return (
        <form onSubmit={handleSendMessage}>
          <input
            name="addressInput"
            type="text"
            onChange={handleAddressChange}
            disabled={isSending}
          />
          <input
            name="messageInput"
            type="text"
            onChange={handleMessageChange}
            disabled={isSending}
          />
        </form>
      );
    };
+
    import { useMessages } from "@xmtp/react-sdk";
    import type { CachedConversation } from "@xmtp/react-sdk";

    export const Messages: React.FC<{
      conversation: CachedConversation;
    }> = ({ conversation }) => {
      const { error, messages, isLoading } = useMessages(conversation);

      if (error) {
        return "An error occurred while loading messages";
      }

      if (isLoading) {
        return "Loading messages...";
      }

      return (
        ...
      );
    };
 
    
-
    To learn more, see Send messages in the xmtp-js SDK docs.
    
-
    List messages in a conversation
    The useMessages hook fetches a list of all messages within a conversation on mount. It also exposes loading and error states and whether there are more messages based on the options passed.
    
+
    Send messages
    The useSendMessage hook sends a new message into a conversation.
    
 
    Type
    
-
    import type {
      Conversation,
      DecodedMessage,
      ListMessagesOptions,
    } from "@xmtp/react-sdk";

    export type UseMessagesOptions = ListMessagesOptions & {
      /**
       * Callback function to execute when new messages are fetched
       */
      onMessages?: (
        messages: DecodedMessage[],
        options: ListMessagesOptions,
      ) => void;
    };

    const useMessages: (
      conversation?: Conversation,
      options?: UseMessagesOptions,
    ) => {
      error: unknown;
      hasMore: boolean;
      isLoading: boolean;
      messages: DecodedMessage[];
      next: () => Promise<DecodedMessage[]>;
    };
+
    import type { DecodedMessage, CachedConversation, SendOptions } from "@xmtp/react-sdk";

    const useSendMessage: (options?: UseSendMessageOptions) => {
        error: unknown;
        isLoading: boolean;
        sendMessage: <T = string>(conversation: CachedConversation, content: T, contentType?: ContentTypeId, sendOptions?: Omit<SendOptions, "contentType">) => Promise<DecodedMessage>;
    }
 
    
 
    Example
    
-
    import { useMessages } from "@xmtp/react-sdk";
    import type { Conversation, DecodedMessage } from "@xmtp/react-sdk";

    export const Messages: React.FC<{
      conversation: Conversation;
    }> = ({ conversation }) => {
      const { error, messages, isLoading } = useMessages(conversation);

      if (error) {
        return "An error occurred while loading messages";
      }

      if (isLoading) {
        return "Loading messages...";
      }

      return (
        ...
      );
    };
+
    import { useSendMessage } from "@xmtp/react-sdk";
    import type { Conversation } from "@xmtp/react-sdk";
    import { useCallback, useState } from "react";

    export const SendMessage: React.FC<{ conversation: CachedConversation }> = ({
      conversation,
    }) => {
      const [peerAddress, setPeerAddress] = useState("");
      const [message, setMessage] = useState("");
      const [isSending, setIsSending] = useState(false);
      const sendMessage = useSendMessage();

      const handleAddressChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => {
          setPeerAddress(e.target.value);
        },
        [],
      );

      const handleMessageChange = useCallback(
        (e: ChangeEvent<HTMLInputElement>) => {
          setMessage(e.target.value);
        },
        [],
      );

      const handleSendMessage = useCallback(
        async (e: React.FormEvent) => {
          e.preventDefault();
          if (peerAddress && isValidAddress(peerAddress) && message) {
            setIsLoading(true);
            await sendMessage(conversation, message);
            setIsLoading(false);
          }
        },
        [message, peerAddress, sendMessage],
      );

      return (
        <form onSubmit={handleSendMessage}>
          <input
            name="addressInput"
            type="text"
            onChange={handleAddressChange}
            disabled={isSending}
          />
          <input
            name="messageInput"
            type="text"
            onChange={handleMessageChange}
            disabled={isSending}
          />
        </form>
      );
    };
 
    
-
    Page through messages
    If a conversation has a lot of messages, it's more performant to page through them rather than fetching them all at once. This can be accomplished by using the limit option to limit the number of messages to fetch at a time.
    
-
    Example
    
-
    import { useMessages } from "@xmtp/react-sdk";
    import type { Conversation, DecodedMessage } from "@xmtp/react-sdk";

    export const PagedMessages: React.FC<{
      conversation: Conversation;
    }> = ({ conversation }) => {
      const { error, isLoading, messages, next } = useMessages(
        conversation,
        options: {
          limit: 20,
        },
      );

      const handleClick = useCallback(() => {
        // fetch next page of messages
        next();
      }, [next]);

      if (error) {
        return "An error occurred while loading messages";
      }

      if (isLoading) {
        return "Loading messages...";
      }

      return (
        <>
          ...
          <button type="button" onClick={handleClick}>
            Load more messages
          </button>
        </>
      );
    };
+
    Optimistic sending
    When a user sends a message with XMTP, they might experience a slight delay between sending the message and seeing their sent message display in their app UI.
    
+
    This is because when a user sends a message, they typically have to wait for the XMTP network to finish processing the message before the app can display it in the UI.
    
+
    The local-first architecture of the React SDK automatically includes optimistic sending to immediately display the sent message in the sender’s UI while processing the message in the background. This provides the user with immediate feedback and enables them to continue messaging without having to wait for their previous message to finish processing.
    
+
    Messages that are in the sending state will have a true value for their isSending property.
    
+
    Handle messages that fail to send
    If a message fails to complete the sending process, you must provide an error state that alerts the user and enables them to either resend the message or cancel sending the message.
    
+
    While in this unsent state, the message remains in its original location in the user’s conversation flow, with any newer sent and received messages displaying after it.
    
+
    If the user chooses to resend the message, the message moves into the most recently sent message position in the conversation. Once it successfully sends, it remains in that position.
    
+
    If the user chooses to cancel sending the message, the message is removed from the conversation flow.
    
+
    Messages that fail to send will have the hasSendError property set to true.
    
+
    Resend a failed message
    Use the resendMessage function from the useResendMessage hook to resend a failed message.
    
+
    const { resendMessage } = useResendMessage();

    // resend the message
    resendMessage(failedMessage);
+
    
+
    Compression
    Message content can be optionally compressed using the compression option. The value of the option is the name of the compression algorithm to use. Currently supported are gzip and deflate. Compression is applied to the bytes produced by the content codec.
    
+
    Content will be decompressed transparently on the receiving end. Note that Client enforces maximum content size. The default limit can be overridden through the ClientOptions. Consequently, a message that would expand beyond that limit on the receiving end will fail to decode.
    
+
    import { Compression, ContentTypeText } from "@xmtp/react-sdk";

    const sendMessage = useSendMessage();

    await sendMessage(conversation, "#".repeat(1000), ContentTypeText, {
      compression: Compression.COMPRESSION_DEFLATE,
    });
 
    
-
    Listen for new messages in a conversation
    The useStreamMessages hook streams new conversation messages on mount and exposes an error state.
    
+
    Listen for new messages in a conversation
    The useStreamMessages hook streams new conversation messages on mount and exposes an error state.
    
 
    Type
    
-
    import type { Conversation, DecodedMessage } from "@xmtp/react-sdk";

    const useStreamMessages: (
      conversation: Conversation,
      onMessage: (message: DecodedMessage) => void,
    ) => {
      error: unknown;
    };
+
    import type { CachedConversation } from "@xmtp/react-sdk";

    const useStreamMessages: (
      conversation: CachedConversation,
      options?: UseStreamMessagesOptions,
    ) => {
      error: unknown;
    };
 
    
 
    Example
    
-
    import { useStreamMessages } from "@xmtp/react-sdk";
    import type { Conversation, DecodedMessage } from "@xmtp/react-sdk";
    import { useCallback, useEffect, useState } from "react";

    export const StreamMessages: React.FC<{
      conversation: Conversation;
    }> = ({
      conversation,
    }) => {
      // track streamed messages
      const [streamedMessages, setStreamedMessages] = useState<DecodedMessage[]>(
        [],
      );

      // callback to handle incoming messages
      const onMessage = useCallback(
        (message: DecodedMessage) => {
          setStreamedMessages((prev) => [...prev, message]);
        },
        [streamedMessages],
      );

      useStreamMessages(conversation, onMessage);

      useEffect(() => {
        setStreamedMessages([]);
      }, [conversation]);

      return (
        ...
      );
    };
+
    import { useStreamMessages } from "@xmtp/react-sdk";
    import type { CachedConversation, DecodedMessage } from "@xmtp/react-sdk";
    import { useCallback, useEffect, useState } from "react";

    export const StreamMessages: React.FC<{
      conversation: CachedConversation;
    }> = ({
      conversation,
    }) => {
      // track streamed messages
      const [streamedMessages, setStreamedMessages] = useState<DecodedMessage[]>(
        [],
      );

      // callback to handle incoming messages
      const onMessage = useCallback(
        (message: DecodedMessage) => {
          setStreamedMessages((prev) => [...prev, message]);
        },
        [streamedMessages],
      );

      useStreamMessages(conversation, onMessage);

      useEffect(() => {
        setStreamedMessages([]);
      }, [conversation]);

      return (
        ...
      );
    };
 
    
-
    To learn more, see Listen for new messages in a conversation in the xmtp-js SDK docs.
    
-
    Listen for new messages in all conversations
    The useStreamAllMessages hook streams new messages from all conversations on mount and exposes an error state.
    
+
    Listen for new messages in all conversations
    The useStreamAllMessages hook streams new messages from all conversations on mount and exposes an error state.
    
 
    Type
    
-
    import type { DecodedMessage } from "@xmtp/react-sdk";

    const useStreamAllMessages: (onMessage: (message: DecodedMessage) => void) => {
      error: unknown;
    };
+
    import type { DecodedMessage } from "@xmtp/react-sdk";

    const useStreamAllMessages: (
      onMessage: (message: DecodedMessage) => void | Promise<void>,
      onError?: OnError["onError"],
    ) => {
      error: unknown;
    };
 
    
 
    Example
    
 
    import { useStreamAllMessages } from "@xmtp/react-sdk";
    import type { DecodedMessage } from "@xmtp/react-sdk";
    import { useCallback, useState } from "react";

    export const StreamAllMessages: React.FC = () => {
      // track streamed messages
      const [streamedMessages, setStreamedMessages] = useState<DecodedMessage[]>(
        [],
      );

      // callback to handle incoming messages
      const onMessage = useCallback(
        (message: DecodedMessage) => {
          setStreamedMessages((prev) => [...prev, message]);
        },
        [streamedMessages],
      );

      useStreamAllMessages(onMessage);

      return (
        ...
      );
    };
 
    
-
    To learn more, see Listen for new messages in all conversations in the xmtp-js SDK docs.
    
-
    Check if an address is on the network
    The useCanMessage hook exposes both the client and static instances of the canMessage method. To check if a blockchain address is registered on the network before instantiating a client instance, use the canMessageStatic export.
    
-
    Type
    
-
    type NetworkOptions = {
      env: "local" | "dev" | "production";
      apiUrl: string | undefined;
      appVersion?: string;
    };

    const useCanMessage: () => {
      canMessage: {
        (peerAddress: string): Promise<boolean>;
        (peerAddress: string[]): Promise<boolean[]>;
      };
      canMessageStatic: {
        (peerAddress: string, opts?: Partial<NetworkOptions>): Promise<boolean>;
        (peerAddress: string[], opts?: Partial<NetworkOptions>): Promise<boolean[]>;
      };
    };
+
    Handle content types
    As the ecosystem of apps built with XMTP grows exponentially, so will the number of available content types.
    
+
    All apps built with an XMTP client SDK automatically support the plain text standard content type. However, there are other content types that you can choose to support.
    
+
    These include standards-track content types and custom content types.
    
+
    To learn more about content types, see Content types with XMTP.
    
+
    Standards-track content types
    Standards-track content types are proposals being actively reviewed for adoption as standard content types through the XMTP Improvement Proposal (XIP) process. Once a content type has been adopted as a standard, it is included in the XMTP client SDKs. Apps can use an SDK to automatically handle the new standard content types.
    
+
    Here are some examples of standards-track content types that you can review, test, and adopt in your app today:
    
+
    Remote attachments
    This content type supports sending file attachments that are stored off-network. Use it to enable your app to send and receive message attachments.
    
+
+
    Replies
    This content type supports direct replies to messages.
    
+
+
    Reactions
    This content type supports reactions to messages.
    
+
+
    Read receipts
    This content type supports read receipts to messages
    
+
+
    Integrate standards-track content types with the React SDK
    The React SDK supports all current standards-track content types, but only text messages are enabled out of the box. Adding support for other standards-track content types requires a bit of configuration.
    
+
    import {
      XMTPProvider,
      attachmentContentTypeConfig,
      reactionContentTypeConfig,
      readReceiptContentTypeConfig,
      replyContentTypeConfig,
    } from "@xmtp/react-sdk";

    const contentTypeConfigs = [
      attachmentContentTypeConfig,
      reactionContentTypeConfig,
      readReceiptContentTypeConfig,
      replyContentTypeConfig,
    ];

    createRoot(document.getElementById("root") as HTMLElement).render(
      <StrictMode>
        <XMTPProvider contentTypeConfigs={contentTypeConfigs}>
          <App />
        </XMTPProvider>
      </StrictMode>,
    );
+
    
+
    Custom content types
    On the other hand, custom content types are those that an app chooses to use in its implementation, but which are not standards and are not being actively reviewed as standards-track content types.
    
+
    When your app encounters a custom content type, you can:
    
+
      
+
    • Choose to adopt the custom content type if you think it is a good fit for your app.
      • 
+
    • Update your app to gracefully handle the unsupported content type.
      • 
+
    • Ignore it
      • 
+
    
+
    Integrate custom content types with the React SDK
    
+
    Note
    This part of the React SDK is still under active development and may change in the future.
    
+
    
+
    To support a custom content type, you must create a content type configuration to integrate with the local-first architecture. There are five possible options in a content type configuration, and two are required. They are outlined below.
    
+
    Namespace (required)
    
+
    This must be specified and unique to all other content type namespaces.
    
+
    Message processors (required)
    
+
    Processing a message as it arrives from the XMTP network is a key aspect of the local-first architecture. It determines if and how a message is cached locally.
    
+
    Codecs (required)
    
+
    All custom content types require at least one codec.
    
+
    Schema (optional)
    
+
    When working with some content types, you may want to cache data in a separate table. This option allows you to specify a new Dexie table schema.
    
+
    Validators (optional)
    
+
    Content validators help to ensure that custom content type messages are in the correct format and can be processed properly.
    
+
    Example configuration
    
+
    import type { ContentCodec } from "@xmtp/xmtp-js";

    const MyContentType = new ContentTypeId({
      authorityId: "mydomain.com",
      typeId: "myContentType",
      versionMajor: 1,
      versionMinor: 0,
    });

    class MyContentTypeCodec implements ContentCodec { ... };

    export const myCustomContentTypeConfiguration = {
      namespace: "MyContentType",
      codecs: [new MyContentTypeCodec()],
      processors: {
        [MyContentType.toString()]: [processMyContentType],
      },
      validators: {
        [MyContentType.toString()]: validateMyContentType,
      },
    };
+
    
+
    Send custom content type messages
    The useSendMessage hook supports custom content types. Pass in the content type as the third parameter as shown in the example below.
    
+
    import { useCallback, useState } from "react";
    import { useSendMessage } from "@xmtp/react-sdk";
    import type { Conversation } from "@xmtp/react-sdk";
    import type { Reaction } from "@xmtp/content-type-reaction";
    import { ContentTypeReaction } from "@xmtp/content-type-reaction";

    export const SendCustomContentTypeMessage: React.FC<{
      conversation: CachedConversation;
    }> = ({ conversation }) => {
      const [isSending, setIsSending] = useState(false);
      const sendMessage = useSendMessage();

      const handleSendMessage = useCallback(
        async (e: React.FormEvent) => {
          e.preventDefault();
          setIsLoading(true);
          // send custom content type
          await sendMessage(
            conversation,
            {
              action: "added",
              content: "👍",
              reference: "<XMTP message ID>",
              schema: "unicode",
            } as Reaction,
            ContentTypeReaction,
          );
          setIsLoading(false);
        },
        [message, peerAddress, sendMessage],
      );

      return (
        <form onSubmit={handleSendMessage}>
          <button type="submit" disabled={isSending}>
            Send custom content type message
          </button>
        </form>
      );
    };
 
    
+
    Handle unsupported content types
    Messages that contain unsupported content types are stored in the local cache, but are not processed. The content property of an unsupported message will be undefined. Each time a client is initialized, any messages that were previously unprocessed because their content type was unsupported at the time, will attempt to be reprocessed.
    
+
    If you wish to display an unsupported content type, there’s a contentFallback property that may include a useful string. However, it is recommended that you manually process unsupported content types.
    
 
    Example
    
-
    import { useCanMessage } from "@xmtp/react-sdk";

    export const CanMessage: React.FC = () => {
      const [peerAddress, setPeerAddress] = useState("");
      const [isOnNetwork, setIsOnNetwork] = useState(false);
      const [isLoading, setIsLoading] = useState(false);

      const { canMessage } = useCanMessage();

      const handleAddressChange = useCallback((e: React.KeyboardEvent<HTMLInputElement>) => {
        setPeerAddress(e.target.value);
      }, []);

      const handleCheckAddress = useCallback(async (e: FormEvent) => {
          e.preventDefault();
          if (isValidAddress(peerAddress)) {
            setIsLoading(true);
            setIsOnNetwork(await canMessage(peerAddress));
            setIsLoading(false);
          } else {
            setIsOnNetwork(false);
          }
        };
        void checkAddress();
      }, [peerAddress]);

      return (
        <form onSubmit={handleCheckAddress}>
          <input
            name="addressInput"
            type="text"
            onChange={handleAddressChange}
            disabled={isLoading}
          />
        </form>
      );
    };
+
    import { ContentTypeId } from "@xmtp/xmtp-js";
    import { ContentTypeAttachment } from "@xmtp/content-type-remote-attachment";

    const MessageContent = ({ message }) => {
      if (
        message.content === undefined &&
        ContentTypeId.fromString(message.contentType).sameAs(ContentTypeAttachment)
      ) {
        return "This message contains an attachment, which is not supported by this client.";
      }
    };
 
    
-
    Developing
    Run yarn dev to build the SDK and watch for changes, which will trigger a rebuild.
    
+
    Developing
    Run yarn dev to build the SDK and watch for changes, which will trigger a rebuild.
    
 
    Useful commands
      
 
    • yarn build: Builds the SDK
      • 
-
    • yarn clean: Removes node_modules, lib, and .turbo folders
      • 
+
    • yarn clean: Removes node_modules, lib, and .turbo folders
      • 
 
    • yarn dev: Builds the SDK and watches for changes, which will trigger a rebuild
      • 
 
    • yarn format: Runs prettier format and write changes
      • 
 
    • yarn format:check: Runs prettier format check
      • 
 
    • yarn lint: Runs ESLint
      • 
 
    • yarn test: Runs all unit tests
      • 
-
    • yarn typecheck: Runs tsc
      • 
+
    • yarn typecheck: Runs tsc
      • 
 
    
-
    🏗 Breaking revisions
    Because this SDK is in active development, you should expect breaking revisions that might require you to adopt the latest SDK release to enable your app to continue working as expected.
    
-
    XMTP communicates about breaking revisions in the XMTP Discord community, providing as much advance notice as possible. Additionally, breaking revisions in a release are described on the Releases page.
    
+
    Breaking revisions
    Because this SDK is in active development, you should expect breaking revisions that might require you to adopt the latest SDK release to enable your app to continue working as expected.
    
+
    XMTP communicates about breaking revisions in the XMTP Discord community, providing as much advance notice as possible. Additionally, breaking revisions in a release are described on the Releases page.
    
 
    Deprecation
    Older versions of the SDK will eventually be deprecated, which means:
    
 
      
 
    1. The network will not support and eventually actively reject connections from clients using deprecated versions.
      2. 
@@ -152,23 +294,19 @@ 
      @xmtp/react-sdk
    -

    Bug reports, feature requests, and PRs are welcome in accordance with these contribution guidelines.

    -

    XMTP production and dev network environments

    XMTP provides both production and dev network environments to support the development phases of your project.

    -

    The production and dev networks are completely separate and not interchangeable. -For example, for a given blockchain account, its XMTP identity on dev network is completely distinct from its XMTP identity on the production network, as are the messages associated with these identities. In addition, XMTP identities and messages created on the dev network can't be accessed from or moved to the production network, and vice versa.

    +

    Bug reports, feature requests, and PRs are welcome in accordance with these contribution guidelines.

    +

    XMTP production and dev network environments

    XMTP provides both production and dev network environments to support the development phases of your project.

    +

    The production and dev networks are completely separate and not interchangeable. For example, for a given blockchain account, its XMTP identity on the dev network is completely distinct from its XMTP identity on the production network, as are the messages associated with these identities. In addition, XMTP identities and messages created on the dev network can't be accessed from or moved to the production network, and vice versa.

    -

    Important:
    When you create a client, it connects to the XMTP dev environment by default. To learn how to use the env parameter to set your client's network environment, see Configure the client.

    +

    Important
    When you create a client, it connects to the XMTP dev environment by default. To learn how to use the env parameter to set your client's network environment, see Configure the client.

    -

    The env parameter accepts one of three valid values: dev, production, or local. Here are some best practices for when to use each environment:

    +

    The env parameter accepts one of three valid values: dev, production, or local. Here are some best practices for when to use each environment:

      -

    • dev: Use to have a client communicate with the dev network. As a best practice, set env to dev while developing and testing your app. Follow this best practice to isolate test messages to dev inboxes.

      -
      • -

    • production: Use to have a client communicate with the production network. As a best practice, set env to production when your app is serving real users. Follow this best practice to isolate messages between real-world users to production inboxes.

      -
      • -

    • local: Use to have a client communicate with an XMTP node you are running locally. For example, an XMTP node developer can set env to local to generate client traffic to test a node running locally.

      -
      • +
    • dev: Use to have a client communicate with the dev network. As a best practice, set env to dev while developing and testing your app. Follow this best practice to isolate test messages to dev inboxes.
      • +
    • production: Use to have a client communicate with the production network. As a best practice, set env to production when your app is serving real users. Follow this best practice to isolate messages between real-world users to production inboxes.
      • +
    • local: Use to have a client communicate with an XMTP node you are running locally. For example, an XMTP node developer can set env to local to generate client traffic to test a node running locally.
    -

    The production network is configured to store messages indefinitely. XMTP may occasionally delete messages and keys from the dev network, and will provide advance notice in the XMTP Discord community.

    +

    The production network is configured to store messages indefinitely. XMTP may occasionally delete messages and keys from the dev network, and will provide advance notice in the XMTP Discord community.

    @@ -202,31 +340,57 @@

    Create React App
  • Vite
  • Buffer polyfill
    • +
  • Reference docs
    • +
  • Local-first architecture
  • Usage
    • +
  • Create a client with private keys
    • +
  • +
    • +
  • Handle conversations
  • List existing conversations
  • Listen for new conversations
    • -
  • Start a new conversation
    • -
  • Send messages
    • +
  • Start a new conversation
    • +
  • Handle messages
    • +
  • +
    • +
  • Compression
  • Listen for new messages in a conversation
    • -
  • Listen for new messages in all conversations
    • -
  • Check if an address is on the network
    • +
  • Listen for new messages in all conversations
    • +
  • Handle content types
    • +
  • +
  • Developing
  • Useful commands
    • -
  • 🏗 Breaking revisions
    • +
  • Breaking revisions
  • Deprecation
    • -
  • XMTP production and dev network environments

    • +
  • XMTP production and dev network environments
    • CachedAttachmentsMetadata: Attachment | undefined
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/attachment.ts:21
    • diff --git a/types/CachedConversation.html b/types/CachedConversation.html index d331fe25..98e03bf1 100644 --- a/types/CachedConversation.html +++ b/types/CachedConversation.html @@ -43,7 +43,7 @@
    updatedAt
    walletAddress: string
    +
  • Defined in packages/react-sdk/src/helpers/caching/conversations.ts:6
    • diff --git a/types/CachedConversationWithId.html b/types/CachedConversationWithId.html index 5221bcd5..e4e32816 100644 --- a/types/CachedConversationWithId.html +++ b/types/CachedConversationWithId.html @@ -22,7 +22,7 @@

    Type declaration

  • id: number
    • +
  • Defined in packages/react-sdk/src/helpers/caching/conversations.ts:32
    • diff --git a/types/CachedConversationsTable.html b/types/CachedConversationsTable.html index 9964bbfd..30ff241b 100644 --- a/types/CachedConversationsTable.html +++ b/types/CachedConversationsTable.html @@ -17,7 +17,7 @@

    Type alias CachedConversationsTable

    CachedConversationsTable: Table<CachedConversation, number>
    +
  • Defined in packages/react-sdk/src/helpers/caching/conversations.ts:30
    • diff --git a/types/CachedMessage.html b/types/CachedMessage.html index d8d0d47e..2ed66465 100644 --- a/types/CachedMessage.html +++ b/types/CachedMessage.html @@ -59,7 +59,7 @@
    walletAddress
    xmtpID: string
    +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:21
    • diff --git a/types/CachedMessageWithId.html b/types/CachedMessageWithId.html index 759a20de..e057a55d 100644 --- a/types/CachedMessageWithId.html +++ b/types/CachedMessageWithId.html @@ -27,7 +27,7 @@

    Type declaration

  • id: number
    • +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:42
    • diff --git a/types/CachedMessagesTable.html b/types/CachedMessagesTable.html index b1a7b073..2bde6406 100644 --- a/types/CachedMessagesTable.html +++ b/types/CachedMessagesTable.html @@ -17,7 +17,7 @@

    Type alias CachedMessagesTable

    CachedMessagesTable: Table<CachedMessage, number>
    +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:40
    • diff --git a/types/CachedReaction.html b/types/CachedReaction.html index d0e75c56..6bd02d9c 100644 --- a/types/CachedReaction.html +++ b/types/CachedReaction.html @@ -32,7 +32,7 @@
    senderAddress
    xmtpID: string
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reaction.ts:18
    • diff --git a/types/CachedReactionsMetadata.html b/types/CachedReactionsMetadata.html index 8b049253..99c88121 100644 --- a/types/CachedReactionsMetadata.html +++ b/types/CachedReactionsMetadata.html @@ -17,7 +17,7 @@

    Type alias CachedReactionsMetadata

    CachedReactionsMetadata: boolean
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reaction.ts:38
    • diff --git a/types/CachedReactionsTable.html b/types/CachedReactionsTable.html index eb15e242..ab04f624 100644 --- a/types/CachedReactionsTable.html +++ b/types/CachedReactionsTable.html @@ -17,7 +17,7 @@

    Type alias CachedReactionsTable

    CachedReactionsTable: Table<CachedReaction, number>
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reaction.ts:40
    • diff --git a/types/CachedReadReceiptMetadata.html b/types/CachedReadReceiptMetadata.html index a9a9a1da..edabd431 100644 --- a/types/CachedReadReceiptMetadata.html +++ b/types/CachedReadReceiptMetadata.html @@ -17,7 +17,7 @@

    Type alias CachedReadReceiptMetadata

    CachedReadReceiptMetadata: string | undefined
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/readReceipt.ts:17
    • diff --git a/types/CachedRepliesMetadata.html b/types/CachedRepliesMetadata.html index 7543bc2a..ea14c9dc 100644 --- a/types/CachedRepliesMetadata.html +++ b/types/CachedRepliesMetadata.html @@ -17,7 +17,7 @@

    Type alias CachedRepliesMetadata

    CachedRepliesMetadata: string[]
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reply.ts:15
    • diff --git a/types/ProcessUnprocessedMessagesOptions.html b/types/ProcessUnprocessedMessagesOptions.html index 6e53e084..f151e070 100644 --- a/types/ProcessUnprocessedMessagesOptions.html +++ b/types/ProcessUnprocessedMessagesOptions.html @@ -26,7 +26,7 @@
    Optional
    +
  • Defined in packages/react-sdk/src/helpers/caching/messages.ts:451
    • diff --git a/variables/attachmentContentTypeConfig.html b/variables/attachmentContentTypeConfig.html index 8f163da6..41e33653 100644 --- a/variables/attachmentContentTypeConfig.html +++ b/variables/attachmentContentTypeConfig.html @@ -17,7 +17,7 @@

    Variable attachmentContentTypeConfigConst

    attachmentContentTypeConfig: ContentTypeConfiguration = ...
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/attachment.ts:131
    • diff --git a/variables/reactionContentTypeConfig.html b/variables/reactionContentTypeConfig.html index 0c9cc232..38fdad00 100644 --- a/variables/reactionContentTypeConfig.html +++ b/variables/reactionContentTypeConfig.html @@ -17,7 +17,7 @@

    Variable reactionContentTypeConfigConst

    reactionContentTypeConfig: ContentTypeConfiguration = ...
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reaction.ts:199
    • diff --git a/variables/readReceiptContentTypeConfig.html b/variables/readReceiptContentTypeConfig.html index a226a470..4737f628 100644 --- a/variables/readReceiptContentTypeConfig.html +++ b/variables/readReceiptContentTypeConfig.html @@ -17,7 +17,7 @@

    Variable readReceiptContentTypeConfigConst

    readReceiptContentTypeConfig: ContentTypeConfiguration = ...
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/readReceipt.ts:81
    • diff --git a/variables/replyContentTypeConfig.html b/variables/replyContentTypeConfig.html index 38319fa4..c8a175c1 100644 --- a/variables/replyContentTypeConfig.html +++ b/variables/replyContentTypeConfig.html @@ -17,7 +17,7 @@

    Variable replyContentTypeConfigConst

    replyContentTypeConfig: ContentTypeConfiguration = ...
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/reply.ts:134
    • diff --git a/variables/textContentTypeConfig.html b/variables/textContentTypeConfig.html index e5b4b4a2..2502227c 100644 --- a/variables/textContentTypeConfig.html +++ b/variables/textContentTypeConfig.html @@ -17,7 +17,7 @@

    Variable textContentTypeConfigConst

    textContentTypeConfig: ContentTypeConfiguration = ...
    +
  • Defined in packages/react-sdk/src/helpers/caching/contentTypes/text.ts:36