docs: add _userBy query and userByName built-in interface for Built-in IdP

docs/guides/auth/integration/built-in-idp.md

@@ -312,6 +312,7 @@ Once registered, the IdP subgraph provides the following GraphQL operations for
 
 - `_users` - List IdP users with pagination and filtering
 - `_user` - Get a specific IdP user by ID
+- `_userBy` - Get a specific IdP user by ID or name
 
 **Mutation Operations:**
 
@@ -375,6 +376,32 @@ query GetUser($userId: ID!) {
 }
 ```
 
+**Get an IdP user by ID or name:**
+
+The `_userBy` query allows you to fetch a single user by exactly one of `id` or `name`. Exactly one argument must be provided — specifying both or neither returns an error.
+
+```graphql
+# By ID
+query GetUserById {
+  _userBy(id: "user-uuid") {
+    id
+    name
+    createdAt
+    disabled
+  }
+}
+
+# By name
+query GetUserByName {
+  _userBy(name: "foo@example.com") {
+    id
+    name
+    createdAt
+    disabled
+  }
+}
+```
+
 **Create a new IdP user:**
 
 ```graphql

docs/guides/function/builtin-interfaces.md

@@ -41,8 +41,9 @@ const { users, totalCount } = await client.users({
   query: { names: ["user@example.com"] },
 });
 
-// Get, update, delete
+// Get by ID or by name
 const user = await client.user(userId);
+const userByName = await client.userByName("foo@example.com");
 await client.updateUser({ id: userId, name: "new@example.com" });
 await client.deleteUser(userId);
 
@@ -57,6 +58,7 @@ await client.sendPasswordResetEmail({
 | --- | --- | --- |
 | `users(options?)` | `Promise<ListUsersResponse>` | List users with optional filtering and pagination |
 | `user(userId)` | `Promise<User>` | Get a user by ID |
+| `userByName(name)` | `Promise<User>` | Get a user by name |
 | `createUser(input)` | `Promise<User>` | Create a new user |
 | `updateUser(input)` | `Promise<User>` | Update an existing user |
 | `deleteUser(userId)` | `Promise<boolean>` | Delete a user by ID |

docs/guides/function/managing-idp-users.md

@@ -71,6 +71,7 @@ class Client {
   constructor(config: ClientConfig);
   users(options?: ListUsersOptions): Promise<ListUsersResponse>;
   user(userId: string): Promise<User>;
+  userByName(name: string): Promise<User>;
   createUser(input: CreateUserInput): Promise<User>;
   updateUser(input: UpdateUserInput): Promise<User>;
   deleteUser(userId: string): Promise<boolean>;
@@ -170,6 +171,25 @@ export default async (args) => {
 };
 ```
 
+### Get User by Name
+
+The `userByName` method retrieves a single user by their name.
+
+```js
+export default async (args) => {
+  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });
+
+  const user = await idpClient.userByName(args.userName);
+
+  return {
+    id: user.id,
+    name: user.name,
+    disabled: user.disabled,
+    createdAt: user.createdAt,
+  };
+};
+```
+
 ### Create User
 
 The `createUser` method creates a new user in the Built-in IdP. The `password` field is optional; if omitted, the user is created without a password and will not be able to log in until a password is set (e.g., via `sendPasswordResetEmail`).