diff --git a/docs/components/CustomHomePage.tsx b/docs/components/CustomHomePage.tsx new file mode 100644 index 0000000..0e02561 --- /dev/null +++ b/docs/components/CustomHomePage.tsx @@ -0,0 +1,77 @@ +import React from 'react' + +const Root: React.FC<{ children: React.ReactNode }> = ({ children }) => ( +
{children}
+); + +const Headline: React.FC<{ children: React.ReactNode }> = ({ children }) => { + return ( +

+ {React.Children.map(children, child => { + if (React.isValidElement(child) && child.type === 'p') { + return React.cloneElement(child, { + className: `custom-homepage-headline-text ${child.props.className || ''}`.trim() + }); + } + return {child}; + })} +

+ ); +}; + +const Subhead: React.FC<{ children: React.ReactNode }> = ({ children }) => { + return ( +
+ {React.Children.map(children, child => { + if (React.isValidElement(child) && child.type === 'p') { + return React.cloneElement(child, { + className: `custom-homepage-subhead-text ${child.props.className || ''}`.trim() + }); + } + return {child}; + })} +
+ ); +}; + +const TileGrid: React.FC<{ children: React.ReactNode }> = ({ children }) => ( +
{children}
+); + +interface TileProps { + href: string; + title: string; + description: string; + icon?: string; + isExternal?: boolean; + } + + const ExternalLinkIcon = () => ( + + + + + + ); + + const Tile: React.FC = ({ href, title, description, icon, isExternal }) => ( + + {icon && {icon}} +

{title}

+

{description}

+ {isExternal && } + + ); + +export const CustomHomePage = { + Root, + Headline, + Subhead, + TileGrid, + Tile, +}; \ No newline at end of file diff --git a/docs/pages/chat-widget/chat-widget.md b/docs/pages/chat-widget/chat-widget.md new file mode 100644 index 0000000..79b84c3 --- /dev/null +++ b/docs/pages/chat-widget/chat-widget.md @@ -0,0 +1,19 @@ +--- +description: "Embed a floating inbox chat widget built with XMTP on your website" +--- + +# Embed a floating inbox chat widget built with XMTP + +You can embed a "floating inbox" chat widget built with XMTP on your website. + +You can use one of these floating inbox quickstart example apps to get started: + +- [For JavaScript](https://github.com/xmtp/xmtp-quickstart-reactjs) + +- [With React hooks](https://github.com/xmtp/xmtp-quickstart-hooks) + +- [With Next.js hooks](https://github.com/xmtp/xmtp-quickstart-hooks-next) + +For example, here's a screenshot of the floating inbox chat widget built with the JavaScript quickstart app. You can also try out the [JavaScript quickstart app](https://xmtp-quickstart-reactjs.vercel.app/). + +![Screenshot of the floating inbox chat widget](https://raw.githubusercontent.com/xmtp/docs-xmtp-org/main/docs/pages/img/floating-inbox.png) diff --git a/docs/pages/dms/client.mdx b/docs/pages/client/create-client.mdx similarity index 66% rename from docs/pages/dms/client.mdx rename to docs/pages/client/create-client.mdx index 0969270..0931697 100644 --- a/docs/pages/dms/client.mdx +++ b/docs/pages/client/create-client.mdx @@ -4,31 +4,50 @@ description: Learn how to create and configure an XMTP client # Create and configure an XMTP client -The XMTP message API revolves around a network client that allows retrieving and sending messages to other network participants. A client must be connected to a wallet on startup. The client will request a wallet signature in two cases: - -1. To sign the newly generated key bundle. This happens only the very first time when key bundle is not found in storage. -2. To sign a random salt used to encrypt the key bundle in storage. This happens every time the client is started (including the very first time). +The XMTP message API revolves around a network client that allows retrieving and sending messages to other network participants. ## Create a client -A client is created that requires passing in a connected wallet that implements the Signer interface. +To create an XMTP client, it must be connected to a wallet on startup. You must pass in a connected wallet that implements the Signer interface. This wallet is required for authentication and encryption purposes. + +For more information about wallet signature requests, see [Account signatures](/protocol/signatures). + +Clients created by XMTP v3 SDKs can also support XMTP v2 messages if the wallet is an EOA. At a high-level, XMTP v3 is used to support group chat and XMTP v2 is used to support 1:1 chat. + +In the near future, XMTP v3 will support both group and 1:1 chat with Messaging Layer Security (MLS). Have questions or feedback? Post to the [XMTP Community Forums](https://community.xmtp.org/c/development/58). + +Group chat is currently supported in Kotlin, Swift, React Native, and Node.js. + +In the near future, XMTP v3 will also support group chat for the web. + +For more information about the work being done to support group chat for the web, see this [SQLite, WebAssembly, and Diesel](https://www.youtube.com/watch?v=qnCeXsqqKcY&t=240s) talk in the XMTP Developer Community Call. + +If your mobile app provides group chat, you must explicitly configure your client to enable this functionality by setting the `enableV3` client option to `true`. + +:::tip[Best practice for mobile apps] -[Use client configuration options](#configure-the-client) to change parameters of a client's network connection. +Regardless of whether your mobile app provides group chat, set the `enableV3` client option to `true` to benefit from other aspects of the upgraded XMTP v3 protocol. Enabling v3 doesn't stop your app's support for XMTP v2 functionality. + +::: + +For more information about client options, including how to set your client's network environment, see [client configuration options](#configure-the-client). :::code-group ```ts [JavaScript] import { Client } from "@xmtp/xmtp-js"; + // Create the client with a `Signer` from your application -const xmtp = await Client.create(signer, { env: "dev" }); +const xmtp = await Client.create(signer, { + env: "production", +}); ``` -
-To use the hooks provided by the React SDK, you must wrap your app with an `XMTPProvider`. This gives the hooks access to the XMTP client instance. - -```ts [TypeScript] +```ts [React] import { XMTPProvider } from "@xmtp/react-sdk"; +import { useClient } from "@xmtp/react-sdk"; +// Wrap your app with XMTPProvider createRoot(document.getElementById("root") as HTMLElement).render( @@ -36,63 +55,94 @@ createRoot(document.getElementById("root") as HTMLElement).render( ); -``` -```tsx [TypeScript] +// Inside your component export const CreateClient: React.FC<{ signer: Signer }> = ({ signer }) => { const { client, error, isLoading, initialize } = useClient(); const handleConnect = useCallback(async () => { const options = { persistConversations: false, - env: "dev", + env: "production", }; await initialize({ keys, options, signer }); }, [initialize]); - if (error) { - return "An error occurred while initializing the client"; - } - - if (isLoading) { - return "Awaiting signatures..."; - } - - if (!client) { - return ( - - ); - } - - return "Connected to XMTP"; + // ... rest of the component code }; ``` -
- ```kotlin [Kotlin] -// Create the client with a `SigningKey` from your app -val options = - ClientOptions( - api = ClientOptions.Api(env = XMTPEnvironment.PRODUCTION, isSecure = true) +val client = Client().create( + account = wallet, // wallet that implements SigningKey + options = ClientOptions( + api = ClientOptions.Api(XMTPEnvironment.PRODUCTION, isSecure = true), + enableV3 = true, // Enable group chat support + appContext = context, // Required if enableV3 is true + dbEncryptionKey = ByteArray(32), // Required 32-byte array for database encryption if enableV3 is true + dbDirectory = "mydbdir", // Optional. Specify a database directory. If no directory is specified, the value is set to xmtp_db by default. ) -val client = Client().create(account = account, options = options) +) ``` ```swift [Swift] import XMTP -// Create the client with a `SigningKey` from your app let client = try await Client.create( - account: account, options: .init(api: .init(env: .production))) + account: account, // account that implements SigningKey + options: .init( + api: .init(env: .production, isSecure: true), + enableV3: true, // Enable group chat support + dbEncryptionKey: key, // Required 32-byte array for database encryption if enableV3 is true + dbDirectory: "mydir", // Specify a database directory. If no directory is specified, the value is set to xmtp_db by default. + ) +) ``` ```tsx [React Native] import { Client } from "@xmtp/xmtp-react-native"; -// Create the client with a `Signer` from your application -const xmtp = await Client.create(signer); + +const xmtp = await Client.create(signer, { + env: "production", + enableV3: true, // Enable group chat support + dbEncryptionKey: new Uint8Array(32), // Required: 32-byte array for database encryption + dbDirectory: "mydbdir", // Specify a database directory. If no directory is specified, the value is set to xmtp_db by default. +}); +``` + +```tsx [Node] +import { createWalletClient, http, toBytes } from "viem"; +import { generatePrivateKey, privateKeyToAccount } from "viem/accounts"; +import { mainnet } from "viem/chains"; +import { Client } from "@xmtp/mls-client"; + +// Create a wallet for signing +const key = generatePrivateKey(); +const account = privateKeyToAccount(key); +const wallet = createWalletClient({ + account, + chain: mainnet, + transport: http(), +}); + +// Create client +const client = Client.create(account.address, { + env: "production", + enableV3: true, // Enable group chat support + dbPath: "path/to/local/db/file.db3", // Specify database path +}); + +// Sign the provided message +const signature = await wallet.signMessage({ + message: client.signatureText ?? "", +}); +const signatureBytes = toBytes(signature); + +// Add the signature to the client +client.addEcdsaSignature(signatureBytes); + +// Register client identity +await client.registerIdentity(); ``` ::: @@ -323,9 +373,9 @@ The keys returned by `exportKeyBundle` should be treated with the utmost care as ::: -## Create an XMTP client with a private key +## Create a client with a private key -You can create an XMTP client with a private key using a compatible client library. +You can create a client with a private key using a compatible client library. :::code-group @@ -438,7 +488,16 @@ Set the `env` client option to `dev` while developing. Set it to `production` be Parameter Default Description - + + + env + `dev` + + Connect 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](#xmtp-network-environments). + appVersion @@ -455,18 +514,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be app support, especially around communicating important SDK updates, including deprecations and required upgrades. - - - - env - `dev` - - Connect 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](#xmtp-network-environments). - - apiUrl @@ -475,20 +522,18 @@ Set the `env` client option to `dev` while developing. Set it to `production` be Manually specify an API URL to use. If specified, value of `env` will be ignored. - keystoreProviders `[StaticKeystoreProvider, NetworkKeystoreProvider, - KeyGeneratorKeystoreProvider]` + KeyGeneratorKeystore Provider]` 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. - persistConversations @@ -497,7 +542,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be Maintain a cache of previously seen V2 conversations in the storage provider (defaults to `LocalStorage`). - skipContactPublishing @@ -509,19 +553,16 @@ Set the `env` client option to `dev` while developing. Set it to `production` be 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. - maxContentSize `100M` Maximum message content size in bytes. - preCreateIdentityCallback @@ -532,7 +573,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be Identity](/protocol/signatures#sign-to-create-an-xmtp-identity) wallet signature is requested from the user. - preEnableIdentityCallback @@ -543,7 +583,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be Identity](/protocol/signatures#sign-to-enable-an-xmtp-identity) wallet signature is requested from the user. - useSnaps @@ -557,7 +596,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be to `false`. To learn more, see [Build with the Snap](/perf-ux/xmtp-metamask-snap#as-a-developer-who-wants-my-app-to-use-sign-in-with-xmtp-how-do-i-get-started). - basePersistence @@ -572,7 +610,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be and [Pluggable persistence](https://github.com/xmtp/xmtp-js/releases/tag/v11.0.0). - apiClientFactory @@ -585,7 +622,6 @@ Set the `env` client option to `dev` while developing. Set it to `production` be performance and reliability. To learn more, see [Pluggable gRPC API client](https://github.com/xmtp/xmtp-js/releases/tag/v11.0.0). - @@ -596,11 +632,20 @@ Set the `env` client option to `dev` while developing. Set it to `production` be Parameter Default Description - + + + env + `dev` + + Connect 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](#xmtp-network-environments). + appVersion - undefined + `undefined` Add a client app version identifier that's included with API requests.
@@ -612,53 +657,38 @@ Set the `env` client option to `dev` while developing. Set it to `production` be app support, especially around communicating important SDK updates, including deprecations and required upgrades. - - - - env - dev - - Connect 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](#xmtp-network-environments). - - apiUrl - undefined + `undefined` Manually specify an API URL to use. If specified, value of env will be ignored. - keystoreProviders - [StaticKeystoreProvider, NetworkKeystoreProvider, - KeyGeneratorKeystoreProvider] + `[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. - persistConversations - true + `true` Maintain a cache of previously seen V2 conversations in the storage provider (defaults to LocalStorage). - skipContactPublishing - false + `false` Do not publish the user's contact bundle to the network on client creation. Designed to be used in cases where the client session is @@ -666,50 +696,77 @@ Set the `env` client option to `dev` while developing. Set it to `production` be is known that a client instance has been instantiated with this flag set to false at some point in the past. - codecs - [TextCodec] + `[TextCodec]` Add codecs to support additional content types. - maxContentSize - 100M + `100M` Maximum message content size in bytes. - preCreateIdentityCallback - undefined + `undefined` preCreateIdentityCallback is a function that will be called immediately before a [Create Identity wallet signature](/protocol/signatures#sign-to-create-an-xmtp-identity) is requested from the user. - preEnableIdentityCallback - undefined + `undefined` preEnableIdentityCallback is a function that will be called immediately before an [Enable Identity wallet signature](/protocol/signatures#sign-to-enable-an-xmtp-identity) is requested from the user. -
- - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDefaultDescription
appVersion`undefined`Add a client app version identifier that's included with API requests. **Production apps are strongly encouraged to set this value.**
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.
env`DEV`Connect 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](#xmtp-network-environments).
ParameterDefaultDescription
env`DEV`Connect 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](#xmtp-network-environments).
enableV3`false`To support group chat (a feature of XMTP v3), set to `true`. As a best practice, regardless of whether your mobile app provides group chat, set `enableV3` to `true` to benefit from other aspects of the upgraded XMTP v3 protocol. Enabling v3 doesn't stop your app's support for XMTP v2 functionality.
appContextnullRequired if `enableV3` is set to `true`.
dbEncryptionKeynullRequired 32-byte array for database encryption if `enableV3` is `true`. For information about recommended key storage for Kotlin, [Android Keystore system](https://developer.android.com/privacy-and-security/keystore).
dbDirectoryxmtp_dbOptional. Specify a database directory. If no directory is specified, the value is set to `xmtp_db` by default.
appVersion`undefined`Add a client app version identifier that's included with API requests. Production apps are strongly encouraged to set this value.
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.
Configure `env` @@ -729,9 +786,36 @@ val client = Client().create(account = account, options = options)
- - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDefaultDescription
appVersion`undefined`Add a client app version identifier that's included with API requests. **Production apps are strongly encouraged to set this value.**
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.
env`dev`Connect 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](#xmtp-network-environments).
ParameterDefaultDescription
env`dev`Connect 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](#xmtp-network-environments).
enableV3`false`To support group chat (a feature of XMTP v3), set to `true`. As a best practice, regardless of whether your app provides group chat, set `enableV3` to `true` to benefit from other aspects of the upgraded XMTP v3 protocol. Enabling v3 doesn't stop your app's support for XMTP v2 functionality.
dbEncryptionKeynullRequired 32-byte array for database encryption if `enableV3` is `true`. For information about recommended key storage for Swift, see [Protecting keys with the Secure Enclave](https://developer.apple.com/documentation/security/protecting-keys-with-the-secure-enclave).
dbDirectoryxmtp_dbOptional. Specify a database directory. If no directory is specified, the value is set to `xmtp_db` by default.
appVersion`undefined`Add a client app version identifier that's included with API requests. Production apps are strongly encouraged to set this value.
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.
Configure `env` @@ -750,7 +834,31 @@ let client = try await Client.create(account: account, options: clientOptions) Parameter Default Description - + + + env + `dev` + + Connect 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](#xmtp-network-environments). + + + + enableV3 + `false` + To support group chat (a feature of XMTP v3), set to `true`. As a best practice, regardless of whether your app provides group chat, set `enableV3` to `true` to benefit from other aspects of the upgraded XMTP v3 protocol. Enabling v3 doesn't stop your app's support for XMTP v2 functionality. + + + dbEncryptionKey + null + Required. For secure key storage in React Native, consider using libraries like `react-native-keychain` or `expo-secure-store`. These provide cross-platform solutions for securely storing sensitive data on both iOS and Android devices. + + + dbDirectory + xmtp_db + Optional. Specify a database directory. If no directory is specified, the value is set to `xmtp_db` by default. appVersion @@ -767,17 +875,6 @@ let client = try await Client.create(account: account, options: clientOptions) app support, especially around communicating important SDK updates, including deprecations and required upgrades. - - - - env - `dev` - - Connect 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](#xmtp-network-environments). -
@@ -786,18 +883,14 @@ let client = try await Client.create(account: account, options: clientOptions) ## XMTP network environments -XMTP identity on `dev` network is completely distinct from its XMTP identity on the `production` network, as are the messages associated with these identities. - -- `production`: This network is used in production and is configured to store messages indefinitely. - - - Try the web inbox at [https://xmtp.chat/](https://xmtp.chat/). +An 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. - - Send a message to our `gm` bot to get started. `gm.xmtp.eth` +- `production`: Use this network for production messages. -- `dev`: XMTP may occasionally delete messages and keys from this network + - To send and receive messages on the `production` network, you can use the open source Converse web app connected to the `production` network: [https://app.converse.xyz](https://app.converse.xyz). - - Try the web dev inbox at [https://dev.xmtp.chat/](https://xmtp.chat/). +- `dev`: Use this network for development. - - Send a message to our `gm` bot to get started. `0x8DC925338C1eE1fE62c0C43404371deb701BfB55` + - To send and receive messages on the `dev` network, you can use the open source Converse web app connected to the `dev` network: [https://app-preview.converse.xyz](https://app-preview.converse.xyz). -- `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. +- `local`: Use this network 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. diff --git a/docs/pages/dms/overview.md b/docs/pages/dms/overview.md index 37da4bf..edb04b6 100644 --- a/docs/pages/dms/overview.md +++ b/docs/pages/dms/overview.md @@ -290,9 +290,9 @@ npm i @xmtp/react-native-sdk ### Need to send a test message? -Message this XMTP message bot to get an immediate automated reply: +Message this XMTP message bot to get an immediate `gm` reply: -- `gm.xmtp.eth` (`0x937C0d4a6294cdfa575de17382c7076b579DC176`) +- `gm.xmtp.eth` (0x937C0d4a6294cdfa575de17382c7076b579DC176) ### Troubleshooting diff --git a/docs/pages/get-started/developer-quickstart.mdx b/docs/pages/get-started/developer-quickstart.mdx index 56c0771..73f301d 100644 --- a/docs/pages/get-started/developer-quickstart.mdx +++ b/docs/pages/get-started/developer-quickstart.mdx @@ -242,7 +242,7 @@ console.log("Wallet address: " + wallet.address); ### Create a client -To create a client, you need to pass in a wallet that implements the `Signer` interface. This is a requirement because the XMTP client uses the wallet to sign messages and verify the sender's identity. When you create a client, you can set [client parameters](/dms/client#configure-the-client), including which [network environment](/dms/client#xmtp-network-environments) (`env`) the client should connect to. +To create a client, you need to pass in a wallet that implements the `Signer` interface. This is a requirement because the XMTP client uses the wallet to sign messages and verify the sender's identity. When you create a client, you can set [client parameters](/client/create-client#configure-the-client), including which [network environment](/client/create-client#xmtp-network-environments) (`env`) the client should connect to. ```jsx const xmtp = await Client.create(signer, { env: "dev" }); diff --git a/docs/pages/get-started/examples.mdx b/docs/pages/get-started/examples.mdx index bfe504a..58c13c6 100644 --- a/docs/pages/get-started/examples.mdx +++ b/docs/pages/get-started/examples.mdx @@ -62,15 +62,6 @@ Here are some quickstarts and example apps to help you get started with building A Repl of a full flow for sending and streaming messages in JavaScript -
  • - - Floating inbox quickstart app - - Use it to help you build your own app with XMTP. -