docs: update fetching user details endpoint for ecosystems (#4918)

## Problem solved

Short description of the bug fixed or feature added

<!-- start pr-codex -->

---

## 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 identifiers.

### Detailed summary
- Added support for querying user details using `externalWalletAddress` in `getUser`.
- Updated documentation for `getUser` to include `externalWalletAddress` as a query parameter.
- Modified examples in the documentation to demonstrate querying with `externalWalletAddress`.
- Updated user detail query parameters in documentation to reflect new options.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->

Author: ElasticBottle

.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: "[email protected]",
+});
+```

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
 <Tabs defaultValue='wallet'>
   <TabsList>
     <TabsTrigger value='wallet'>Wallet</TabsTrigger>
+    <TabsTrigger value='external-wallet'>External Wallet</TabsTrigger>
     <TabsTrigger value='email'>Email</TabsTrigger>
     <TabsTrigger value='phone'>Phone</TabsTrigger>
     <TabsTrigger value='id'>User ID</TabsTrigger>
@@ -18,13 +19,26 @@ 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...",
 });
 ```
 </TabsContent>
 
+<TabsContent value='external-wallet'>
+```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...",
+});
+```
+</TabsContent>
+
 <TabsContent value='email'>
 ```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 protected]' \
+  -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
 

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<GetUserResult | null> {
   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.",
     );
   }