create-feedbax 0.2.0 → 0.2.1

package/template/src/lazy-post-detail-overlay.tsx

@@ -1,10 +1,21 @@
-import { OverlayPostDetail } from "./overlay-post-detail";
+import { lazy, Suspense } from "react";
 import { PostDetailOverlay } from "./post-detail-overlay";
+import { PublicPostDetailSkeleton } from "./public-post-detail-skeleton";
+
+const OverlayPostDetail = lazy(() =>
+  import("./overlay-post-detail").then((module) => ({
+    default: module.OverlayPostDetail,
+  })),
+);
 
 export function LazyPostDetailOverlay() {
   return (
     <PostDetailOverlay
-      renderDetail={(slug) => <OverlayPostDetail slug={slug} />}
+      renderDetail={(slug) => (
+        <Suspense fallback={<PublicPostDetailSkeleton display="overlay" />}>
+          <OverlayPostDetail key={slug} slug={slug} />
+        </Suspense>
+      )}
     />
   );
 }

package/template/src/overlay-post-detail.test.tsx

@@ -1,7 +1,15 @@
 // @vitest-environment jsdom
 
-import { cleanup, render, screen, within } from "@testing-library/react";
+import {
+  cleanup,
+  fireEvent,
+  render as renderView,
+  screen,
+  within,
+} from "@testing-library/react";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
 
 import { OverlayPostDetail } from "./overlay-post-detail";
 import {
@@ -60,7 +68,7 @@ it("shows loading instead of stale content when the requested slug changes", asy
   ).toBeTruthy();
 });
 
-it("shows the designed Post detail with a canonical full-page link", async () => {
+it("shows Post details without the redundant full-page toolbar", async () => {
   vi.mocked(getPublicPost).mockResolvedValue(firstPost);
   vi.mocked(getPublicPostComments).mockResolvedValue({
     items: [
@@ -83,25 +91,50 @@ it("shows the designed Post detail with a canonical full-page link", async () =>
   expect(
     await screen.findByRole("heading", { name: "First Post" }),
   ).toBeTruthy();
-  expect(
-    screen.getByRole("link", { name: "Open full page" }).getAttribute("href"),
-  ).toBe("/p/first-post");
+  expect(screen.queryByRole("link", { name: "Open full page" })).toBeNull();
   expect(screen.getByRole("complementary", { name: "Details" })).toBeTruthy();
   expect(
-    within(screen.getByRole("region", { name: "Comments" })).getByText(
+    await within(screen.getByRole("region", { name: "Comments" })).findByText(
       "Visible in the dialog",
     ),
   ).toBeTruthy();
   expect(
     await screen.findByRole("form", { name: "Comment composer" }),
   ).toBeTruthy();
+  const composer = screen.getByRole("form", { name: "Comment composer" });
+  const threads = screen.getByRole("region", { name: "Comment threads" });
+  expect(
+    composer.compareDocumentPosition(threads) &
+      Node.DOCUMENT_POSITION_FOLLOWING,
+  ).toBeTruthy();
+  expect(
+    within(threads).queryByRole("form", { name: "Comment composer" }),
+  ).toBeNull();
   expect(getPublicPostComments).toHaveBeenCalledWith({
     data: { slug: "first-post" },
   });
   expect(screen.queryByRole("link", { name: "Back to Feedback" })).toBeNull();
 });
 
-it("keeps the Post and Comment composer available when Comment loading fails", async () => {
+it("shows the Post while Comments are still loading", async () => {
+  vi.mocked(getPublicPost).mockResolvedValue(firstPost);
+  let finish!: (page: { items: [] }) => void;
+  vi.mocked(getPublicPostComments).mockReturnValue(
+    new Promise((resolve) => {
+      finish = resolve;
+    }),
+  );
+  render(<OverlayPostDetail slug="first-post" />);
+  expect(
+    await screen.findByRole("heading", { name: "First Post" }),
+  ).toBeTruthy();
+  expect(screen.getByRole("status", { name: "Loading Comments" })).toBeTruthy();
+  expect(screen.queryByText("No comments yet")).toBeNull();
+  finish({ items: [] });
+  expect(await screen.findByText("No comments yet")).toBeTruthy();
+});
+
+it("keeps the Post available and retries a failed Comment load", async () => {
   vi.mocked(getPublicPost).mockResolvedValue(firstPost);
   vi.mocked(getPublicPostComments).mockRejectedValue(
     new Error("Comments temporarily unavailable"),
@@ -115,7 +148,14 @@ it("keeps the Post and Comment composer available when Comment loading fails", a
   expect(
     await screen.findByRole("form", { name: "Comment composer" }),
   ).toBeTruthy();
-  expect(screen.getByText("No comments yet")).toBeTruthy();
+  expect(await screen.findByRole("alert")).toHaveProperty(
+    "textContent",
+    "Comments could not be loaded.",
+  );
+  expect(screen.queryByText("No comments yet")).toBeNull();
+  vi.mocked(getPublicPostComments).mockResolvedValue({ items: [] });
+  fireEvent.click(screen.getByRole("button", { name: "Retry Comments" }));
+  expect(await screen.findByText("No comments yet")).toBeTruthy();
   expect(screen.queryByText("Draft fallback")).toBeNull();
 });
 
@@ -128,3 +168,14 @@ const firstPost = {
   createdAt: new Date("2026-08-22T10:00:00.000Z"),
   updatedAt: new Date("2026-08-22T10:00:00.000Z"),
 };
+
+function render(ui: ReactNode) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return renderView(ui, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    ),
+  });
+}

package/template/src/overlay-post-detail.tsx

@@ -1,88 +1,39 @@
-import { useEffect, useState } from "react";
-import type { CommentThreadPage, PublicPost } from "@feedbax/feedback";
-import { ExternalLink } from "lucide-react";
+import { useQuery } from "@tanstack/react-query";
 
 import {
   getPublicPost,
   getPublicPostComments,
 } from "./public-post-server-function";
-import {
-  PublicPostDetail,
-  PublicPostDetailSkeleton,
-} from "./public-post-detail";
+import { PublicPostDetailSkeleton } from "./public-post-detail-skeleton";
+import { publicPostQuery } from "./post-detail-query";
+import { PostDetailContent } from "./post-detail-content";
 import { AuthorizedDraftPost } from "./authorized-draft-post";
 import { mutatePublicComment, submitPublicComment } from "./public-post-route";
-import { mergeCommentThreads } from "./comment-thread-page";
 
-type OverlayDetail = {
-  post: PublicPost | null;
-  comments: CommentThreadPage;
-};
+const loadComments = (slug: string, cursor?: string) =>
+  getPublicPostComments({ data: { slug, ...(cursor ? { cursor } : {}) } });
 
 export function OverlayPostDetail({ slug }: { slug: string }) {
-  const [detail, setDetail] = useState<OverlayDetail>();
-  useEffect(() => {
-    let current = true;
-    setDetail(undefined);
-    getPublicPost({ data: { slug } })
-      .then(async (post) => ({
-        post: post ?? null,
-        comments: post
-          ? await getPublicPostComments({ data: { slug } }).catch(() => ({
-              items: [],
-            }))
-          : { items: [] },
-      }))
-      .then((value) => current && setDetail(value))
-      .catch(
-        () => current && setDetail({ post: null, comments: { items: [] } }),
-      );
-    return () => {
-      current = false;
-    };
-  }, [slug]);
+  return <OverlayPost key={slug} slug={slug} />;
+}
+
+function OverlayPost({ slug }: { slug: string }) {
+  const query = useQuery(
+    publicPostQuery(slug, (value) => getPublicPost({ data: { slug: value } })),
+  );
+  const post = query.data;
 
-  if (detail === undefined) return <PublicPostDetailSkeleton />;
   return (
     <div className="overlay-post-detail">
-      <a
-        className="post-full-page-link"
-        href={`/p/${encodeURIComponent(slug)}`}
-      >
-        Open full page <ExternalLink aria-hidden="true" />
-      </a>
-      {detail.post ? (
-        <PublicPostDetail
-          post={detail.post}
+      {query.isPending ? (
+        <PublicPostDetailSkeleton display="overlay" />
+      ) : post ? (
+        <PostDetailContent
+          post={post}
           display="overlay"
-          comments={detail.comments}
+          loadComments={loadComments}
           submitComment={submitPublicComment}
           mutateComment={mutatePublicComment}
-          loadMore={
-            detail.comments.nextCursor
-              ? async () => {
-                  const next = await getPublicPostComments({
-                    data: { slug, cursor: detail.comments.nextCursor },
-                  });
-                  setDetail((current) =>
-                    current
-                      ? {
-                          ...current,
-                          comments: {
-                            items: mergeCommentThreads(
-                              current.comments.items,
-                              next.items,
-                            ),
-                            ...(next.nextCursor
-                              ? { nextCursor: next.nextCursor }
-                              : {}),
-                          },
-                        }
-                      : current,
-                  );
-                }
-              : undefined
-          }
         />
       ) : (
         <AuthorizedDraftPost slug={slug} />

package/template/src/participation-client.ts

@@ -0,0 +1,63 @@
+import { queryOptions } from "@tanstack/react-query";
+import type { ParticipantNotification, FollowState } from "@feedbax/feedback";
+export interface NotificationPage {
+  items: ParticipantNotification[];
+  unreadCount: number;
+  nextCursor?: string;
+}
+export interface EmailPreferences {
+  emailAvailable: boolean;
+  emailEnabled: boolean;
+}
+export async function participationRequest<T>(
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  const response = await fetch(`/internal/connected/${path}`, {
+    cache: "no-store",
+    ...(body === undefined
+      ? {}
+      : {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+        }),
+  });
+  const value = await response.json();
+  if (!response.ok)
+    throw new Error(
+      value && typeof value === "object" && "error" in value
+        ? String(value.error)
+        : "Updates are temporarily unavailable.",
+    );
+  return value as T;
+}
+export const followQuery = (slug: string) =>
+  queryOptions({
+    queryKey: ["participant-follow", slug],
+    queryFn: () =>
+      participationRequest<FollowState>(
+        `follow?slug=${encodeURIComponent(slug)}`,
+      ),
+    staleTime: 0,
+    retry: false,
+    refetchInterval: (query) =>
+      query.state.data?.initializing ? 15000 : false,
+  });
+export const preferencesQuery = () =>
+  queryOptions({
+    queryKey: ["participant-email-preferences"],
+    queryFn: () => participationRequest<EmailPreferences>("preferences"),
+    staleTime: 0,
+    retry: false,
+  });
+export const notificationQuery = {
+  queryKey: ["participant-notifications"],
+  initialPageParam: undefined as string | undefined,
+  queryFn: ({ pageParam }: { pageParam: string | undefined }) =>
+    participationRequest<NotificationPage>(
+      `notifications${pageParam ? `?cursor=${encodeURIComponent(pageParam)}` : ""}`,
+    ),
+  getNextPageParam: (last: NotificationPage) => last.nextCursor,
+  retry: false as const,
+};

package/template/src/participation-runtime.test.ts

@@ -0,0 +1,35 @@
+import { expect, it } from "vitest";
+import { createParticipationRequestHandler } from "./participation-runtime";
+
+it("keeps social routes private and rejects cross-origin mutations before touching participation", async () => {
+  let read = false;
+  const handler = createParticipationRequestHandler({
+    siteUrl: "https://feedback.example.com",
+    enabled: true,
+    getParticipant: async () => undefined,
+    getModule: () => {
+      read = true;
+      throw new Error();
+    },
+    rateLimit: async () => true,
+  });
+  const privateRead = await handler(
+    new Request(
+      "https://feedback.example.com/internal/connected/notifications",
+    ),
+  );
+  expect(privateRead?.status).toBe(401);
+  expect(privateRead?.headers.get("Cache-Control")).toBe("no-store");
+  const mutation = await handler(
+    new Request("https://feedback.example.com/internal/connected/follow", {
+      method: "POST",
+      headers: { Origin: "https://evil.example.com" },
+      body: JSON.stringify({ slug: "public", following: true }),
+    }),
+  );
+  expect(mutation?.status).toBe(403);
+  expect(read).toBe(false);
+  expect(
+    await handler(new Request("https://feedback.example.com/roadmap")),
+  ).toBeUndefined();
+});

package/template/src/participation-runtime.ts

@@ -0,0 +1,255 @@
+import {
+  createEmailSender,
+  createParticipationModule,
+  type VerifiedParticipant,
+} from "@feedbax/feedback";
+import { env } from "cloudflare:workers";
+import feedbax from "./feedbax";
+import {
+  configuredImages,
+  createConfiguredNotionFeedbackModule,
+  getConnectedStore,
+} from "./feedback-runtime";
+import {
+  readSessionToken,
+  sameOrigin,
+  sessionHash,
+} from "./connected-identity";
+
+type ParticipationModule = ReturnType<typeof createParticipationModule>;
+const paths = new Set([
+  "follow",
+  "notifications",
+  "preferences",
+  "unsubscribe",
+]);
+export function createParticipationRequestHandler(options: {
+  siteUrl: string;
+  enabled: boolean;
+  getParticipant(request: Request): Promise<VerifiedParticipant | undefined>;
+  getModule(participant?: VerifiedParticipant): ParticipationModule;
+  rateLimit(request: Request): Promise<boolean>;
+}) {
+  return async (request: Request): Promise<Response | undefined> => {
+    const url = new URL(request.url);
+    const route = url.pathname.replace("/internal/connected/", "");
+    if (!url.pathname.startsWith("/internal/connected/") || !paths.has(route))
+      return;
+    const json = (body: unknown, status = 200) =>
+      Response.json(body, { status, headers: { "Cache-Control": "no-store" } });
+    if (!options.enabled) return json({ error: "Not found." }, 404);
+    if (!["GET", "POST"].includes(request.method))
+      return json({ error: "Method not allowed." }, 405);
+    if (
+      route !== "unsubscribe" &&
+      request.method !== "GET" &&
+      !sameOrigin(request, options.siteUrl)
+    )
+      return json({ error: "Request origin is invalid." }, 403);
+    try {
+      if (route === "unsubscribe") {
+        const token = url.searchParams.get("token") ?? "";
+        if (!/^[a-f0-9]{32}\.[A-Za-z0-9_-]{43}$/.test(token))
+          return json({ error: "Invalid unsubscribe link." }, 400);
+        if (request.method === "GET")
+          return new Response(null, {
+            status: 303,
+            headers: {
+              Location: `/email-preferences?token=${encodeURIComponent(token)}`,
+              "Cache-Control": "no-store",
+              "Referrer-Policy": "no-referrer",
+            },
+          });
+        if (!(await options.rateLimit(request)))
+          return json({ error: "Try again shortly." }, 429);
+        await options.getModule().unsubscribe(token);
+        return new Response(
+          "Email notifications are turned off. You can turn them on again in Feedbax.",
+          {
+            headers: {
+              "Content-Type": "text/plain; charset=utf-8",
+              "Cache-Control": "no-store",
+            },
+          },
+        );
+      }
+      const participant = await options.getParticipant(request);
+      if (!participant)
+        return json(
+          {
+            error: "Sign in through the product to continue.",
+            code: "sign_in_required",
+          },
+          401,
+        );
+      const module = options.getModule(participant);
+      if (request.method === "GET") {
+        if (route === "follow")
+          return json(
+            await module.followState(url.searchParams.get("slug") ?? ""),
+          );
+        if (route === "notifications")
+          return json(
+            await module.inbox(url.searchParams.get("cursor") ?? undefined),
+          );
+        if (route === "preferences") return json(await module.preferences());
+      }
+      if (!(await options.rateLimit(request)))
+        return json({ error: "Too many changes. Try again shortly." }, 429);
+      if (Number(request.headers.get("Content-Length")) > 4096)
+        return json({ error: "Request is too large." }, 413);
+      const reader = request.body?.getReader();
+      const chunks: Uint8Array[] = [];
+      let length = 0;
+      if (reader)
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          length += value.byteLength;
+          if (length > 4096) {
+            await reader.cancel();
+            return json({ error: "Request is too large." }, 413);
+          }
+          chunks.push(value);
+        }
+      const bytes = new Uint8Array(length);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      const text = new TextDecoder().decode(bytes);
+      if (text.length > 4096)
+        return json({ error: "Request is too large." }, 413);
+      let body: Record<string, unknown>;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        return json({ error: "Invalid request." }, 400);
+      }
+      if (!body || typeof body !== "object" || Array.isArray(body))
+        return json({ error: "Invalid request." }, 400);
+      if (
+        route === "follow" &&
+        typeof body.slug === "string" &&
+        body.slug.length <= 512 &&
+        typeof body.following === "boolean"
+      )
+        return json(await module.follow(body.slug, body.following));
+      if (
+        route === "notifications" &&
+        (body.id === undefined ||
+          (typeof body.id === "string" && /^[a-f0-9]{32}$/.test(body.id)))
+      ) {
+        await module.markRead(body.id as string | undefined);
+        return json({ updated: true });
+      }
+      if (route === "preferences" && typeof body.emailEnabled === "boolean") {
+        await module.setEmailPreference(body.emailEnabled);
+        return json(await module.preferences());
+      }
+      return json({ error: "Invalid request." }, 400);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "";
+      const known = [
+        "Post is unavailable.",
+        "Invalid notification cursor.",
+        "Invalid unsubscribe link.",
+        "Email notifications require a verified application email and a configured sender.",
+      ];
+      return json(
+        {
+          error: known.includes(message)
+            ? message
+            : "Updates are temporarily unavailable. Try again.",
+        },
+        message === "Post is unavailable."
+          ? 404
+          : known.includes(message)
+            ? 400
+            : 503,
+      );
+    }
+  };
+}
+
+export function configuredParticipation(participant?: VerifiedParticipant) {
+  return createConfiguredParticipation(
+    createConfiguredNotionFeedbackModule(),
+    participant,
+  );
+}
+
+function createConfiguredParticipation(
+  feedback: import("@feedbax/feedback").FeedbackModule,
+  participant?: VerifiedParticipant,
+) {
+  if (!feedbax.connected || !env.FEEDBAX_DB)
+    throw new Error("Connected database is missing.");
+  const config = feedbax.connected.email;
+  let email: Parameters<typeof createParticipationModule>[0]["email"];
+  if (config) {
+    const sender =
+      config.provider === "cloudflare"
+        ? createEmailSender({
+            provider: "cloudflare",
+            binding: requireBinding(env.FEEDBAX_EMAIL),
+          })
+        : config.provider === "resend"
+          ? createEmailSender({
+              provider: "resend",
+              token: env.EMAIL_PROVIDER_SECRET ?? "",
+            })
+          : createEmailSender({
+              provider: "custom",
+              url: config.endpoint!,
+              token: env.EMAIL_PROVIDER_SECRET ?? "",
+            });
+    email = {
+      sender,
+      from: config.from,
+      siteUrl: feedbax.product.siteUrl!,
+      unsubscribeSecret: env.PARTICIPATION_SIGNING_SECRET ?? "",
+    };
+  }
+  return createParticipationModule({
+    database: env.FEEDBAX_DB,
+    feedback,
+    participant,
+    processing: feedbax.connected.processing ?? "small",
+    email,
+  });
+}
+const requireBinding = <T>(value: T | undefined): T => {
+  if (!value) throw new Error("Email binding is missing.");
+  return value;
+};
+export const handleParticipationRequest = createParticipationRequestHandler({
+  enabled: Boolean(feedbax.connected),
+  siteUrl: feedbax.product.siteUrl ?? "https://not-configured.invalid",
+  getParticipant: async (request) => {
+    const token = readSessionToken(request);
+    return token ? getConnectedStore().session(sessionHash(token)) : undefined;
+  },
+  getModule: configuredParticipation,
+  rateLimit: async (request) =>
+    (
+      await env.PORTAL_SUBMISSIONS_RATE_LIMITER.limit({
+        key: `updates:${request.headers.get("CF-Connecting-IP") ?? "unknown"}`,
+      })
+    ).success,
+});
+export async function synchronizeConnectedUpdates() {
+  if (!feedbax.connected) return;
+  const content = createConfiguredNotionFeedbackModule();
+  const module = createConfiguredParticipation(content);
+  const observation = await module.synchronize();
+  const email = await module.deliverEmails();
+  if (feedbax.connected.images) await configuredImages(content).cleanup();
+  // Counts only: never log identities, addresses, provider responses, or message bodies.
+  if (observation.failed || email.failed)
+    console.warn("Connected update processing will retry", {
+      observations: observation.failed,
+      deliveries: email.failed,
+    });
+}

package/template/src/portal-comments.ts

@@ -26,6 +26,7 @@ export interface PortalCommentResult {
 const commentCapabilityLifetime = 15 * 60 * 1_000;
 
 export interface PortalCommentRequest {
+  imageIds?: string[];
   slug: string;
   body: string;
   displayName: string;
@@ -36,6 +37,7 @@ export interface PortalCommentRequest {
 }
 
 export function createPortalCommentHandler(options: {
+  verifiedParticipant?: { displayName: string };
   feedback: Pick<FeedbackModule, "createComment" | "replyToCommentThread">;
   commentsEnabled: boolean;
   rateLimiter: PortalSubmissionRateLimiter;
@@ -50,7 +52,7 @@ export function createPortalCommentHandler(options: {
         "Comments are disabled for this Installation.",
         "comments_disabled",
       );
-    const value = validateCommentInput(input);
+    const value = validateCommentInput(input, options.verifiedParticipant);
     const { success } = await options.rateLimiter.limit({
       key: `comment:${options.rateLimitKey}`,
     });
@@ -89,6 +91,7 @@ export function createPortalCommentHandler(options: {
     }
 
     const command = {
+      ...(value.imageIds ? { imageIds: value.imageIds } : {}),
       slug: value.slug,
       body: value.body,
       displayName: value.displayName,
@@ -338,10 +341,16 @@ export function createPortalCommentMutationRequestHandler(
   };
 }
 
-function validateCommentInput(input: unknown): PortalCommentRequest {
+function validateCommentInput(
+  input: unknown,
+  participant?: { displayName: string },
+): PortalCommentRequest {
   if (!input || typeof input !== "object" || Array.isArray(input))
     throw invalidCommentRequest();
-  const value = input as Record<string, unknown>;
+  const value: Record<string, unknown> = {
+    ...(input as Record<string, unknown>),
+    ...(participant ? { displayName: participant.displayName } : {}),
+  };
   if (typeof value.slug !== "string" || !value.slug.trim())
     throw invalidCommentRequest();
   if (typeof value.body !== "string" || !value.body.trim())
@@ -354,16 +363,26 @@ function validateCommentInput(input: unknown): PortalCommentRequest {
       "Device Profile display name is required before commenting.",
       "profile_required",
     );
-  if (!isValidCommentEmail(value.email))
+  if (!participant && !isValidCommentEmail(value.email))
     throw new ActionablePortalFailure(
       "A Device Profile with a valid email is required before commenting.",
       "profile_required",
     );
+  if (
+    value.imageIds !== undefined &&
+    (!Array.isArray(value.imageIds) ||
+      value.imageIds.length > 4 ||
+      value.imageIds.some(
+        (id) => typeof id !== "string" || !/^[-a-f0-9]{36}$/.test(id),
+      ))
+  )
+    throw invalidCommentRequest();
   return {
+    ...(value.imageIds ? { imageIds: value.imageIds as string[] } : {}),
     slug: value.slug.trim(),
     body: value.body.trim(),
     displayName: value.displayName.trim(),
-    email: value.email.trim(),
+    email: typeof value.email === "string" ? value.email.trim() : "",
     ...(typeof value.discussionId === "string" && value.discussionId
       ? { discussionId: value.discussionId }
       : {}),