create-feedbax 0.1.0 → 0.2.1

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

@@ -0,0 +1,6 @@
+import { CreatePostOverlay } from "./create-post-overlay";
+import { portalFeedbackMutations } from "./routed-post-creation-form";
+
+export function LazyCreatePostOverlay() {
+  return <CreatePostOverlay mutations={portalFeedbackMutations} />;
+}

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

@@ -0,0 +1,21 @@
+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) => (
+        <Suspense fallback={<PublicPostDetailSkeleton display="overlay" />}>
+          <OverlayPostDetail key={slug} slug={slug} />
+        </Suspense>
+      )}
+    />
+  );
+}

package/template/src/masked-post-link.tsx

@@ -0,0 +1,27 @@
+import { Link } from "@tanstack/react-router";
+import type { AnchorHTMLAttributes } from "react";
+
+export function PostLink({
+  slug,
+  contextual = false,
+  ...props
+}: AnchorHTMLAttributes<HTMLAnchorElement> & {
+  slug: string;
+  contextual?: boolean;
+}) {
+  if (!contextual) {
+    return <a {...props} href={`/p/${encodeURIComponent(slug)}`} />;
+  }
+  return (
+    <Link
+      {...props}
+      to="."
+      state={{ postDetailOverlay: { slug } }}
+      mask={{
+        to: "/p/$slug",
+        params: { slug },
+        unmaskOnReload: true,
+      }}
+    />
+  );
+}

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

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+
+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 {
+  getPublicPost,
+  getPublicPostComments,
+} from "./public-post-server-function";
+import { saveDeviceProfile } from "./browser-post-state";
+
+vi.mock("./public-post-server-function", () => ({
+  getPublicPost: vi.fn(),
+  getPublicPostComments: vi.fn().mockResolvedValue({ items: [] }),
+}));
+vi.mock("./authorized-draft-post", () => ({
+  AuthorizedDraftPost: () => <p>Draft fallback</p>,
+}));
+
+beforeEach(() => {
+  saveDeviceProfile(localStorage, {
+    name: "Ari",
+    email: "ari@example.com",
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  localStorage.clear();
+  vi.clearAllMocks();
+});
+
+it("shows loading instead of stale content when the requested slug changes", async () => {
+  let resolveSecond!: (post: typeof firstPost) => void;
+  vi.mocked(getPublicPost)
+    .mockResolvedValueOnce(firstPost)
+    .mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolveSecond = resolve;
+      }),
+    );
+
+  const view = render(<OverlayPostDetail slug="first-post" />);
+  expect(
+    await screen.findByRole("heading", { name: "First Post" }),
+  ).toBeTruthy();
+
+  view.rerender(<OverlayPostDetail slug="second-post" />);
+  expect(
+    screen
+      .getByRole("main", { name: "Loading Post details" })
+      .getAttribute("aria-busy"),
+  ).toBe("true");
+  expect(screen.queryByRole("heading", { name: "First Post" })).toBeNull();
+
+  resolveSecond({ ...firstPost, slug: "second-post", title: "Second Post" });
+  expect(
+    await screen.findByRole("heading", { name: "Second Post" }),
+  ).toBeTruthy();
+});
+
+it("shows Post details without the redundant full-page toolbar", async () => {
+  vi.mocked(getPublicPost).mockResolvedValue(firstPost);
+  vi.mocked(getPublicPostComments).mockResolvedValue({
+    items: [
+      {
+        id: "discussion-1",
+        comments: [
+          {
+            id: "comment-1",
+            body: "Visible in the dialog",
+            author: { kind: "participant", displayName: "Ari" },
+            createdAt: new Date("2026-08-25T01:00:00.000Z"),
+          },
+        ],
+      },
+    ],
+  });
+
+  render(<OverlayPostDetail slug="first-post" />);
+
+  expect(
+    await screen.findByRole("heading", { name: "First Post" }),
+  ).toBeTruthy();
+  expect(screen.queryByRole("link", { name: "Open full page" })).toBeNull();
+  expect(screen.getByRole("complementary", { name: "Details" })).toBeTruthy();
+  expect(
+    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("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"),
+  );
+
+  render(<OverlayPostDetail slug="first-post" />);
+
+  expect(
+    await screen.findByRole("heading", { name: "First Post" }),
+  ).toBeTruthy();
+  expect(
+    await screen.findByRole("form", { name: "Comment composer" }),
+  ).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();
+});
+
+const firstPost = {
+  slug: "first-post",
+  title: "First Post",
+  description: "First description",
+  type: "Feature Request" as const,
+  status: "New" as const,
+  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

@@ -0,0 +1,43 @@
+import { useQuery } from "@tanstack/react-query";
+
+import {
+  getPublicPost,
+  getPublicPostComments,
+} from "./public-post-server-function";
+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";
+
+const loadComments = (slug: string, cursor?: string) =>
+  getPublicPostComments({ data: { slug, ...(cursor ? { cursor } : {}) } });
+
+export function OverlayPostDetail({ slug }: { slug: string }) {
+  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;
+
+  return (
+    <div className="overlay-post-detail">
+      {query.isPending ? (
+        <PublicPostDetailSkeleton display="overlay" />
+      ) : post ? (
+        <PostDetailContent
+          post={post}
+          display="overlay"
+          loadComments={loadComments}
+          submitComment={submitPublicComment}
+          mutateComment={mutatePublicComment}
+        />
+      ) : (
+        <AuthorizedDraftPost slug={slug} />
+      )}
+    </div>
+  );
+}

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,
+    });
+}