create-feedbax 0.1.0 → 0.2.0

package/template/src/feedbax/feedback/notion-comments.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createNotionCommentStorage } from "./notion-comments";
+
+describe("Notion Comment HTTP boundary", () => {
+  it("creates native page Comments and discussion replies with a custom display name", async () => {
+    const request = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(
+        Response.json(
+          notionComment({
+            id: "created-comment",
+            display_name: { type: "custom", resolved_name: "Ari" },
+          }),
+        ),
+      )
+      .mockResolvedValueOnce(
+        Response.json(
+          notionComment({
+            id: "created-reply",
+            display_name: { type: "custom", resolved_name: "Ari" },
+          }),
+        ),
+      );
+    const comments = createNotionCommentStorage({
+      token: "notion-token",
+      dataSourceId: "feedback",
+      propertyIds: {} as never,
+      request,
+    });
+
+    await comments.createPageComment({
+      postId: "page-1",
+      body: "A public message",
+      displayName: "Ari",
+    });
+    await comments.createDiscussionReply({
+      postId: "page-1",
+      discussionId: "discussion-1",
+      body: "A reply",
+      displayName: "Ari",
+    });
+
+    expect(
+      request.mock.calls.map((call) => JSON.parse(String(call[1]?.body))),
+    ).toEqual([
+      {
+        parent: { page_id: "page-1" },
+        rich_text: [{ type: "text", text: { content: "A public message" } }],
+        display_name: { type: "custom", custom: { name: "Ari" } },
+      },
+      {
+        discussion_id: "discussion-1",
+        rich_text: [{ type: "text", text: { content: "A reply" } }],
+        display_name: { type: "custom", custom: { name: "Ari" } },
+      },
+    ]);
+  });
+  it("requests 50 page Comments, preserves the cursor, and classifies public authors", async () => {
+    const request = vi.fn<typeof fetch>().mockResolvedValue(
+      Response.json({
+        results: [
+          notionComment({
+            id: "participant",
+            display_name: { type: "custom", resolved_name: "Ari" },
+          }),
+          notionComment({ id: "team", discussion_id: "discussion-1" }),
+          notionComment({ id: "resolved", resolved: true }),
+        ],
+        has_more: true,
+        next_cursor: "next-native-cursor",
+      }),
+    );
+    const comments = createNotionCommentStorage({
+      token: "notion-token",
+      dataSourceId: "feedback",
+      propertyIds: {} as never,
+      request,
+    });
+
+    await expect(
+      comments.listPageComments("page-1", "start-native-cursor"),
+    ).resolves.toMatchObject({
+      items: [
+        { author: { kind: "participant", displayName: "Ari" }, scope: "page" },
+        {
+          author: { kind: "product-team", displayName: "Product Team" },
+          scope: "page",
+        },
+      ],
+      nextCursor: "next-native-cursor",
+    });
+    expect(String(request.mock.calls[0]?.[0])).toBe(
+      "https://api.notion.com/v1/comments?block_id=page-1&page_size=50&start_cursor=start-native-cursor",
+    );
+  });
+
+  it("returns actionable repair instructions for missing read permission", async () => {
+    const comments = createNotionCommentStorage({
+      token: "notion-token",
+      dataSourceId: "feedback",
+      propertyIds: {} as never,
+      request: vi
+        .fn<typeof fetch>()
+        .mockResolvedValue(new Response(null, { status: 403 })),
+    });
+    await expect(comments.listPageComments("page-1")).rejects.toThrow(
+      "Enable read comment content for the connection, then retry.",
+    );
+  });
+
+  it("updates and deletes native Comments", async () => {
+    const request = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(Response.json(notionComment({ id: "comment-1" })))
+      .mockResolvedValueOnce(new Response(null, { status: 204 }));
+    const comments = createNotionCommentStorage({
+      token: "notion-token",
+      dataSourceId: "feedback",
+      propertyIds: {} as never,
+      request,
+    });
+
+    await comments.updateComment("comment-1", "Corrected message");
+    await comments.deleteComment("comment-1");
+
+    expect(String(request.mock.calls[0]?.[0])).toBe(
+      "https://api.notion.com/v1/comments/comment-1",
+    );
+    expect(request.mock.calls[0]?.[1]).toMatchObject({
+      method: "PATCH",
+      body: JSON.stringify({
+        rich_text: [{ type: "text", text: { content: "Corrected message" } }],
+      }),
+    });
+    expect(request.mock.calls[1]).toMatchObject([
+      "https://api.notion.com/v1/comments/comment-1",
+      expect.objectContaining({ method: "DELETE" }),
+    ]);
+  });
+
+  it("returns actionable permission failures for native Comment mutations", async () => {
+    const comments = createNotionCommentStorage({
+      token: "notion-token",
+      dataSourceId: "feedback",
+      propertyIds: {} as never,
+      request: vi
+        .fn<typeof fetch>()
+        .mockResolvedValue(new Response(null, { status: 403 })),
+    });
+
+    await expect(
+      comments.updateComment("comment-1", "Updated"),
+    ).rejects.toThrow("permission to update this Comment");
+    await expect(comments.deleteComment("comment-1")).rejects.toThrow(
+      "permission to delete this Comment",
+    );
+  });
+});
+
+function notionComment(overrides: Record<string, unknown>) {
+  return {
+    object: "comment",
+    id: "comment-1",
+    parent: { type: "page_id", page_id: "page-1" },
+    discussion_id: "discussion-1",
+    created_time: "2026-08-20T13:00:00.000Z",
+    rich_text: [{ plain_text: "A public message" }],
+    ...overrides,
+  };
+}

package/template/src/feedbax/feedback/notion-comments.ts

@@ -0,0 +1,231 @@
+import type { CommentAuthor } from "./index";
+import type { NotionFeedbackStorageOptions } from "./notion-feedback";
+import { requestNotion } from "./notion-request";
+
+const NOTION_API_URL = "https://api.notion.com/v1";
+const NOTION_API_VERSION = "2026-03-11";
+
+export interface StoredComment {
+  id: string;
+  postId: string;
+  discussionId: string;
+  body: string;
+  author: CommentAuthor;
+  createdAt: Date;
+  resolved: boolean;
+  scope?: "page" | "block";
+}
+
+export interface CommentStorage {
+  createPageComment(input: {
+    postId: string;
+    body: string;
+    displayName: string;
+  }): Promise<StoredComment>;
+  createDiscussionReply(input: {
+    postId: string;
+    discussionId: string;
+    body: string;
+    displayName: string;
+  }): Promise<StoredComment>;
+  listPageComments(
+    postId: string,
+    cursor?: string,
+  ): Promise<{
+    items: StoredComment[];
+    nextCursor?: string;
+  }>;
+  updateComment(commentId: string, body: string): Promise<StoredComment>;
+  deleteComment(commentId: string): Promise<void>;
+}
+
+export function createNotionCommentStorage({
+  token,
+  request = fetch,
+  retry,
+}: NotionFeedbackStorageOptions): CommentStorage {
+  return {
+    createPageComment: (input) =>
+      createComment({
+        parent: { page_id: input.postId },
+        body: input.body,
+        displayName: input.displayName,
+        postId: input.postId,
+      }),
+    createDiscussionReply: (input) =>
+      createComment({
+        discussion_id: input.discussionId,
+        body: input.body,
+        displayName: input.displayName,
+        postId: input.postId,
+      }),
+    async listPageComments(postId, cursor) {
+      const url = new URL(`${NOTION_API_URL}/comments`);
+      url.searchParams.set("block_id", postId);
+      url.searchParams.set("page_size", "50");
+      if (cursor) url.searchParams.set("start_cursor", cursor);
+      const response = await requestNotion(
+        url,
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Notion-Version": NOTION_API_VERSION,
+          },
+        },
+        { request, retry, operation: "idempotent" },
+      );
+      if (!response.ok)
+        throw new Error(
+          response.status === 403
+            ? "Notion cannot read Comments. Enable read comment content for the connection, then retry."
+            : `Notion rejected the Comment request (${response.status}).`,
+        );
+      const value: unknown = await response.json();
+      if (!isRecord(value) || !Array.isArray(value.results))
+        throw new Error("Notion returned an invalid Comment list.");
+      const items = value.results
+        .map((entry) => commentFromNotion(entry, postId))
+        .filter((comment) => !comment.resolved);
+      const nextCursor =
+        value.has_more === true ? value.next_cursor : undefined;
+      if (nextCursor !== undefined && typeof nextCursor !== "string")
+        throw new Error("Notion returned an invalid Comment cursor.");
+      return { items, ...(nextCursor ? { nextCursor } : {}) };
+    },
+    async updateComment(commentId, body) {
+      const response = await requestNotion(
+        `${NOTION_API_URL}/comments/${encodeURIComponent(commentId)}`,
+        {
+          method: "PATCH",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "Notion-Version": NOTION_API_VERSION,
+          },
+          body: JSON.stringify({
+            rich_text: [{ type: "text", text: { content: body } }],
+          }),
+        },
+        { request, retry, operation: "idempotent" },
+      );
+      if (!response.ok) throw commentMutationFailure(response.status, "update");
+      return commentFromNotion(await response.json(), "");
+    },
+    async deleteComment(commentId) {
+      const response = await requestNotion(
+        `${NOTION_API_URL}/comments/${encodeURIComponent(commentId)}`,
+        {
+          method: "DELETE",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Notion-Version": NOTION_API_VERSION,
+          },
+        },
+        { request, retry, operation: "idempotent" },
+      );
+      if (!response.ok) throw commentMutationFailure(response.status, "delete");
+    },
+  };
+
+  async function createComment(input: {
+    parent?: { page_id: string };
+    discussion_id?: string;
+    body: string;
+    displayName: string;
+    postId: string;
+  }): Promise<StoredComment> {
+    const response = await requestNotion(
+      `${NOTION_API_URL}/comments`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          "Notion-Version": NOTION_API_VERSION,
+        },
+        body: JSON.stringify({
+          ...(input.parent ? { parent: input.parent } : {}),
+          ...(input.discussion_id
+            ? { discussion_id: input.discussion_id }
+            : {}),
+          rich_text: [{ type: "text", text: { content: input.body } }],
+          display_name: {
+            type: "custom",
+            custom: { name: input.displayName },
+          },
+        }),
+      },
+      { request, retry, operation: "create" },
+    );
+    if (!response.ok)
+      throw new Error(
+        response.status === 403
+          ? "Notion cannot create Comments. Enable insert comment capability for the connection, then retry."
+          : `Notion rejected the Comment creation (${response.status}).`,
+      );
+    return commentFromNotion(await response.json(), input.postId);
+  }
+}
+
+function commentMutationFailure(status: number, action: "update" | "delete") {
+  return new Error(
+    status === 403
+      ? `Notion does not grant permission to ${action} this Comment. Only Comments created by this connection can be changed.`
+      : `Notion rejected the Comment ${action} (${status}). The Comment may have been resolved or deleted.`,
+  );
+}
+
+function commentFromNotion(value: unknown, postId: string): StoredComment {
+  if (!isRecord(value)) throw new Error("Notion returned an invalid Comment.");
+  const id = requiredString(value.id, "Comment ID");
+  const discussionId = requiredString(value.discussion_id, "discussion ID");
+  const createdAt = new Date(
+    requiredString(value.created_time, "created time"),
+  );
+  if (Number.isNaN(createdAt.getTime()))
+    throw new Error("Notion returned an invalid Comment created time.");
+  const parent = value.parent;
+  const pageLevel =
+    !postId ||
+    (isRecord(parent) &&
+      parent.type === "page_id" &&
+      parent.page_id === postId);
+  const richText = Array.isArray(value.rich_text) ? value.rich_text : [];
+  const body = richText
+    .map((part) =>
+      isRecord(part) && typeof part.plain_text === "string"
+        ? part.plain_text
+        : "",
+    )
+    .join("");
+  const displayName = value.display_name;
+  const participantName =
+    isRecord(displayName) &&
+    displayName.type === "custom" &&
+    typeof displayName.resolved_name === "string" &&
+    displayName.resolved_name.trim()
+      ? displayName.resolved_name.trim()
+      : undefined;
+  return {
+    id,
+    postId,
+    discussionId,
+    body,
+    author: participantName
+      ? { kind: "participant", displayName: participantName }
+      : { kind: "product-team", displayName: "Product Team" },
+    createdAt,
+    resolved: value.resolved === true,
+    scope: pageLevel ? "page" : "block",
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function requiredString(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value)
+    throw new Error(`Notion returned an invalid ${label}.`);
+  return value;
+}