# `users` API

Helpers for reading workspace users from inside a custom block. The SDK forwards each call to Notion on your behalf.

```ts
import {
  customBlock,
  initCustomBlock,
  users,
  type NotionUserId,
} from "ncblock";
import { useCurrentUser } from "ncblock/react";
```

Every helper returns a discriminated result instead of throwing:

```ts
const result = await users.get(userId);
if (result.status === "success") {
  // result.user is a NotionUser
} else {
  // result.error is a human-readable string
}
```

Always check `result.status` before reading `result.user` / `result.list`.

## Reading the current user

`useCurrentUser()` returns the viewing user's `NotionUser` from the initial host payload, so your first render can personalize or filter without a separate `users.get` request.

```ts
const me = useCurrentUser();
// me.id, me.name, me.person.email
```

The hook updates when the host sends `currentUserChanged`, so renders stay in sync if the viewer's profile changes.

For non-React renderers, read the same state through `customBlock` after initialization:

```ts
await initCustomBlock()
const me = customBlock.getCurrentUser()

const unsubscribe = customBlock.subscribe(() => {
	const nextMe = customBlock.getCurrentUser()
	// Update your renderer with nextMe.
})
```

## Listing users

`users.list(input?)` returns workspace users visible to the current custom block, mirroring Notion's [`GET /v1/users`](https://developers.notion.com/reference/get-users) shape.

```ts
const result = await users.list({ pageSize: 50 });
if (result.status === "error") return;

for (const user of result.list.results) {
  console.log(user.id, user.name, user.person.email);
}

if (result.list.has_more && result.list.next_cursor) {
  const next = await users.list({ startCursor: result.list.next_cursor });
  // ...
}
```

`ListUsersInput` accepts `pageSize` and `startCursor`; both are optional. `ListUsersResult` resolves to either `{ status: "success", list }` or `{ status: "error", error }`, where `list` is a `NotionUserList` (with `results`, `next_cursor`, `has_more`).

## Reading a single user

`users.get(userId)` fetches one `NotionUser` by `NotionUserId`:

```ts
const result = await users.get(userId);
if (result.status === "success") {
  console.log(result.user.name);
}
```

`GetUserResult` follows the same success/error shape and returns `{ status: "success", user }` when the host resolves the user.

## Types

- `NotionUser` — the user record returned by `users.get` and inside `NotionUserList.results`.
- `NotionUserId` — branded string ID for a user.
- `NotionUserList` — paginated list shape returned by `users.list`.
- `useCurrentUser()` — hook that returns the viewer's `NotionUser`.
- `customBlock.getCurrentUser()` — framework-neutral getter for the viewer's `NotionUser`.
- `ListUsersInput` / `ListUsersResult`.
- `GetUserResult`.