From 77d0c13bc616effecffc89aa0137ae1fd24f312b Mon Sep 17 00:00:00 2001 From: ElasticBottle Date: Fri, 4 Oct 2024 19:53:06 +0000 Subject: [PATCH] docs: update fetching user details endpoint for ecosystems (#4918) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem solved Short description of the bug fixed or feature added --- ## PR-Codex overview This PR focuses on enhancing the `getUser` functionality in the `thirdweb` SDK by adding support for querying user details via an external wallet address and ecosystem wallet details. ### Detailed summary - Added functionality to query user details using `externalWalletAddress`. - Updated documentation for `getUser` to reflect new parameters. - Modified examples to include querying by `externalWalletAddress`. - Enhanced user guide to include new querying options. > ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}` --- .changeset/sixty-cats-doubt.md | 30 +++++++++++ .../guides/get-user-details/page.mdx | 53 ++++++++++++++++--- .../src/wallets/in-app/core/users/getUser.ts | 18 ++++--- 3 files changed, 87 insertions(+), 14 deletions(-) create mode 100644 .changeset/sixty-cats-doubt.md diff --git a/.changeset/sixty-cats-doubt.md b/.changeset/sixty-cats-doubt.md new file mode 100644 index 00000000000..30debd87128 --- /dev/null +++ b/.changeset/sixty-cats-doubt.md @@ -0,0 +1,30 @@ +--- +"thirdweb": patch +--- + +Add querying for in app wallet user details via externally linked wallet address: + +```ts +import { getUser } from "thirdweb"; + +// this is the wallet address that the user used to connect via SIWE to their in app wallet +const user = await getUser({ + client, + externalWalletAddress: "0x123...", +}); +``` + +Add querying for ecosystem wallet user details: + +```ts +import { getUser } from "thirdweb"; + +const user = await getUser({ + client, + ecosystem: { + id: "ecosystem.YOUR_ID", + partnerId: "OPTIONAL_PARTNER_ID" + } + email: "user@example.com", +}); +``` diff --git a/apps/portal/src/app/connect/in-app-wallet/guides/get-user-details/page.mdx b/apps/portal/src/app/connect/in-app-wallet/guides/get-user-details/page.mdx index 274ada0945c..4d334b03812 100644 --- a/apps/portal/src/app/connect/in-app-wallet/guides/get-user-details/page.mdx +++ b/apps/portal/src/app/connect/in-app-wallet/guides/get-user-details/page.mdx @@ -9,6 +9,7 @@ You can query user details through the thirdweb SDK using a wallet address, emai Wallet + External Wallet Email Phone User ID @@ -18,6 +19,7 @@ You can query user details through the thirdweb SDK using a wallet address, emai ```ts import { getUser } from "thirdweb"; +// this is the wallet address that thirdweb has generated for the user const user = await getUser({ client, walletAddress: "0x123...", @@ -25,6 +27,18 @@ const user = await getUser({ ``` + +```ts +import { getUser } from "thirdweb"; + +// this is the wallet address that the user used to connect via SIWE to their in app wallet +const user = await getUser({ + client, + externalWalletAddress: "0x123...", +}); +``` + + ```ts import { getUser } from "thirdweb"; @@ -70,27 +84,52 @@ https://embedded-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details ### Query Parameters -You can query user details using one of the following parameters: +You can specify the query parameter `queryBy` to query by different user identifiers: + +- `queryBy`: The parameter to query by. Can be one of `walletAddress`, `email`, `phone`, `externalWalletAddress`, or `id`. + +You can then specify the value to query by, matching the queryBy parameter: -- `walletAddress`: The user's wallet address +- `walletAddress`: The user's wallet address that thirdweb has generated for them - `email`: The user's email address - `phone`: The user's phone number -- `id`: The user's ID +- `externalWalletAddress`: The user's wallet address that used to login via SIWE +- `id`: The user's ID (for custom auth) ### Authentication -You need to include your ThirdWeb Client Secret in the Authorization header. +You need to include your ThirdWeb Client Secret in the Authorization header. + +If you are an ecosystem owner, you have to include the `x-ecosystem-id` header and optionally the `x-ecosystem-partner-id` header if the ecosystem is set to partners only. ### Example curl Command -Here's an example curl command to fetch user details: +Here's an example curl command to fetch user details by email: + +```bash +curl -X GET 'https://embedded-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details?queryBy=email&email=user@example.com' \ + -H 'x-secret-key: YOUR_THIRD_WEB_CLIENT_SECRET' +``` + +Here's an example curl command to fetch user details by address: ```bash curl -X GET 'https://embedded-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details?queryBy=walletAddress&walletAddress=0x123456789abcdef' \ - -H 'Authorization: Bearer YOUR_THIRD_WEB_CLIENT_SECRET' + -H 'x-secret-key: YOUR_THIRD_WEB_CLIENT_SECRET' ``` -Replace `YOUR_THIRD_WEB_CLIENT_SECRET` with your actual ThirdWeb Client Secret. +Here's an example curl command to fetch the user details for an ecosystem owner: + +```bash +curl -X GET 'https://embedded-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details?queryBy=walletAddress&walletAddress=0x123456789abcdef' \ + -H 'x-secret-key: YOUR_THIRD_WEB_CLIENT_SECRET' \ + -H 'x-ecosystem-id: ecosystem.YOUR_ECOSYSTEM_ID' \ + -H 'x-ecosystem-partner-id: YOUR_PARTNER_ID' +``` + +In both examples, replace `YOUR_THIRD_WEB_CLIENT_SECRET` with your actual ThirdWeb Client Secret. + +Replace `YOUR_ECOSYSTEM_ID` and `YOUR_PARTNER_ID` with your actual ecosystem ID and partner ID respectively. The partner ID can be one you set up for yourself as the ecosystem owner. ### Response Format diff --git a/packages/thirdweb/src/wallets/in-app/core/users/getUser.ts b/packages/thirdweb/src/wallets/in-app/core/users/getUser.ts index e18d211df63..43c9ef72826 100644 --- a/packages/thirdweb/src/wallets/in-app/core/users/getUser.ts +++ b/packages/thirdweb/src/wallets/in-app/core/users/getUser.ts @@ -18,24 +18,23 @@ export type GetUserResult = { * Gets user based on the provided query parameters. * @note This function is only available on the server (a secret key is required in the client). * - * @param options - The options for the find users function. + * @param options - The options for the get user function. * @param options.client - The Thirdweb client with a secret key included. - * @param [options.walletAddress] - The wallet address to query by. + * @param [options.walletAddress] - The wallet address generated by thirdweb to query by. * @param [options.email] - The email to query by. * @param [options.phone] - The phone number to query by. * @param [options.id] - The user ID to query by. + * @param [options.externalWalletAddress] - The linked external wallet address to query by. * - * @returns An array of user objects. + * @returns A user object or null if not found. * * @example - * ```ts * import { getUser } from "thirdweb/wallets"; * * const user = await getUser({ * client, * walletAddress: "0x123...", * }); - * ``` * * @wallet */ @@ -45,16 +44,18 @@ export async function getUser({ email, phone, id, + externalWalletAddress, ecosystem, }: Prettify< { client: ThirdwebClient; + ecosystem?: Ecosystem; } & OneOf<{ walletAddress?: string; email?: string; phone?: string; id?: string; - ecosystem?: Ecosystem; + externalWalletAddress?: string; }> >): Promise { if (!client.secretKey) { @@ -79,9 +80,12 @@ export async function getUser({ } else if (id) { url.searchParams.set("queryBy", "id"); url.searchParams.set("id", id); + } else if (externalWalletAddress) { + url.searchParams.set("queryBy", "externalWalletAddress"); + url.searchParams.set("externalWalletAddress", externalWalletAddress); } else { throw new Error( - "Please provide a walletAddress, email, phone, or id to query for users.", + "Please provide a walletAddress, email, phone, id, or externalWalletAddress to query for users.", ); }