create-feedbax 0.1.0 → 0.2.1

package/template/src/post-queries.test.ts

@@ -0,0 +1,158 @@
+import { InfiniteQueryObserver, QueryClient } from "@tanstack/react-query";
+import type { PublicPostPage } from "@feedbax/feedback";
+import { describe, expect, it, vi } from "vitest";
+
+import { publicPostsQuery } from "./post-queries";
+import { authorizedDraftPostsQuery } from "./authorized-draft-query";
+import { capabilitiesKey, readCapabilities } from "./browser-post-state";
+
+vi.mock("./public-feedback-server-function", () => ({
+  getPublicPostPage: vi.fn(),
+}));
+
+describe("public Posts query", () => {
+  it("reuses the loader page and retains it when another cursor page loads", async () => {
+    const pages: Record<string, PublicPostPage> = {
+      first: {
+        items: [post("first-post")],
+        nextCursor: "opaque-cursor",
+      },
+      "opaque-cursor": { items: [post("second-post")] },
+    };
+    const fetchPage = vi.fn(async ({ cursor }: { cursor?: string }) =>
+      cursor ? pages[cursor]! : pages.first!,
+    );
+    const client = new QueryClient();
+    const options = publicPostsQuery({ sort: "trending" }, fetchPage);
+
+    await client.ensureInfiniteQueryData(options);
+    expect(fetchPage).toHaveBeenCalledTimes(1);
+
+    const observer = new InfiniteQueryObserver(client, options);
+    await observer.fetchNextPage();
+
+    expect(fetchPage).toHaveBeenCalledTimes(2);
+    expect(client.getQueryData(options.queryKey)).toMatchObject({
+      pages: [pages.first, pages["opaque-cursor"]],
+      pageParams: [undefined, "opaque-cursor"],
+    });
+  });
+});
+
+describe("authorized Draft Posts query", () => {
+  it("keeps Browser Capability secrets out of its key and cached result", async () => {
+    const secret = "private-browser-capability";
+    const capabilities = {
+      "draft-id": {
+        id: "draft-id",
+        slug: "private-draft",
+        browserCapability: secret,
+      },
+    };
+    const fetchDraft = vi.fn(async () => draft("draft-id"));
+    const client = new QueryClient();
+    const options = authorizedDraftPostsQuery(capabilities, fetchDraft);
+
+    await client.ensureQueryData(options);
+
+    expect(fetchDraft).toHaveBeenCalledWith({
+      data: {
+        id: "draft-id",
+        slug: "private-draft",
+        browserCapability: secret,
+      },
+    });
+    expect(JSON.stringify(options.queryKey)).not.toContain(secret);
+    expect(JSON.stringify(client.getQueryData(options.queryKey))).not.toContain(
+      secret,
+    );
+  });
+
+  it("removes only capabilities proven invalid while retaining valid drafts", async () => {
+    const storage = memoryStorage({
+      [capabilitiesKey]: JSON.stringify({
+        valid: {
+          id: "valid",
+          slug: "valid-draft",
+          browserCapability: "valid-secret",
+        },
+        expired: {
+          id: "expired",
+          slug: "expired-draft",
+          browserCapability: "expired-secret",
+        },
+      }),
+    });
+    const fetchDraft = vi.fn(async ({ data }: { data: { id: string } }) => {
+      if (data.id === "expired") {
+        throw new Error("Browser Capability did not authorize this draft.");
+      }
+      return draft(data.id);
+    });
+    const client = new QueryClient();
+
+    const drafts = await client.ensureQueryData(
+      authorizedDraftPostsQuery(readCapabilities(storage), fetchDraft, storage),
+    );
+
+    expect(drafts.map((item) => item.id)).toEqual(["valid"]);
+    expect(Object.keys(readCapabilities(storage))).toEqual(["valid"]);
+  });
+
+  it("keeps cached drafts visible when a private retrieval fails transiently", async () => {
+    const capabilities = {
+      valid: {
+        id: "valid",
+        slug: "valid-draft",
+        browserCapability: "valid-secret",
+      },
+    };
+    const options = authorizedDraftPostsQuery(capabilities, async () => {
+      throw new Error("Post service unavailable");
+    });
+    const cached = [draft("valid")];
+    const client = new QueryClient();
+    client.setQueryData(options.queryKey, cached);
+    await client.invalidateQueries({ queryKey: options.queryKey });
+
+    await expect(client.fetchQuery(options)).rejects.toThrow(
+      "Post service unavailable",
+    );
+
+    expect(client.getQueryData(options.queryKey)).toEqual(cached);
+  });
+});
+
+function post(slug: string) {
+  return {
+    slug,
+    title: slug,
+    description: `${slug} 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 draft(id: string) {
+  return {
+    id,
+    slug: `${id}-draft`,
+    title: `${id} draft`,
+    description: `${id} description`,
+    type: "Feature Request" as const,
+    status: "New" as const,
+    submitter: {},
+    createdAt: new Date("2026-08-22T10:00:00.000Z"),
+    updatedAt: new Date("2026-08-22T10:00:00.000Z"),
+  };
+}
+
+function memoryStorage(initial: Record<string, string>) {
+  const values = new Map(Object.entries(initial));
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => values.set(key, value),
+  };
+}

package/template/src/post-queries.ts

@@ -0,0 +1,26 @@
+import { infiniteQueryOptions } from "@tanstack/react-query";
+import type { PublicPostQuery, PublicPostPage } from "@feedbax/feedback";
+
+export type FetchPublicPostsPage = (
+  search: PublicPostQuery,
+) => Promise<PublicPostPage>;
+
+export const publicPostsQueryKey = ["public-posts"] as const;
+
+export function publicPostsQuery(
+  search: PublicPostQuery,
+  fetchPage: FetchPublicPostsPage,
+) {
+  const querySearch = { ...search, cursor: undefined };
+  return infiniteQueryOptions({
+    queryKey: [...publicPostsQueryKey, querySearch] as const,
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({ pageParam }) =>
+      fetchPage({
+        ...querySearch,
+        ...(pageParam ? { cursor: pageParam } : {}),
+      }),
+    getNextPageParam: (page) => page.nextCursor,
+    staleTime: 30_000,
+  });
+}

package/template/src/post-results.tsx

@@ -0,0 +1,165 @@
+import type { DraftPost, PublicPost } from "@feedbax/feedback";
+import type { PortalFeatures } from "@feedbax/config";
+import { Badge } from "@feedbax/ui/components/badge";
+import { Button } from "@feedbax/ui/components/button";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "@feedbax/ui/components/empty";
+import { SearchX } from "lucide-react";
+
+import { PostLink } from "./masked-post-link";
+import { PostStatusBadge, PostTypeBadge } from "./post-badges";
+import feedbax from "./feedbax";
+import { VoteToggle } from "./vote-toggle";
+
+export function PostResults({
+  drafts = [],
+  initialItems,
+  nextCursor,
+  loadMore,
+  loadingMore = false,
+  loadMoreError = false,
+  maskPostLinks = false,
+  features = feedbax.features,
+}: {
+  drafts?: DraftPost[];
+  initialItems: PublicPost[];
+  nextCursor?: string;
+  loadMore?: () => void;
+  loadingMore?: boolean;
+  loadMoreError?: boolean;
+  maskPostLinks?: boolean;
+  features?: PortalFeatures;
+}) {
+  if (!drafts.length && !initialItems.length) {
+    return (
+      <Empty className="min-h-72 border">
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <SearchX aria-hidden="true" />
+          </EmptyMedia>
+          <EmptyTitle>No Posts match this view.</EmptyTitle>
+          <EmptyDescription>
+            Try another Board or remove a Status filter.
+          </EmptyDescription>
+        </EmptyHeader>
+        <EmptyContent>
+          <Button
+            render={<a href="/" />}
+            nativeButton={false}
+            variant="outline"
+          >
+            Clear filters
+          </Button>
+        </EmptyContent>
+      </Empty>
+    );
+  }
+
+  return (
+    <>
+      <ol className="divide-y overflow-hidden border bg-card/30">
+        {drafts.map((post) => (
+          <PostResultRow
+            key={post.id}
+            post={post}
+            draft
+            maskPostLinks={maskPostLinks}
+            features={features}
+          />
+        ))}
+        {initialItems.map((post) => (
+          <PostResultRow
+            key={post.slug}
+            post={post}
+            maskPostLinks={maskPostLinks}
+            features={features}
+          />
+        ))}
+      </ol>
+      {loadMoreError ? (
+        <div role="alert" className="mt-6 flex items-center gap-3 border p-4">
+          <p className="mr-auto text-sm">Couldn’t load more Posts.</p>
+          <Button type="button" onClick={loadMore}>
+            Try again
+          </Button>
+        </div>
+      ) : null}
+      {nextCursor ? (
+        <Button
+          className="mt-6"
+          type="button"
+          onClick={loadMore}
+          disabled={loadingMore || loadMoreError || !loadMore}
+        >
+          {loadingMore ? "Loading…" : "Load More"}
+        </Button>
+      ) : null}
+    </>
+  );
+}
+
+function PostResultRow({
+  post,
+  draft = false,
+  maskPostLinks,
+  features,
+}: {
+  post: DraftPost | PublicPost;
+  draft?: boolean;
+  maskPostLinks: boolean;
+  features: PortalFeatures;
+}) {
+  const votingEligible =
+    features.voting &&
+    !draft &&
+    "voteCount" in post &&
+    post.voteCount !== undefined;
+  return (
+    <li className="relative">
+      {votingEligible ? (
+        <div className="absolute top-5 left-5 z-10 flex h-[4.75rem] w-16 items-center justify-center sm:w-[4.75rem]">
+          <VoteToggle post={post} />
+        </div>
+      ) : null}
+      <PostLink
+        className={draft ? "post-link draft-post-link" : "post-link"}
+        slug={post.slug}
+        contextual={maskPostLinks}
+      >
+        <article
+          className={`relative grid ${features.voting ? "grid-cols-[4rem_minmax(0,1fr)] sm:grid-cols-[4.75rem_minmax(0,1fr)]" : "grid-cols-1"} items-start gap-4 p-5 transition-colors duration-150 hover:bg-muted/30 sm:items-center`}
+        >
+          {features.voting ? (
+            <span className="h-[4.75rem]" aria-hidden="true" />
+          ) : null}
+          <span className="min-w-0 sm:pr-16">
+            <span className="block text-base font-medium text-foreground sm:text-lg">
+              {post.title}
+            </span>
+            <span className="mt-1 line-clamp-2 break-words text-sm leading-relaxed text-muted-foreground">
+              {post.description}
+            </span>
+            <span
+              className="mt-3 flex flex-wrap items-center gap-2 text-xs text-muted-foreground"
+              role="group"
+              aria-label="Post metadata"
+            >
+              <PostTypeBadge type={post.type} />
+              {draft ? (
+                <Badge variant="outline">Draft</Badge>
+              ) : (
+                <PostStatusBadge status={post.status} />
+              )}
+            </span>
+          </span>
+        </article>
+      </PostLink>
+    </li>
+  );
+}

package/template/src/public-cache-policy.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  applyPublicCachePolicy,
+  canonicalPublicRequest,
+} from "./public-cache-policy";
+
+describe("public portal cache policy", () => {
+  it("marks only successful public projections with the agreed browser and edge freshness", () => {
+    const response = applyPublicCachePolicy(
+      new Request("https://feedback.example.com/roadmap"),
+      Response.json({ lanes: [] }),
+    );
+
+    expect(response.headers.get("cache-control")).toBe("public, max-age=30");
+    expect(response.headers.get("cloudflare-cdn-cache-control")).toBe(
+      "public, max-age=120, stale-while-revalidate=600, stale-if-error=86400",
+    );
+    expect(response.headers.get("cache-tag")).toBe(
+      "feedbax-public,feedbax-roadmap",
+    );
+  });
+
+  it("caches Changelog briefly without stale reuse of expiring image URLs", () => {
+    const response = applyPublicCachePolicy(
+      new Request("https://feedback.example.com/changelog"),
+      new Response("timeline"),
+    );
+
+    expect(response.headers.get("cache-control")).toBe("public, max-age=30");
+    expect(response.headers.get("cloudflare-cdn-cache-control")).toBe(
+      "public, max-age=30",
+    );
+    expect(response.headers.get("cloudflare-cdn-cache-control")).not.toContain(
+      "stale-if-error",
+    );
+    expect(response.headers.get("cache-tag")).toBe(
+      "feedbax-public,feedbax-changelog",
+    );
+  });
+
+  it("keeps mutations, private pages, and failed public reads out of the cache", () => {
+    const cases = [
+      [
+        new Request("https://feedback.example.com/submit"),
+        new Response("form"),
+      ],
+      [
+        new Request("https://feedback.example.com/roadmap", {
+          method: "POST",
+        }),
+        new Response("updated"),
+      ],
+      [
+        new Request("https://feedback.example.com/roadmap"),
+        new Response("unavailable", { status: 503 }),
+      ],
+    ] as const;
+
+    for (const [request, source] of cases) {
+      const response = applyPublicCachePolicy(request, source);
+      expect(response.headers.get("cache-control")).toBe("no-store");
+      expect(response.headers.has("cache-tag")).toBe(false);
+    }
+  });
+
+  it("canonicalizes equivalent feedback filters before the cache sees the public projection", () => {
+    const first = canonicalPublicRequest(
+      new Request(
+        "https://feedback.example.com/?status=New&type=Bug%20Report&ignored=value",
+      ),
+    );
+    const second = canonicalPublicRequest(
+      new Request("https://feedback.example.com/?type=Bug%20Report&status=New"),
+    );
+
+    expect(first?.url).toBe(
+      "https://feedback.example.com/?types=%5B%22Bug+Report%22%5D&statuses=%5B%22New%22%5D&pageSize=25&sort=top&schema=2",
+    );
+    expect(second?.url).toBe(first?.url);
+  });
+
+  it("does not canonicalize non-public routes", () => {
+    const request = new Request(
+      "https://feedback.example.com/submit?status=New&type=Bug%20Report",
+    );
+
+    expect(canonicalPublicRequest(request)).toBeUndefined();
+  });
+
+  it("versions detail and roadmap identities with their fixed projection policy", () => {
+    expect(
+      canonicalPublicRequest(
+        new Request("https://feedback.example.com/roadmap"),
+      )?.url,
+    ).toBe(
+      "https://feedback.example.com/roadmap?sort=updated-at-desc&schema=2",
+    );
+    expect(
+      canonicalPublicRequest(new Request("https://feedback.example.com/p/slug"))
+        ?.url,
+    ).toBe("https://feedback.example.com/p/slug?schema=2");
+  });
+});
+
+describe("feed URL normalization", () => {
+  it("preserves New ordering instead of redirecting back to Top", () => {
+    expect(
+      canonicalPublicRequest(
+        new Request(
+          "https://feedback.example.com/?pageSize=25&sort=new&schema=2",
+        ),
+      ),
+    ).toBeUndefined();
+  });
+  it("uses New ordering with voting disabled and reaches a stable canonical URL", () => {
+    const features = { voting: false, comments: true, changelog: true };
+    const first = canonicalPublicRequest(
+      new Request("https://feedback.example.com/"),
+      features,
+    );
+    expect(new URL(first!.url).searchParams.get("sort")).toBe("new");
+    expect(canonicalPublicRequest(first!, features)).toBeUndefined();
+  });
+  it("preserves URL search and multiple Type/Status filters", () => {
+    const first = canonicalPublicRequest(
+      new Request(
+        "https://feedback.example.com/?types=%5B%22Bug%20Report%22,%22Feature%20Request%22%5D&statuses=%5B%22Planned%22%5D&search=keyboard&sort=new",
+      ),
+    );
+    const url = new URL(first!.url);
+    expect(JSON.parse(url.searchParams.get("types")!)).toEqual([
+      "Bug Report",
+      "Feature Request",
+    ]);
+    expect(JSON.parse(url.searchParams.get("statuses")!)).toEqual(["Planned"]);
+    expect(url.searchParams.get("search")).toBe("keyboard");
+    expect(url.searchParams.get("sort")).toBe("new");
+    expect(canonicalPublicRequest(first!)).toBeUndefined();
+  });
+});
+
+it("moves pre-0.2.1 cached projections to a new schema identity", () => {
+  const request = canonicalPublicRequest(
+    new Request("https://feedback.example.com/?pageSize=25&sort=top&schema=1"),
+  );
+  expect(new URL(request!.url).searchParams.get("schema")).toBe("2");
+});

package/template/src/public-cache-policy.ts

@@ -0,0 +1,119 @@
+import {
+  defaultParseSearch,
+  defaultStringifySearch,
+} from "@tanstack/react-router";
+import type { PortalFeatures } from "@feedbax/config";
+import { publicPostSearch } from "./public-feedback-page";
+import {
+  publicChangelogCacheTag,
+  publicFeedbackCacheTag,
+  publicPostCacheTag,
+  publicRoadmapCacheTag,
+} from "./public-cache-tags";
+
+const BROWSER_CACHE_CONTROL = "public, max-age=30";
+const EDGE_CACHE_CONTROL =
+  "public, max-age=120, stale-while-revalidate=600, stale-if-error=86400";
+const CHANGELOG_EDGE_CACHE_CONTROL = "public, max-age=30";
+const PUBLIC_PROJECTION_SCHEMA_VERSION = "2";
+const PUBLIC_FEEDBACK_PAGE_SIZE = "25";
+const PUBLIC_ROADMAP_SORT = "updated-at-desc";
+
+export function canonicalPublicRequest(
+  request: Request,
+  features?: PortalFeatures,
+): Request | undefined {
+  if (request.method !== "GET") return undefined;
+  const source = new URL(request.url);
+  if (!isPublicPath(source.pathname)) return undefined;
+
+  const canonical = new URL(source.origin + source.pathname);
+  if (source.pathname === "/") {
+    const parsed: Record<string, unknown> = defaultParseSearch(source.search);
+    const query = publicPostSearch(
+      {
+        ...parsed,
+        types: parsed.types ?? parsed.type,
+        statuses: parsed.statuses ?? parsed.status,
+      },
+      features,
+    );
+    const { cursor, search, types, statuses, sort } = query;
+    canonical.search = defaultStringifySearch({
+      ...(cursor ? { cursor } : {}),
+      ...(search ? { search } : {}),
+      ...(types?.length ? { types: [...types].sort() } : {}),
+      ...(statuses?.length ? { statuses: [...statuses].sort() } : {}),
+      pageSize: Number(PUBLIC_FEEDBACK_PAGE_SIZE),
+      sort,
+      schema: Number(PUBLIC_PROJECTION_SCHEMA_VERSION),
+    });
+  } else if (source.pathname === "/roadmap") {
+    canonical.searchParams.set("sort", PUBLIC_ROADMAP_SORT);
+  }
+  canonical.searchParams.set("schema", PUBLIC_PROJECTION_SCHEMA_VERSION);
+
+  if (canonical.href === source.href) return undefined;
+  return new Request(canonical, request);
+}
+
+export function applyPublicCachePolicy(
+  request: Request,
+  source: Response,
+): Response {
+  const response = new Response(source.body, source);
+  if (!isSafePublicProjection(request, response)) {
+    response.headers.set("Cache-Control", "no-store");
+    response.headers.delete("Cloudflare-CDN-Cache-Control");
+    response.headers.delete("Cache-Tag");
+    return response;
+  }
+
+  response.headers.set("Cache-Control", BROWSER_CACHE_CONTROL);
+  response.headers.set(
+    "Cloudflare-CDN-Cache-Control",
+    new URL(request.url).pathname === "/changelog"
+      ? CHANGELOG_EDGE_CACHE_CONTROL
+      : EDGE_CACHE_CONTROL,
+  );
+  response.headers.set("Cache-Tag", publicCacheTags(new URL(request.url)));
+  return response;
+}
+
+function isSafePublicProjection(request: Request, response: Response): boolean {
+  if (request.method !== "GET" || response.status !== 200) return false;
+  if (response.headers.has("Set-Cookie")) return false;
+  const { pathname } = new URL(request.url);
+  return isPublicPath(pathname);
+}
+
+function isPublicPath(pathname: string): boolean {
+  return (
+    pathname === "/" ||
+    pathname === "/roadmap" ||
+    pathname === "/changelog" ||
+    /^\/p\/[^/]+$/.test(pathname)
+  );
+}
+
+function publicCacheTags(url: URL): string {
+  if (url.pathname === "/changelog") {
+    return `feedbax-public,${publicChangelogCacheTag}`;
+  }
+  if (url.pathname === "/roadmap") {
+    return `feedbax-public,${publicRoadmapCacheTag}`;
+  }
+  const slug = /^\/p\/([^/]+)$/.exec(url.pathname)?.[1];
+  if (slug) {
+    return `feedbax-public,${publicFeedbackCacheTag},${publicPostCacheTag(decodePathSegment(slug))}`;
+  }
+  return `feedbax-public,${publicFeedbackCacheTag}`;
+}
+
+function decodePathSegment(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/template/src/public-cache-tags.ts

@@ -0,0 +1,7 @@
+export const publicFeedbackCacheTag = "feedbax-feedback";
+export const publicRoadmapCacheTag = "feedbax-roadmap";
+export const publicChangelogCacheTag = "feedbax-changelog";
+
+export function publicPostCacheTag(slug: string): string {
+  return `feedbax-post-${slug.replace(/[^A-Za-z0-9_.:-]/g, "-")}`;
+}

package/template/src/public-changelog-page.ts

@@ -0,0 +1,15 @@
+import type {
+  ChangelogModule,
+  ChangelogPage,
+  ChangelogQuery,
+} from "@feedbax/changelog";
+
+export function loadPublicChangelogPage({
+  changelog,
+  query = {},
+}: {
+  changelog: Pick<ChangelogModule, "listPublishedEntries">;
+  query?: ChangelogQuery;
+}): Promise<ChangelogPage> {
+  return changelog.listPublishedEntries(query);
+}

package/template/src/public-changelog-server-function.ts

@@ -0,0 +1,27 @@
+import { createServerFn } from "@tanstack/react-start";
+import { loadPublicChangelogPage } from "./public-changelog-page";
+import { runSafePublicRead } from "./safe-public-failure";
+
+export const getPublicChangelogPage = createServerFn({ method: "GET" })
+  .validator((input: unknown) => {
+    if (input === undefined) return {};
+    if (!input || typeof input !== "object")
+      throw new Error("Changelog request is invalid.");
+    const cursor = Reflect.get(input, "cursor");
+    const label = Reflect.get(input, "label");
+    if (cursor !== undefined && typeof cursor !== "string")
+      throw new Error("Changelog request is invalid.");
+    if (label !== undefined && typeof label !== "string")
+      throw new Error("Changelog request is invalid.");
+    return { ...(cursor ? { cursor } : {}), ...(label ? { label } : {}) };
+  })
+  .handler(({ data }) =>
+    runSafePublicRead(async () => {
+      const { createConfiguredChangelogModule } =
+        await import("./changelog-runtime");
+      return loadPublicChangelogPage({
+        changelog: createConfiguredChangelogModule(),
+        query: data,
+      });
+    }),
+  );

package/template/src/public-date.ts

@@ -0,0 +1,11 @@
+export function formatPublicDate(
+  date: Date,
+  month: "short" | "long" = "short",
+): string {
+  return new Intl.DateTimeFormat("en", {
+    day: "numeric",
+    month,
+    year: "numeric",
+    timeZone: "UTC",
+  }).format(date);
+}