create-feedbax 0.2.0 → 0.2.2

package/template/src/feedbax/feedback/index.ts

@@ -1,3 +1,4 @@
+import type { PostOwnership } from "./ownership";
 import {
   createHash,
   randomBytes,
@@ -9,16 +10,18 @@ import {
   createNotionFeedbackStorage,
   type NotionFeedbackStorageOptions,
 } from "./notion-feedback";
+import {
+  createGitHubFeedbackStorage,
+  type GitHubFeedbackOptions,
+} from "./github-feedback";
+import { createGitHubCommentStorage } from "./github-comments";
+import type { CommentStorage, StoredComment } from "./comment-storage";
 import type {
   FeedbackStorage,
   NewStoredPost,
   StoredPost,
 } from "./feedback-storage";
-import {
-  createNotionCommentStorage,
-  type CommentStorage,
-  type StoredComment,
-} from "./notion-comments";
+import { createNotionCommentStorage } from "./notion-comments";
 
 export {
   createNotionFeedbackDataSource,
@@ -35,6 +38,8 @@ export type PostStatus =
   "New" | "Reviewing" | "Planned" | "In Progress" | "Shipped" | "Closed";
 
 export interface SubmitPostInput {
+  submissionKey?: string;
+  imageIds?: string[];
   title: string;
   description: string;
   type: PostType;
@@ -49,6 +54,7 @@ export interface SubmitTrustedPostInput extends SubmitPostInput {
 }
 
 export interface Post extends SubmitPostInput {
+  images?: import("./images").ImageAttachment[];
   id: string;
   slug: string;
   status: PostStatus;
@@ -90,6 +96,7 @@ export type PublicPost = Pick<
   voteCount?: number;
   teamResponse?: string;
   releaseNotesUrl?: string;
+  images?: import("./images").ImageAttachment[];
 };
 
 export interface ChangeVoteInput {
@@ -127,13 +134,14 @@ export type DraftPost = Pick<
   | "createdAt"
   | "updatedAt"
   | "submitter"
+  | "images"
 >;
 
 export type TrustedSubmittedPost = Omit<Post, "published" | "submitter">;
 
 export interface EditDraftPostInput {
   id: string;
-  browserCapability: BrowserCapability;
+  browserCapability?: BrowserCapability;
   title?: string;
   description?: string;
   type?: PostType;
@@ -141,7 +149,7 @@ export interface EditDraftPostInput {
 
 export interface WithdrawDraftPostInput {
   id: string;
-  browserCapability: BrowserCapability;
+  browserCapability?: BrowserCapability;
 }
 
 export type GetDraftPostInput = WithdrawDraftPostInput;
@@ -162,10 +170,11 @@ export interface PublicPostPage {
 }
 
 export type CommentAuthor =
-  | { kind: "participant"; displayName: string }
+  | { kind: "participant"; displayName: string; verified?: boolean }
   | { kind: "product-team"; displayName: "Product Team" };
 
 export interface Comment {
+  images?: import("./images").ImageAttachment[];
   id: string;
   body: string;
   author: CommentAuthor;
@@ -188,6 +197,10 @@ export interface ListCommentThreadsInput {
 }
 
 export interface CreateCommentInput {
+  submissionKey?: string;
+  /** Internal recovery precondition; it never grants Comment authority. */
+  recoveryCommentId?: string;
+  imageIds?: string[];
   slug: string;
   body: string;
   displayName: string;
@@ -197,7 +210,9 @@ export interface ReplyToCommentThreadInput extends CreateCommentInput {
   discussionId: string;
 }
 
+export const recoverableComment = Symbol("recoverable-comment");
 export interface CreatedComment extends Comment {
+  [recoverableComment]?: boolean;
   discussionId: string;
 }
 
@@ -354,7 +369,27 @@ class InMemoryFeedbackStorage implements FeedbackStorage {
   }
 }
 
+export type ParticipantPost = Pick<
+  Post,
+  | "id"
+  | "slug"
+  | "title"
+  | "description"
+  | "type"
+  | "status"
+  | "published"
+  | "createdAt"
+  | "updatedAt"
+> & { editable: boolean };
+
 export interface FeedbackModule {
+  getParticipantPost(id: string): Promise<ParticipantPost | undefined>;
+  claimDraftPost(
+    input: GetDraftPostInput,
+  ): Promise<ParticipantPost | undefined>;
+  getAttachmentPostState(
+    slug: string,
+  ): Promise<"published" | "draft" | "private" | undefined>;
   createComment(input: CreateCommentInput): Promise<CreatedComment>;
   replyToCommentThread(
     input: ReplyToCommentThreadInput,
@@ -384,6 +419,7 @@ export type FeedbackMutationModule = Pick<
 >;
 
 interface CreateFeedbackModuleOptions {
+  ownership?: PostOwnership;
   initialItems?: StoredPost[];
   storage?: FeedbackStorage;
   votingEnabled?: boolean;
@@ -403,10 +439,39 @@ export function createFeedbackModule(
     options.commentStorage ??
     createInMemoryCommentStorage(options.initialComments);
   const voteQueues = new Map<string, Promise<void>>();
+  const authorizedDraft = async (
+    item: StoredPost | undefined,
+    capability?: BrowserCapability,
+  ): Promise<boolean> =>
+    Boolean(
+      item &&
+      isEditableDraft(item) &&
+      (authorizesDraft(item, capability) ||
+        (await options.ownership?.owns(item.id))),
+    );
+  const participantPost = async (
+    id: string,
+  ): Promise<ParticipantPost | undefined> => {
+    if (!(await options.ownership?.owns(id))) return;
+    const item = await storage.find(id);
+    if (!item) return;
+    return {
+      id: item.id,
+      slug: item.slug,
+      title: item.title,
+      description: item.description,
+      type: item.type,
+      status: item.status,
+      published: item.published,
+      createdAt: item.createdAt,
+      updatedAt: item.updatedAt,
+      editable: isEditableDraft(item),
+    };
+  };
   const editStoredDraft = async (input: EditDraftPostInput) => {
     const item = await storage.find(input.id);
 
-    if (!authorizesDraft(item, input.browserCapability)) {
+    if (!item || !(await authorizedDraft(item, input.browserCapability))) {
       throw new BrowserCapabilityAuthorizationError();
     }
 
@@ -432,7 +497,29 @@ export function createFeedbackModule(
   };
 
   return {
+    getParticipantPost: participantPost,
+    async claimDraftPost(input) {
+      const item = await storage.find(input.id);
+      if (!options.ownership || !authorizesDraft(item, input.browserCapability))
+        throw new BrowserCapabilityAuthorizationError();
+      await options.ownership.register(toPost(item));
+      return participantPost(item.id);
+    },
+    async getAttachmentPostState(slug) {
+      const post = await storage.findBySlug(slug);
+      return !post
+        ? undefined
+        : post.published
+          ? "published"
+          : post.status === "New" && post.draftEditable !== false
+            ? "draft"
+            : "private";
+    },
     async createComment(input) {
+      if (input.recoveryCommentId && !commentStorage.supportsIntentRecovery)
+        throw new CommentValidationError(
+          "Attached Comment recovery is unavailable.",
+        );
       const { post, body, displayName } = await validateCommentCreation(
         input,
         storage,
@@ -440,12 +527,22 @@ export function createFeedbackModule(
       return toCreatedComment(
         await commentStorage.createPageComment({
           postId: post.id,
+          ...(input.recoveryCommentId
+            ? { recoveryCommentId: input.recoveryCommentId }
+            : {}),
+          ...(input.submissionKey
+            ? { submissionKey: input.submissionKey }
+            : {}),
           body,
           displayName,
         }),
       );
     },
     async replyToCommentThread(input) {
+      if (input.recoveryCommentId && !commentStorage.supportsIntentRecovery)
+        throw new CommentValidationError(
+          "Attached Comment recovery is unavailable.",
+        );
       const { post, body, displayName } = await validateCommentCreation(
         input,
         storage,
@@ -472,6 +569,12 @@ export function createFeedbackModule(
         await commentStorage.createDiscussionReply({
           postId: post.id,
           discussionId: input.discussionId,
+          ...(input.recoveryCommentId
+            ? { recoveryCommentId: input.recoveryCommentId }
+            : {}),
+          ...(input.submissionKey
+            ? { submissionKey: input.submissionKey }
+            : {}),
           body,
           displayName,
         }),
@@ -536,10 +639,29 @@ export function createFeedbackModule(
     submitPost(input) {
       const submission = postCreationQueue.then(async () => {
         const now = new Date();
-        const browserCapability = createBrowserCapability();
+        const { submissionKey, ...content } = input;
+        if (
+          submissionKey !== undefined &&
+          !/^[A-Za-z0-9_-]{43}$/.test(submissionKey)
+        )
+          throw new Error("Submission intent is invalid.");
+        const browserCapability = submissionKey
+          ? (submissionKey as BrowserCapability)
+          : createBrowserCapability();
+        const externalId = submissionKey
+          ? `portal:${hashBrowserCapability(browserCapability)}`
+          : undefined;
+        if (externalId) {
+          const previous = await storage.findByExternalId(externalId);
+          if (previous) {
+            await options.ownership?.register(toPost(previous));
+            return { ...toPost(previous), browserCapability };
+          }
+        }
         const slug = await createUniqueSlug(input.title, storage);
         const item = await storage.create({
-          ...input,
+          ...content,
+          ...(externalId ? { externalId } : {}),
           slug,
           status: "New",
           published: false,
@@ -549,6 +671,7 @@ export function createFeedbackModule(
           voteCount: 0,
         });
 
+        await options.ownership?.register(toPost(item));
         return {
           ...toPost(item),
           browserCapability,
@@ -571,7 +694,7 @@ export function createFeedbackModule(
     },
     async getDraftPost(input) {
       const item = await storage.find(input.id);
-      if (!authorizesDraft(item, input.browserCapability)) {
+      if (!item || !(await authorizedDraft(item, input.browserCapability))) {
         throw new BrowserCapabilityAuthorizationError();
       }
       return toDraftPost(toPost(item));
@@ -619,11 +742,12 @@ export function createFeedbackModule(
     async withdrawDraftPost(input) {
       const item = await storage.find(input.id);
 
-      if (!authorizesDraft(item, input.browserCapability)) {
+      if (!item || !(await authorizedDraft(item, input.browserCapability))) {
         throw new BrowserCapabilityAuthorizationError();
       }
 
       await storage.remove(item.id);
+      await options.ownership?.withdrawn(item.id);
     },
     async getPublicPostRoadmap() {
       const pages = await Promise.all(
@@ -640,9 +764,11 @@ export function createNotionFeedbackModule(
   options: NotionFeedbackStorageOptions & {
     votingEnabled?: boolean;
     commentsEnabled?: boolean;
+    ownership?: PostOwnership;
   },
 ): FeedbackModule {
   return createFeedbackModule({
+    ownership: options.ownership,
     storage: createNotionFeedbackStorage(options),
     commentStorage: createNotionCommentStorage(options),
     votingEnabled: options.votingEnabled,
@@ -650,6 +776,21 @@ export function createNotionFeedbackModule(
   });
 }
 
+export function createGitHubFeedbackModule(
+  options: GitHubFeedbackOptions & { ownership?: PostOwnership },
+): FeedbackModule {
+  const storage = createGitHubFeedbackStorage(options);
+  return createFeedbackModule({
+    storage,
+    ownership: options.ownership,
+    commentStorage: createGitHubCommentStorage(options, storage),
+    votingEnabled: options.votingEnabled,
+    commentsEnabled: options.commentsEnabled,
+  });
+}
+
+export type { GitHubFeedbackOptions } from "./github-feedback";
+
 function createInMemoryCommentStorage(
   initialComments: StoredComment[] = [],
 ): CommentStorage {
@@ -743,13 +884,16 @@ async function validateCommentCreation(
 }
 
 function toCreatedComment(comment: StoredComment): CreatedComment {
-  return {
+  const result: CreatedComment = {
     id: comment.id,
     discussionId: comment.discussionId,
     body: comment.body,
     author: comment.author,
     createdAt: comment.createdAt,
   };
+  if (comment.recoverable)
+    Object.defineProperty(result, recoverableComment, { value: true });
+  return result;
 }
 
 function encodePublicPostCursor(
@@ -915,9 +1059,15 @@ function hashBrowserCapability(browserCapability: BrowserCapability): string {
 
 function authorizesDraft(
   item: StoredPost | undefined,
-  browserCapability: BrowserCapability,
+  browserCapability: BrowserCapability | undefined,
 ): item is StoredPost & { browserCapabilityHash: string } {
-  if (!item?.browserCapabilityHash || item.status !== "New" || item.published) {
+  if (
+    !browserCapability ||
+    !item?.browserCapabilityHash ||
+    item.status !== "New" ||
+    item.published ||
+    item.draftEditable === false
+  ) {
     return false;
   }
 
@@ -940,3 +1090,63 @@ function isPublicPostRoadmapItem<Item extends Post>(
       item.status === "Shipped")
   );
 }
+
+export {
+  createConnectedStore,
+  type ConnectedStore,
+  type ConnectedDatabase,
+  type VerifiedParticipant,
+} from "./connected";
+export {
+  signIdentityHandoff,
+  verifyIdentityHandoff,
+  type IdentityHandoff,
+} from "./identity-handoff";
+
+export { createConnectedFeedbackModule } from "./connected-feedback";
+
+export {
+  createParticipationModule,
+  type ParticipantNotification,
+  type FollowState,
+} from "./participation";
+export {
+  createEmailSender,
+  type EmailSender,
+  type NotificationEmail,
+  type CloudflareEmailBinding,
+} from "./email-delivery";
+
+export {
+  createImageModule,
+  ImageAttachmentError,
+  type ImageAttachment,
+} from "./images";
+
+export { createImageFeedbackModule } from "./image-feedback";
+export { createNotionImageReviewWriter } from "./notion-image-review";
+
+export { createGitHubServiceAccess } from "./github-service-client";
+export {
+  createObservedHistoryModule,
+  type ObservedHistoryEvent,
+  type ObservedHistoryPage,
+} from "./observed-history";
+export {
+  boundedBody,
+  signIntegrationRequest,
+  verifyIntegrationRequest,
+} from "./integration-auth";
+
+function isEditableDraft(item: StoredPost) {
+  return (
+    item.status === "New" && !item.published && item.draftEditable !== false
+  );
+}
+export {
+  createPostOwnership,
+  createMyFeedbackModule,
+  type MyFeedbackFilter,
+  type MyFeedbackItem,
+  type MyFeedbackPage,
+} from "./ownership";

package/template/src/feedbax/feedback/integration-auth.ts

@@ -0,0 +1,138 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+export function integrationSecret(
+  master: string,
+  installationId: string,
+  direction: "portal" | "service",
+  version: number,
+) {
+  if (master.length < 32)
+    throw new Error(
+      "Integration signing secret must have at least 32 characters.",
+    );
+  return createHmac("sha256", master)
+    .update(
+      JSON.stringify([
+        "feedbax-integration-v1",
+        installationId,
+        direction,
+        version,
+      ]),
+    )
+    .digest("base64url");
+}
+
+export function signIntegrationRequest(input: {
+  url: string;
+  installationId: string;
+  secret: string;
+  body?: string;
+  method?: string;
+  now?: number;
+  nonce?: string;
+}) {
+  const method = input.method ?? "POST";
+  const time = String(Math.floor((input.now ?? Date.now()) / 1000));
+  const nonce = input.nonce ?? randomUUID();
+  const body = input.body ?? "";
+  const signature = mac(
+    input.secret,
+    method,
+    input.url,
+    input.installationId,
+    time,
+    nonce,
+    body,
+  );
+  return new Request(input.url, {
+    method,
+    redirect: "manual",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Feedbax-Installation": input.installationId,
+      "X-Feedbax-Time": time,
+      "X-Feedbax-Nonce": nonce,
+      "X-Feedbax-Signature": signature,
+    },
+    ...(method === "GET" ? {} : { body }),
+  });
+}
+
+export function verifyIntegrationRequest(
+  request: Request,
+  body: string,
+  secret: string,
+  now = Date.now(),
+) {
+  const installationId = request.headers.get("X-Feedbax-Installation") ?? "";
+  const time = request.headers.get("X-Feedbax-Time") ?? "";
+  const nonce = request.headers.get("X-Feedbax-Nonce") ?? "";
+  const signature = request.headers.get("X-Feedbax-Signature") ?? "";
+  if (
+    secret.length < 32 ||
+    !/^[A-Za-z0-9_-]{1,128}$/.test(installationId) ||
+    !/^\d{10}$/.test(time) ||
+    Math.abs(now - Number(time) * 1000) > 300_000 ||
+    !/^[A-Za-z0-9_-]{16,128}$/.test(nonce)
+  )
+    return false;
+  return equalSignature(
+    signature,
+    mac(secret, request.method, request.url, installationId, time, nonce, body),
+  );
+}
+
+export function equalSignature(actual: string, expected: string) {
+  const a = Buffer.from(actual);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function mac(
+  secret: string,
+  method: string,
+  url: string,
+  installation: string,
+  time: string,
+  nonce: string,
+  body: string,
+) {
+  return createHmac("sha256", secret)
+    .update(
+      JSON.stringify([
+        "feedbax-integration-v1",
+        method,
+        url,
+        installation,
+        time,
+        nonce,
+        body,
+      ]),
+    )
+    .digest("hex");
+}
+
+export async function boundedBody(request: Request, maximum: number) {
+  if (Number(request.headers.get("Content-Length")) > maximum)
+    throw new Error("Request body limit exceeded.");
+  const reader = request.body?.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  if (reader)
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maximum) {
+        await reader.cancel();
+        throw new Error("Request body limit exceeded.");
+      }
+      chunks.push(value);
+    }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}

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

@@ -1,44 +1,11 @@
-import type { CommentAuthor } from "./index";
+import type { CommentStorage, StoredComment } from "./comment-storage";
+export type { CommentStorage, StoredComment } from "./comment-storage";
 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,

package/template/src/feedbax/feedback/notion-image-review.ts

@@ -0,0 +1,55 @@
+import { requestNotion, type NotionRetryOptions } from "./notion-request";
+import type { ImageAttachment } from "./images";
+/** Private page-body links let Team Members review drafts without a second dashboard. */
+export function createNotionImageReviewWriter(options: {
+  token: string;
+  reviewUrl(id: string): Promise<string>;
+  request?: typeof fetch;
+  retry?: NotionRetryOptions;
+}) {
+  return async (postId: string, images: ImageAttachment[]) => {
+    const children = await Promise.all(
+      images.map(async (image) => ({
+        object: "block",
+        type: "paragraph",
+        paragraph: {
+          rich_text: [
+            {
+              type: "text",
+              text: {
+                content: "Review Participant image",
+                link: { url: await options.reviewUrl(image.id) },
+              },
+            },
+          ],
+        },
+      })),
+    );
+    const response = await requestNotion(
+      `https://api.notion.com/v1/blocks/${encodeURIComponent(postId)}/children`,
+      {
+        method: "PATCH",
+        headers: {
+          Authorization: `Bearer ${options.token}`,
+          "Notion-Version": "2025-09-03",
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ children }),
+      },
+      {
+        operation: "create",
+        retry: options.retry,
+        request: (input, init) =>
+          (options.request ?? fetch)(input, {
+            ...init,
+            signal: AbortSignal.timeout(10000),
+          }),
+      },
+    );
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error("Image review links could not be saved in Notion.");
+    }
+    await response.body?.cancel();
+  };
+}