Comments

/**
 * Create a new comment
 * @param args - Comment creation parameters
 * @returns Promise resolving to created comment
 */
comments.create(args: CreateCommentParameters): Promise<CreateCommentResponse>;

interface CreateCommentParameters {
  /** Parent page or block for the comment */
  parent: {
    type: "page_id";
    page_id: string;
  } | {
    type: "block_id";
    block_id: string;
  };
  /** Comment text */
  rich_text: RichTextItemResponse[];
}

type CreateCommentResponse = CommentObjectResponse;

// Comment on a page
const comment = await notion.comments.create({
  parent: { type: "page_id", page_id: "page-id" },
  rich_text: [
    {
      text: { content: "This is a great page!" },
    },
  ],
});

// Comment on a specific block
const blockComment = await notion.comments.create({
  parent: { type: "block_id", block_id: "block-id" },
  rich_text: [
    {
      text: { content: "Need to update this section." },
      annotations: { bold: true },
    },
  ],
});

// Comment with rich text formatting
const richComment = await notion.comments.create({
  parent: { type: "page_id", page_id: "page-id" },
  rich_text: [
    {
      text: { content: "Please review " },
    },
    {
      text: { content: "this section", link: { url: "https://example.com" } },
      annotations: { underline: true },
    },
    {
      text: { content: " by tomorrow." },
    },
  ],
});

/**
 * List comments for a page or block
 * @param args - Comment list parameters
 * @returns Promise resolving to list of comments
 */
comments.list(args: ListCommentsParameters): Promise<ListCommentsResponse>;

interface ListCommentsParameters {
  /** ID of the page or block to get comments for */
  block_id: string;
  /** Pagination cursor */
  start_cursor?: string;
  /** Page size (max 100) */
  page_size?: number;
}

type ListCommentsResponse = {
  object: "list";
  results: CommentObjectResponse[];
  next_cursor: string | null;
  has_more: boolean;
  type: "comment";
  comment: Record<string, unknown>;
};

// Get all comments for a page
const comments = await notion.comments.list({
  block_id: "page-id",
});

comments.results.forEach(comment => {
  console.log(`${comment.created_by.name}: ${comment.rich_text[0]?.text?.content}`);
});

// Paginated comment retrieval
const commentsPage = await notion.comments.list({
  block_id: "page-id",
  page_size: 25,
  start_cursor: "cursor-token",
});

// Get all comments with pagination
let cursor: string | undefined;
let allComments: CommentObjectResponse[] = [];

do {
  const response = await notion.comments.list({
    block_id: "page-id",
    start_cursor: cursor,
  });
  
  allComments.push(...response.results);
  cursor = response.next_cursor || undefined;
} while (cursor);

/**
 * Retrieve a comment by ID
 * @param args - Comment retrieval parameters
 * @returns Promise resolving to comment object
 */
comments.retrieve(args: GetCommentParameters): Promise<GetCommentResponse>;

interface GetCommentParameters {
  /** ID of the comment to retrieve */
  comment_id: string;
}

type GetCommentResponse = CommentObjectResponse;

// Get a specific comment
const comment = await notion.comments.retrieve({
  comment_id: "comment-id-here",
});

console.log(comment.rich_text[0]?.text?.content); // Comment text
console.log(comment.created_time); // When comment was created
console.log(comment.created_by.name); // Who created the comment

interface CommentObjectResponse {
  object: "comment";
  id: string;
  parent: {
    type: "page_id";
    page_id: string;
  } | {
    type: "block_id";
    block_id: string;
  };
  discussion_id: string;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  rich_text: RichTextItemResponse[];
}

interface PartialCommentObjectResponse {
  object: "comment";
  id: string;
}