create-feedbax 0.1.0 → 0.2.0

package/template/src/portal-voting.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPortalVoteHandler } from "./portal-voting";
+import { createFeedbackModule } from "@feedbax/feedback";
+
+function publishedFeedback() {
+  const now = new Date("2026-08-25T00:00:00.000Z");
+  return createFeedbackModule({
+    initialItems: [
+      {
+        id: "post",
+        slug: "post",
+        title: "Post",
+        description: "Visible.",
+        type: "Feature Request",
+        status: "Planned",
+        published: true,
+        voteCount: 2,
+        createdAt: now,
+        updatedAt: now,
+      },
+    ],
+  });
+}
+
+describe("portal Vote handler", () => {
+  it("rate-limits Vote operations and returns an actionable error", async () => {
+    const feedback = publishedFeedback();
+    const vote = createPortalVoteHandler({
+      feedback,
+      votingEnabled: true,
+      rateLimiter: { limit: vi.fn().mockResolvedValue({ success: false }) },
+      rateLimitKey: "participant-ip",
+    });
+
+    await expect(vote({ slug: "post", intention: "add" })).rejects.toThrow(
+      "Vote rate limit exceeded",
+    );
+    await expect(feedback.getPublicPost("post")).resolves.toMatchObject({
+      voteCount: 2,
+    });
+  });
+
+  it("issues a thirty-minute Participation Pass after first verification and accepts reuse", async () => {
+    let now = 1_000;
+    const verify = vi.fn().mockResolvedValue(true);
+    const options = {
+      feedback: publishedFeedback(),
+      votingEnabled: true,
+      rateLimiter: { limit: vi.fn().mockResolvedValue({ success: true }) },
+      rateLimitKey: "participant-ip",
+      turnstileVerifier: { verify },
+      participationSigningSecret:
+        "a-high-entropy-secret-with-at-least-32-characters",
+      now: () => now,
+    };
+    const vote = createPortalVoteHandler(options);
+    const first = await vote({
+      slug: "post",
+      intention: "add",
+      turnstileToken: "verified",
+    });
+    now += 29 * 60 * 1_000;
+    await vote({
+      slug: "post",
+      intention: "remove",
+      participationPass: first.participationPass,
+    });
+
+    expect(first.participationPass).toEqual(expect.any(String));
+    expect(verify).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed for a tampered or expired Participation Pass", async () => {
+    let now = 1_000;
+    const vote = createPortalVoteHandler({
+      feedback: publishedFeedback(),
+      votingEnabled: true,
+      rateLimiter: { limit: vi.fn().mockResolvedValue({ success: true }) },
+      rateLimitKey: "participant-ip",
+      turnstileVerifier: { verify: vi.fn().mockResolvedValue(true) },
+      participationSigningSecret:
+        "a-high-entropy-secret-with-at-least-32-characters",
+      now: () => now,
+    });
+    const first = await vote({
+      slug: "post",
+      intention: "add",
+      turnstileToken: "verified",
+    });
+    now += 31 * 60 * 1_000;
+    await expect(
+      vote({
+        slug: "post",
+        intention: "remove",
+        participationPass: first.participationPass,
+      }),
+    ).rejects.toThrow("verification is required");
+    await expect(
+      vote({
+        slug: "post",
+        intention: "remove",
+        participationPass: `${first.participationPass}x`,
+      }),
+    ).rejects.toThrow("verification is required");
+  });
+});

package/template/src/portal-voting.ts

@@ -0,0 +1,149 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import type { FeedbackModule, VoteResult } from "@feedbax/feedback";
+import type { TurnstileVerifier } from "./cloudflare-turnstile";
+import type { PortalSubmissionRateLimiter } from "./portal-feedback-submission";
+import { ActionablePortalFailure } from "./safe-public-failure";
+
+const participationPassLifetime = 30 * 60 * 1_000;
+
+export interface PortalVoteResult extends VoteResult {
+  participationPass?: string;
+}
+
+export function createPortalVoteHandler(options: {
+  feedback: Pick<FeedbackModule, "changeVote">;
+  votingEnabled: boolean;
+  rateLimiter: PortalSubmissionRateLimiter;
+  rateLimitKey: string;
+  turnstileVerifier?: TurnstileVerifier;
+  participationSigningSecret?: string;
+  now?: () => number;
+}) {
+  return async (input: unknown): Promise<PortalVoteResult> => {
+    if (!options.votingEnabled)
+      throw new ActionablePortalFailure(
+        "Voting is disabled for this Installation.",
+        "voting_disabled",
+      );
+    const value = validateVoteInput(input);
+    const { success } = await options.rateLimiter.limit({
+      key: `vote:${options.rateLimitKey}`,
+    });
+    if (!success)
+      throw new ActionablePortalFailure(
+        "Vote rate limit exceeded. Try again shortly.",
+        "rate_limited",
+      );
+
+    let participationPass: string | undefined;
+    if (options.turnstileVerifier) {
+      const secret = requiredParticipationSigningSecret(
+        options.participationSigningSecret,
+      );
+      const now = options.now?.() ?? Date.now();
+      if (
+        !value.participationPass ||
+        !verifyParticipationPass(value.participationPass, secret, now)
+      ) {
+        if (!value.turnstileToken)
+          throw new ActionablePortalFailure(
+            "Vote verification is required.",
+            "verification_required",
+          );
+        const verified = await options.turnstileVerifier.verify({
+          token: value.turnstileToken,
+          remoteIp: options.rateLimitKey,
+        });
+        if (!verified)
+          throw new ActionablePortalFailure(
+            "Vote verification failed.",
+            "verification_failed",
+          );
+        participationPass = issueParticipationPass(secret, now);
+      }
+    }
+
+    const result = await options.feedback.changeVote(value);
+    return { ...result, ...(participationPass ? { participationPass } : {}) };
+  };
+}
+
+function validateVoteInput(input: unknown): {
+  slug: string;
+  intention: "add" | "remove";
+  turnstileToken?: string;
+  participationPass?: string;
+} {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new ActionablePortalFailure(
+      "Vote request is invalid.",
+      "invalid_request",
+    );
+  const value = input as Record<string, unknown>;
+  if (
+    typeof value.slug !== "string" ||
+    value.slug.length === 0 ||
+    (value.intention !== "add" && value.intention !== "remove")
+  )
+    throw new ActionablePortalFailure(
+      "Vote request is invalid.",
+      "invalid_request",
+    );
+  return {
+    slug: value.slug,
+    intention: value.intention,
+    ...(typeof value.turnstileToken === "string"
+      ? { turnstileToken: value.turnstileToken }
+      : {}),
+    ...(typeof value.participationPass === "string"
+      ? { participationPass: value.participationPass }
+      : {}),
+  };
+}
+
+export function requiredParticipationSigningSecret(secret?: string): string {
+  if (!secret || secret.length < 32)
+    throw new Error("Participation signing secret is missing or too short.");
+  return secret;
+}
+
+export function issueParticipationPass(secret: string, now: number): string {
+  const payload = Buffer.from(
+    JSON.stringify({ expiresAt: now + participationPassLifetime }),
+  ).toString("base64url");
+  return `${payload}.${sign(payload, secret)}`;
+}
+
+export function verifyParticipationPass(
+  pass: string,
+  secret: string,
+  now: number,
+): boolean {
+  const [payload, signature, extra] = pass.split(".");
+  if (!payload || !signature || extra) return false;
+  const expected = Buffer.from(sign(payload, secret));
+  const received = Buffer.from(signature);
+  if (
+    expected.length !== received.length ||
+    !timingSafeEqual(expected, received)
+  )
+    return false;
+  try {
+    const value: unknown = JSON.parse(
+      Buffer.from(payload, "base64url").toString("utf8"),
+    );
+    return Boolean(
+      value &&
+      typeof value === "object" &&
+      typeof Reflect.get(value, "expiresAt") === "number" &&
+      Reflect.get(value, "expiresAt") > now,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function sign(payload: string, secret: string): string {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}

package/template/src/post-badges.tsx

@@ -0,0 +1,27 @@
+import type { PostStatus, PostType } from "@feedbax/feedback";
+import { Badge } from "@feedbax/ui/components/badge";
+
+import {
+  postStatusPresentation,
+  postTypePresentation,
+} from "./post-presentation";
+
+export function PostTypeBadge({ type }: { type: PostType }) {
+  const { Icon } = postTypePresentation[type];
+  return (
+    <Badge variant="outline">
+      <Icon aria-hidden="true" />
+      {type}
+    </Badge>
+  );
+}
+
+export function PostStatusBadge({ status }: { status: PostStatus }) {
+  const { Icon } = postStatusPresentation[status];
+  return (
+    <Badge variant="outline" data-status={status}>
+      <Icon aria-hidden="true" />
+      {status}
+    </Badge>
+  );
+}

package/template/src/post-creation-flow.test.tsx

@@ -0,0 +1,230 @@
+// @vitest-environment jsdom
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from "@tanstack/react-router";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ComponentProps } from "react";
+
+import { PostCreationFlow } from "./post-creation-flow";
+import { authorizedDraftPostsQueryKey } from "./authorized-draft-query";
+import { readCapabilities } from "./browser-post-state";
+import { saveDeviceProfile } from "./browser-post-state";
+import { DeviceProfileProvider } from "./components/device-profile-provider";
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+});
+
+describe("routed Post creation", () => {
+  it("requests a complete Device Profile instead of exposing the Post form", async () => {
+    saveDeviceProfile(localStorage, { name: "Ama" });
+    const mutations = {
+      submitPost: vi.fn(),
+      editDraftPost: vi.fn(),
+      withdrawDraftPost: vi.fn(),
+    };
+    const history = createMemoryHistory({ initialEntries: ["/submit"] });
+    const router = createCreationRouter(history, mutations);
+
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>,
+    );
+
+    expect(await screen.findByText("Complete your profile")).toBeTruthy();
+    expect(screen.queryByLabelText("Title")).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Complete profile" }));
+    fireEvent.change(await screen.findByLabelText("Email"), {
+      target: { value: "ama@example.com" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Save profile" }));
+
+    expect(await screen.findByLabelText("Title")).toBeTruthy();
+  });
+
+  it("submits the Post Type selected from the three-card picker", async () => {
+    saveDeviceProfile(localStorage, {
+      name: "Ama",
+      email: "ama@example.com",
+    });
+    const created = {
+      id: "post-1",
+      slug: "keyboard-navigation",
+      title: "Keyboard navigation",
+      description: "Let Participants navigate without a pointer.",
+      type: "Bug Report" as const,
+      status: "New" as const,
+      published: false,
+      createdAt: new Date("2026-08-22T10:00:00.000Z"),
+      updatedAt: new Date("2026-08-22T10:00:00.000Z"),
+      browserCapability: "browser-capability" as never,
+    };
+    const mutations = {
+      submitPost: vi.fn().mockResolvedValue(created),
+      editDraftPost: vi.fn(),
+      withdrawDraftPost: vi.fn(),
+    };
+    const history = createMemoryHistory({ initialEntries: ["/submit"] });
+    const router = createCreationRouter(history, mutations);
+
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>,
+    );
+
+    const picker = await screen.findByRole("radiogroup", {
+      name: "Post Type",
+    });
+    expect(within(picker).getAllByRole("radio")).toHaveLength(3);
+    expect(
+      within(picker)
+        .getByRole("radio", { name: /Feature Request/ })
+        .getAttribute("aria-checked"),
+    ).toBe("true");
+
+    fireEvent.click(within(picker).getByRole("radio", { name: /Bug Report/ }));
+    fireEvent.change(screen.getByLabelText("Title"), {
+      target: { value: created.title },
+    });
+    fireEvent.change(screen.getByLabelText("Description"), {
+      target: { value: created.description },
+    });
+    fireEvent.submit(
+      screen.getByRole("button", { name: "Create Post" }).closest("form")!,
+    );
+
+    await waitFor(() =>
+      expect(mutations.submitPost).toHaveBeenCalledWith({
+        data: expect.objectContaining({ type: "Bug Report" }),
+      }),
+    );
+  });
+
+  it("retains authority, reconciles caches, and opens the authorized detail route", async () => {
+    saveDeviceProfile(localStorage, {
+      name: "Ama",
+      email: "ama@example.com",
+    });
+    const created = {
+      id: "post-1",
+      slug: "keyboard-navigation",
+      title: "Keyboard navigation",
+      description: "Let Participants navigate without a pointer.",
+      type: "Feature Request" as const,
+      status: "New" as const,
+      published: false,
+      createdAt: new Date("2026-08-22T10:00:00.000Z"),
+      updatedAt: new Date("2026-08-22T10:00:00.000Z"),
+      browserCapability: "browser-capability" as never,
+    };
+    const mutations = {
+      submitPost: vi.fn().mockResolvedValue(created),
+      editDraftPost: vi.fn(),
+      withdrawDraftPost: vi.fn(),
+    };
+    const queryClient = new QueryClient();
+    queryClient.setQueryData(["public-posts", { sort: "trending" }], {
+      pages: [],
+    });
+    const history = createMemoryHistory({ initialEntries: ["/submit"] });
+    const router = createCreationRouter(history, mutations);
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>,
+    );
+    expect(await screen.findByText("0 / 5,000 characters")).toBeTruthy();
+    fireEvent.submit(
+      screen.getByRole("button", { name: "Create Post" }).closest("form")!,
+    );
+    expect(await screen.findByText("Enter a title.")).toBeTruthy();
+    expect(await screen.findByText("Enter a description.")).toBeTruthy();
+    expect(screen.getByLabelText("Title").getAttribute("aria-invalid")).toBe(
+      "true",
+    );
+    expect(
+      screen.getByLabelText("Description").getAttribute("aria-invalid"),
+    ).toBe("true");
+    fireEvent.change(await screen.findByLabelText("Title"), {
+      target: { value: created.title },
+    });
+    fireEvent.change(screen.getByLabelText("Description"), {
+      target: { value: created.description },
+    });
+    expect(screen.getByText("44 / 5,000 characters")).toBeTruthy();
+    expect(
+      screen.getByText(/Draft access is stored only in this browser/),
+    ).toBeTruthy();
+    fireEvent.submit(
+      screen.getByRole("button", { name: "Create Post" }).closest("form")!,
+    );
+
+    expect(
+      await screen.findByRole("heading", { name: "keyboard-navigation" }),
+    ).toBeTruthy();
+    expect(history.location.pathname).toBe("/p/keyboard-navigation");
+    expect(window.localStorage.getItem("feedbax:post-capabilities")).toContain(
+      "browser-capability",
+    );
+    expect(
+      queryClient.getQueryData(
+        authorizedDraftPostsQueryKey(readCapabilities(localStorage)),
+      ),
+    ).toEqual([
+      expect.objectContaining({ id: "post-1", slug: "keyboard-navigation" }),
+    ]);
+    expect(
+      queryClient.getQueryState(["public-posts", { sort: "trending" }])
+        ?.isInvalidated,
+    ).toBe(true);
+  });
+});
+
+function createCreationRouter(
+  history: ReturnType<typeof createMemoryHistory>,
+  mutations: ComponentProps<typeof PostCreationFlow>["mutations"],
+) {
+  const root = createRootRoute({
+    component: () => (
+      <DeviceProfileProvider>
+        <Outlet />
+      </DeviceProfileProvider>
+    ),
+  });
+  const submit = createRoute({
+    getParentRoute: () => root,
+    path: "/submit",
+    component: () => <PostCreationFlow mutations={mutations} />,
+  });
+  const detail = createRoute({
+    getParentRoute: () => root,
+    path: "/p/$slug",
+    component: function Detail() {
+      const { slug } = detail.useParams();
+      return <h1>{slug}</h1>;
+    },
+  });
+  return createRouter({
+    history,
+    routeTree: root.addChildren([submit, detail]),
+  });
+}

package/template/src/post-creation-flow.tsx

@@ -0,0 +1,88 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { Skeleton } from "@feedbax/ui/components/skeleton";
+
+import {
+  PortalFeedbackForm,
+  type PortalFeedbackMutations,
+} from "./portal-feedback-form";
+import { authorizedDraftPostsQueryKey } from "./authorized-draft-query";
+import { readCapabilities } from "./browser-post-state";
+import {
+  DeviceProfilePrompt,
+  useDeviceProfile,
+} from "./components/device-profile-provider";
+
+export function PostCreationFlow({
+  display = "page",
+  onCancel,
+  mutations,
+}: {
+  display?: "page" | "overlay";
+  onCancel?: () => void;
+  mutations: PortalFeedbackMutations;
+}) {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const { completeProfile, ready } = useDeviceProfile();
+
+  if (!ready)
+    return (
+      <div className="profile-gate" aria-label="Loading profile" aria-busy />
+    );
+  if (!completeProfile) return <DeviceProfilePrompt purpose="post" />;
+
+  return (
+    <PortalFeedbackForm
+      display={display}
+      onCancel={onCancel}
+      mutations={mutations}
+      onCreated={async (post) => {
+        const draft = {
+          id: post.id,
+          slug: post.slug,
+          title: post.title,
+          description: post.description,
+          type: post.type,
+          status: post.status,
+          createdAt: post.createdAt,
+          updatedAt: post.updatedAt,
+        };
+        queryClient.setQueryData(
+          authorizedDraftPostsQueryKey(readCapabilities(localStorage)),
+          (current: (typeof draft)[] | undefined) => [
+            draft,
+            ...(current ?? []).filter((item) => item.id !== draft.id),
+          ],
+        );
+        await queryClient.invalidateQueries({ queryKey: ["public-posts"] });
+        await navigate({ to: "/p/$slug", params: { slug: post.slug } });
+      }}
+    />
+  );
+}
+
+export function PostCreationSkeleton() {
+  return (
+    <main
+      className="feedback-index submission-page"
+      aria-label="Loading Post creation"
+      aria-busy="true"
+    >
+      <section className="feedback-submit creation-skeleton" aria-hidden="true">
+        <div className="feedback-submit-copy">
+          <Skeleton className="creation-skeleton-eyebrow" />
+          <Skeleton className="creation-skeleton-heading" />
+          <Skeleton className="creation-skeleton-copy" />
+        </div>
+        <div className="feedback-submit-form">
+          <Skeleton className="creation-skeleton-field" />
+          <Skeleton className="creation-skeleton-textarea" />
+          <Skeleton className="creation-skeleton-field" />
+          <Skeleton className="creation-skeleton-action" />
+        </div>
+      </section>
+      <span className="sr-only">Loading Post creation…</span>
+    </main>
+  );
+}