User Management

/**
 * Retrieve a user by ID
 * @param args - User retrieval parameters
 * @returns Promise resolving to user object
 */
users.retrieve(args: GetUserParameters): Promise<GetUserResponse>;

interface GetUserParameters {
  /** ID of the user to retrieve */
  user_id: string;
}

type GetUserResponse = UserObjectResponse;

// Get a specific user
const user = await notion.users.retrieve({
  user_id: "user-id-here",
});

console.log(user.name); // User's name
console.log(user.type); // "person" or "bot"
if (user.type === "person") {
  console.log(user.person.email); // Email for person users
}

/**
 * List all users in the workspace
 * @param args - User list parameters
 * @returns Promise resolving to list of users
 */
users.list(args: ListUsersParameters): Promise<ListUsersResponse>;

interface ListUsersParameters {
  /** Pagination cursor */
  start_cursor?: string;
  /** Page size (max 100) */
  page_size?: number;
}

type ListUsersResponse = {
  object: "list";
  results: UserObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: "user";
  user: Record<string, unknown>;
};

// Get all users
const users = await notion.users.list({});

console.log(users.results.length); // Number of users
users.results.forEach(user => {
  console.log(`${user.name} (${user.type})`);
});

// Paginated user listing
const usersPage = await notion.users.list({
  page_size: 50,
  start_cursor: "cursor-token",
});

// Get all users with pagination
let cursor: string | undefined;
let allUsers: UserObjectResponse[] = [];

do {
  const response = await notion.users.list({
    start_cursor: cursor,
  });
  
  allUsers.push(...response.results);
  cursor = response.next_cursor || undefined;
} while (cursor);

/**
 * Get information about the current authenticated user
 * @param args - Current user parameters (empty)
 * @returns Promise resolving to current user object
 */
users.me(args: GetSelfParameters): Promise<GetSelfResponse>;

interface GetSelfParameters {
  // No parameters required
}

type GetSelfResponse = UserObjectResponse;

// Get current user info
const currentUser = await notion.users.me({});

console.log(`Current user: ${currentUser.name}`);
console.log(`User type: ${currentUser.type}`);

if (currentUser.type === "bot") {
  console.log(`Bot owner: ${currentUser.bot.owner.type}`);
}

type UserObjectResponse = PersonUserObjectResponse | BotUserObjectResponse;

interface PersonUserObjectResponse {
  object: "user";
  id: string;
  type: "person";
  name?: string;
  avatar_url?: string;
  person: {
    email?: string;
  };
}

interface BotUserObjectResponse {
  object: "user";
  id: string;
  type: "bot";
  name?: string;
  avatar_url?: string;
  bot: {
    owner: {
      type: "workspace";
      workspace: true;
    } | {
      type: "user";
      user: PartialUserObjectResponse;
    };
    workspace_name?: string;
  };
}

interface GroupObjectResponse {
  object: "user";
  id: string;
  type: "group";
  name?: string;
  avatar_url?: string;
  group: Record<string, unknown>;
}

interface PartialUserObjectResponse {
  object: "user";
  id: string;
}