create-feedbax 0.1.0 → 0.2.0

package/template/src/trusted-feedback-handler.ts

@@ -0,0 +1,181 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+import type { FeedbackModule } from "@feedbax/feedback";
+import type { PostType, SubmitTrustedPostInput } from "@feedbax/feedback";
+
+const FIXED_TRUSTED_SUBMISSION_BOUNDS = {
+  submitterName: 200,
+  submitterEmail: 320,
+  idempotencyKey: 200,
+  bodyBytes: 16 * 1_024,
+} as const;
+
+export interface TrustedSubmissionRateLimiter {
+  limit(options: { key: string }): Promise<{ success: boolean }>;
+}
+
+interface TrustedFeedbackHandlerOptions {
+  apiKeyHash: string;
+  feedback: Pick<FeedbackModule, "submitTrustedPost">;
+  rateLimiter: TrustedSubmissionRateLimiter;
+  limits: {
+    maxTitleLength: number;
+    maxDescriptionLength: number;
+  };
+}
+
+export function createTrustedFeedbackHandler({
+  apiKeyHash,
+  feedback,
+  rateLimiter,
+  limits,
+}: TrustedFeedbackHandlerOptions): (request: Request) => Promise<Response> {
+  return async (request) => {
+    if (!hasValidBearerKey(request.headers.get("Authorization"), apiKeyHash)) {
+      return jsonResponse(401, { error: "Unauthorized trusted submission." });
+    }
+
+    try {
+      const { success } = await rateLimiter.limit({ key: apiKeyHash });
+      if (!success) {
+        return jsonResponse(429, {
+          error: "Trusted submission rate limit exceeded.",
+        });
+      }
+    } catch {
+      return jsonResponse(503, { error: "Trusted submission is unavailable." });
+    }
+
+    const idempotencyKey = request.headers.get("Idempotency-Key")?.trim();
+    if (!idempotencyKey) {
+      return jsonResponse(400, {
+        error: "Idempotency-Key header is required.",
+      });
+    }
+    if (
+      idempotencyKey.length > FIXED_TRUSTED_SUBMISSION_BOUNDS.idempotencyKey
+    ) {
+      return boundsError();
+    }
+
+    const input = await readTrustedSubmission(request, idempotencyKey, limits);
+    if (input instanceof Response) return input;
+
+    try {
+      const item = await feedback.submitTrustedPost(input);
+      return jsonResponse(200, item);
+    } catch {
+      return jsonResponse(502, { error: "Trusted submission failed." });
+    }
+  };
+}
+
+async function readTrustedSubmission(
+  request: Request,
+  externalId: string,
+  limits: TrustedFeedbackHandlerOptions["limits"],
+): Promise<SubmitTrustedPostInput | Response> {
+  let body: unknown;
+  try {
+    const text = await request.text();
+    if (
+      new TextEncoder().encode(text).byteLength >
+      FIXED_TRUSTED_SUBMISSION_BOUNDS.bodyBytes
+    ) {
+      return boundsError();
+    }
+    body = JSON.parse(text) as unknown;
+  } catch {
+    return jsonResponse(400, { error: "Request body must be valid JSON." });
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  const value = body as Record<string, unknown>;
+  if (
+    typeof value.title !== "string" ||
+    typeof value.description !== "string" ||
+    !isPostType(value.type)
+  ) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  if (
+    !hasBoundedRequiredText(value.title, limits.maxTitleLength) ||
+    !hasBoundedRequiredText(value.description, limits.maxDescriptionLength)
+  ) {
+    return boundsError();
+  }
+  const submitter = readSubmitter(value.submitter);
+  if (submitter instanceof Response) return submitter;
+  return {
+    externalId,
+    title: value.title,
+    description: value.description,
+    type: value.type,
+    ...(submitter ? { submitter } : {}),
+  };
+}
+
+function readSubmitter(
+  value: unknown,
+): SubmitTrustedPostInput["submitter"] | Response {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  const submitter = value as Record<string, unknown>;
+  if (
+    (submitter.name !== undefined && typeof submitter.name !== "string") ||
+    (submitter.email !== undefined && typeof submitter.email !== "string")
+  ) {
+    return jsonResponse(400, { error: "Request body is invalid." });
+  }
+  if (
+    (typeof submitter.name === "string" &&
+      submitter.name.length > FIXED_TRUSTED_SUBMISSION_BOUNDS.submitterName) ||
+    (typeof submitter.email === "string" &&
+      submitter.email.length > FIXED_TRUSTED_SUBMISSION_BOUNDS.submitterEmail)
+  ) {
+    return boundsError();
+  }
+  return {
+    ...(typeof submitter.name === "string" ? { name: submitter.name } : {}),
+    ...(typeof submitter.email === "string" ? { email: submitter.email } : {}),
+  };
+}
+
+function hasBoundedRequiredText(value: string, maximum: number): boolean {
+  return value.trim().length > 0 && value.length <= maximum;
+}
+
+function boundsError(): Response {
+  return jsonResponse(400, {
+    error: "Trusted submission exceeds an accepted bound.",
+  });
+}
+
+function isPostType(value: unknown): value is PostType {
+  return (
+    value === "Feature Request" ||
+    value === "Bug Report" ||
+    value === "General Feedback"
+  );
+}
+
+function hasValidBearerKey(
+  authorization: string | null,
+  expectedApiKeyHash: string,
+): boolean {
+  if (!authorization?.startsWith("Bearer ")) return false;
+  const presentedApiKey = authorization.slice("Bearer ".length);
+  const expectedHash = Buffer.from(expectedApiKeyHash, "base64url");
+  const presentedHash = createHash("sha256").update(presentedApiKey).digest();
+  return (
+    expectedHash.length === presentedHash.length &&
+    timingSafeEqual(expectedHash, presentedHash)
+  );
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return Response.json(body, { status });
+}

package/template/src/trusted-feedback-runtime.ts

@@ -0,0 +1,17 @@
+import { env } from "cloudflare:workers";
+
+import {
+  createConfiguredFeedbackModule,
+  feedbackSubmissionLimits,
+  requiredEnvironmentValue,
+} from "./feedback-runtime";
+import { createTrustedFeedbackHandler } from "./trusted-feedback-handler";
+
+export function createConfiguredTrustedFeedbackHandler() {
+  return createTrustedFeedbackHandler({
+    apiKeyHash: requiredEnvironmentValue("FEEDBAX_API_KEY_HASH"),
+    rateLimiter: env.TRUSTED_SUBMISSIONS_RATE_LIMITER,
+    limits: feedbackSubmissionLimits,
+    feedback: createConfiguredFeedbackModule(),
+  });
+}

package/template/src/turnstile-configuration.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import {
+  configuredTurnstileSecret,
+  configuredTurnstileSiteKey,
+} from "./turnstile-configuration";
+describe("typed Turnstile configuration", () => {
+  it("uses the public typed site key without a Vite environment variable", () => {
+    expect(
+      configuredTurnstileSiteKey({
+        enabled: true,
+        siteKey: "configured-public-key",
+      }),
+    ).toBe("configured-public-key");
+  });
+  it("disables browser widgets and server verification together even when a secret remains", () => {
+    expect(
+      configuredTurnstileSiteKey({ enabled: false, siteKey: "old-key" }),
+    ).toBeUndefined();
+    expect(
+      configuredTurnstileSecret("retained-secret", { enabled: false }),
+    ).toBeUndefined();
+  });
+  it("fails closed when enabled verification lacks its secret", () => {
+    expect(() =>
+      configuredTurnstileSecret(undefined, {
+        enabled: true,
+        siteKey: "public-key",
+      }),
+    ).toThrow("TURNSTILE_SECRET_KEY is missing");
+    expect(
+      configuredTurnstileSecret(" private-secret ", {
+        enabled: true,
+        siteKey: "public-key",
+      }),
+    ).toBe("private-secret");
+  });
+});

package/template/src/turnstile-configuration.ts

@@ -0,0 +1,19 @@
+import type { FeedbaxConfig } from "@feedbax/config";
+import feedbax from "./feedbax";
+type TurnstileConfiguration = FeedbaxConfig["turnstile"];
+export function configuredTurnstileSiteKey(
+  config: TurnstileConfiguration = feedbax.turnstile,
+): string | undefined {
+  return config.enabled ? config.siteKey : undefined;
+}
+export function configuredTurnstileSecret(
+  secret: string | undefined,
+  config: TurnstileConfiguration = feedbax.turnstile,
+): string | undefined {
+  if (!config.enabled) return undefined;
+  if (!secret?.trim())
+    throw new Error(
+      "Turnstile is enabled but TURNSTILE_SECRET_KEY is missing.",
+    );
+  return secret.trim();
+}

package/template/src/use-media-query.ts

@@ -0,0 +1,17 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+export function useMediaQuery(query: string): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof window.matchMedia !== "function") return () => {};
+      const media = window.matchMedia(query);
+      media.addEventListener("change", onChange);
+      return () => media.removeEventListener("change", onChange);
+    },
+    [query],
+  );
+  const getSnapshot = () =>
+    typeof window.matchMedia === "function" && window.matchMedia(query).matches;
+
+  return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}

package/template/src/vote-toggle.test.tsx

@@ -0,0 +1,171 @@
+// @vitest-environment jsdom
+
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  QueryClient,
+  QueryClientProvider,
+  useQuery,
+} from "@tanstack/react-query";
+import { VoteToggle } from "./vote-toggle";
+
+const post = {
+  slug: "keyboard-navigation",
+  title: "Keyboard navigation",
+  description: "Navigate without a mouse.",
+  type: "Feature Request" as const,
+  status: "Planned" as const,
+  voteCount: 2,
+  createdAt: new Date("2026-08-25T00:00:00.000Z"),
+  updatedAt: new Date("2026-08-25T00:00:00.000Z"),
+};
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+  delete window.turnstile;
+  sessionStorage.clear();
+});
+
+describe("Vote toggle", () => {
+  it("presents a caret in an interactive Vote control", () => {
+    renderVoteToggle();
+
+    const button = screen.getByRole("button", { name: "Add Vote, 2 Votes" });
+    expect(button.classList.contains("vote-toggle-button")).toBe(true);
+    expect(button.querySelector(".lucide-chevron-up")).not.toBeNull();
+    expect(button.querySelector(".lucide-arrow-up")).toBeNull();
+  });
+
+  it("reconciles every affected browser projection only after confirmation", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      Response.json({ voteCount: 3 }),
+    );
+    const queryClient = new QueryClient();
+    const fetchPosts = vi.fn().mockResolvedValue({ items: [post] });
+    const fetchRoadmap = vi
+      .fn()
+      .mockResolvedValue({ Planned: { items: [post] } });
+    function VisibleProjections() {
+      useQuery({
+        queryKey: ["public-posts", { sort: "top" }],
+        queryFn: fetchPosts,
+        staleTime: Infinity,
+      });
+      useQuery({
+        queryKey: ["public-post-roadmap"],
+        queryFn: fetchRoadmap,
+        staleTime: Infinity,
+      });
+      return null;
+    }
+    render(
+      <QueryClientProvider client={queryClient}>
+        <VisibleProjections />
+        <VoteToggle post={post} />
+      </QueryClientProvider>,
+    );
+    await waitFor(() => {
+      expect(fetchPosts).toHaveBeenCalledOnce();
+      expect(fetchRoadmap).toHaveBeenCalledOnce();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Add Vote, 2 Votes" }));
+
+    await waitFor(() =>
+      expect(localStorage.getItem("feedbax:voted-posts")).toContain(post.slug),
+    );
+    await waitFor(() => {
+      expect(fetchPosts).toHaveBeenCalledTimes(2);
+      expect(fetchRoadmap).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it("keeps mounted feed and Post detail toggles consistent after confirmation", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      Response.json({ voteCount: 3 }),
+    );
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <VoteToggle post={post} />
+        <VoteToggle post={post} />
+      </QueryClientProvider>,
+    );
+
+    fireEvent.click(
+      screen.getAllByRole("button", { name: "Add Vote, 2 Votes" })[0]!,
+    );
+
+    await waitFor(() =>
+      expect(
+        screen.getAllByRole("button", { name: "Remove Vote, 3 Votes" }),
+      ).toHaveLength(2),
+    );
+  });
+
+  it("renders and resets an explicit Turnstile challenge after verification failure", async () => {
+    const reset = vi.fn();
+    window.turnstile = { render: vi.fn().mockReturnValue("widget-1"), reset };
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      Response.json(
+        { error: "Vote verification failed.", code: "verification_failed" },
+        { status: 400 },
+      ),
+    );
+    renderVoteToggle({ turnstileSiteKey: "public-site-key" });
+    await waitFor(() => expect(window.turnstile?.render).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByRole("button", { name: "Add Vote, 2 Votes" }));
+
+    await waitFor(() => expect(reset).toHaveBeenCalledWith("widget-1"));
+    expect(screen.getByRole("alert").textContent).toContain(
+      "verification failed",
+    );
+  });
+
+  it("rolls back and gives retry guidance when a Vote times out", async () => {
+    vi.useFakeTimers();
+    vi.spyOn(globalThis, "fetch").mockImplementation(
+      (_input, init) =>
+        new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () =>
+            reject(new DOMException("Aborted", "AbortError")),
+          );
+        }),
+    );
+    renderVoteToggle({ requestTimeoutMs: 25 });
+    const button = screen.getByRole("button", { name: "Add Vote, 2 Votes" });
+    fireEvent.click(button);
+    expect(button.textContent).toContain("3");
+
+    await act(async () => vi.advanceTimersByTime(25));
+
+    expect(button.textContent).toContain("2");
+    expect(screen.getByRole("alert").textContent).toContain(
+      "Check your connection and try again",
+    );
+  });
+});
+
+function renderVoteToggle(
+  props: Partial<React.ComponentProps<typeof VoteToggle>> = {},
+) {
+  return render(
+    <QueryClientProvider client={new QueryClient()}>
+      <VoteToggle post={post} {...props} />
+    </QueryClientProvider>,
+  );
+}

package/template/src/vote-toggle.tsx

@@ -0,0 +1,211 @@
+import { configuredTurnstileSiteKey } from "./turnstile-configuration";
+import type { PublicPost } from "@feedbax/feedback";
+import { ChevronUp } from "lucide-react";
+import { useContext, useEffect, useRef, useState } from "react";
+import { QueryClientContext } from "@tanstack/react-query";
+import { readVotedPostSlugs, persistVotedPost } from "./browser-vote-state";
+import { publicPostsQueryKey } from "./post-queries";
+import { publicRoadmapQueryKey } from "./roadmap-query";
+
+const voteConfirmedEvent = "feedbax:vote-confirmed";
+
+declare global {
+  interface Window {
+    turnstile?: {
+      render(element: HTMLElement, options: { sitekey: string }): string;
+      reset(widgetId: string): void;
+    };
+  }
+}
+
+export function VoteToggle({
+  post,
+  turnstileSiteKey = configuredTurnstileSiteKey(),
+  requestTimeoutMs = 10_000,
+}: {
+  post: PublicPost;
+  turnstileSiteKey?: string;
+  requestTimeoutMs?: number;
+}) {
+  const queryClient = useContext(QueryClientContext);
+  const [voted, setVoted] = useState(false);
+  const [count, setCount] = useState(post.voteCount ?? 0);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string>();
+  const [participationPass, setParticipationPass] = useState<string>();
+  const form = useRef<HTMLFormElement>(null);
+  const turnstileContainer = useRef<HTMLDivElement>(null);
+  const turnstileWidget = useRef<string | undefined>(undefined);
+
+  useEffect(() => {
+    setVoted(readVotedPostSlugs(localStorage).has(post.slug));
+    setCount(post.voteCount ?? 0);
+    setParticipationPass(
+      sessionStorage.getItem("feedbax:participation-pass") ?? undefined,
+    );
+  }, [post.slug, post.voteCount]);
+  useEffect(() => {
+    const reconcile = (event: Event) => {
+      const detail = (
+        event as CustomEvent<{
+          slug: string;
+          voteCount: number;
+          voted: boolean;
+        }>
+      ).detail;
+      if (detail.slug !== post.slug) return;
+      setCount(detail.voteCount);
+      setVoted(detail.voted);
+    };
+    window.addEventListener(voteConfirmedEvent, reconcile);
+    return () => window.removeEventListener(voteConfirmedEvent, reconcile);
+  }, [post.slug]);
+  useEffect(() => {
+    if (!turnstileSiteKey || participationPass || !turnstileContainer.current)
+      return;
+    const render = () => {
+      if (
+        !turnstileWidget.current &&
+        window.turnstile &&
+        turnstileContainer.current
+      ) {
+        turnstileWidget.current = window.turnstile.render(
+          turnstileContainer.current,
+          { sitekey: turnstileSiteKey },
+        );
+      }
+    };
+    const existing = document.querySelector<HTMLScriptElement>(
+      "script[data-turnstile]",
+    );
+    if (existing) {
+      if (window.turnstile) render();
+      else existing.addEventListener("load", render, { once: true });
+      return () => existing.removeEventListener("load", render);
+    }
+    const script = document.createElement("script");
+    script.src =
+      "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+    script.async = true;
+    script.defer = true;
+    script.dataset.turnstile = "true";
+    script.addEventListener("load", render, { once: true });
+    document.head.append(script);
+    return () => script.removeEventListener("load", render);
+  }, [participationPass, turnstileSiteKey]);
+
+  async function toggle() {
+    const previous = { voted, count };
+    const nextVoted = !voted;
+    setVoted(nextVoted);
+    setCount(Math.max(0, count + (nextVoted ? 1 : -1)));
+    setPending(true);
+    setError(undefined);
+    try {
+      const turnstileToken = form.current
+        ? new FormData(form.current).get("cf-turnstile-response")
+        : undefined;
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+      const response = await fetch("/internal/votes", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        signal: controller.signal,
+        body: JSON.stringify({
+          slug: post.slug,
+          intention: nextVoted ? "add" : "remove",
+          participationPass,
+          ...(turnstileToken ? { turnstileToken: String(turnstileToken) } : {}),
+        }),
+      }).finally(() => clearTimeout(timeout));
+      const result = (await response.json()) as {
+        voteCount: number;
+        participationPass?: string;
+        error?: string;
+        code?: string;
+      };
+      if (!response.ok) {
+        if (
+          result.code === "verification_failed" ||
+          result.code === "verification_required"
+        ) {
+          sessionStorage.removeItem("feedbax:participation-pass");
+          setParticipationPass(undefined);
+          if (turnstileWidget.current)
+            window.turnstile?.reset(turnstileWidget.current);
+          turnstileWidget.current = undefined;
+        }
+        throw new Error(result.error ?? "Vote failed. Try again.");
+      }
+      setCount(result.voteCount);
+      persistVotedPost(localStorage, post.slug, nextVoted);
+      window.dispatchEvent(
+        new CustomEvent(voteConfirmedEvent, {
+          detail: {
+            slug: post.slug,
+            voteCount: result.voteCount,
+            voted: nextVoted,
+          },
+        }),
+      );
+      if (queryClient) {
+        void Promise.all([
+          queryClient.invalidateQueries({ queryKey: publicPostsQueryKey }),
+          queryClient.invalidateQueries({ queryKey: publicRoadmapQueryKey }),
+        ]);
+      }
+      if (result.participationPass) {
+        sessionStorage.setItem(
+          "feedbax:participation-pass",
+          result.participationPass,
+        );
+        setParticipationPass(result.participationPass);
+      }
+    } catch (cause) {
+      setVoted(previous.voted);
+      setCount(previous.count);
+      setError(
+        cause instanceof DOMException && cause.name === "AbortError"
+          ? "Vote timed out. Check your connection and try again."
+          : cause instanceof Error
+            ? cause.message
+            : "Vote failed. Try again.",
+      );
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <form
+      ref={form}
+      className="vote-toggle"
+      onSubmit={(event) => event.preventDefault()}
+    >
+      <button
+        className="vote-toggle-button"
+        type="button"
+        aria-pressed={voted}
+        aria-label={`${voted ? "Remove Vote" : "Add Vote"}, ${count} Votes`}
+        disabled={pending}
+        onClick={toggle}
+      >
+        <ChevronUp aria-hidden="true" /> {count}
+      </button>
+      {turnstileSiteKey && !participationPass ? (
+        <div
+          ref={(element) => {
+            turnstileContainer.current = element;
+            if (element && window.turnstile && !turnstileWidget.current) {
+              turnstileWidget.current = window.turnstile.render(element, {
+                sitekey: turnstileSiteKey,
+              });
+            }
+          }}
+          className="cf-turnstile"
+        />
+      ) : null}
+      {error ? <p role="alert">{error}</p> : null}
+    </form>
+  );
+}

package/template/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ],
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": [
+      "vite/client",
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ],
+      "@feedbax/feedback": [
+        "./src/feedbax/feedback/index.ts"
+      ],
+      "@feedbax/changelog": [
+        "./src/feedbax/changelog/index.ts"
+      ],
+      "@feedbax/config": [
+        "./src/feedbax/config/index.ts"
+      ],
+      "@feedbax/ui/*": [
+        "./src/components/ui/*"
+      ],
+      "@feedbax/ui/globals.css": [
+        "./src/components/ui/styles/globals.css"
+      ]
+    }
+  }
+}