create-feedbax 0.1.0 → 0.2.0

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

@@ -0,0 +1,141 @@
+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=1",
+    );
+    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=1",
+    );
+    expect(
+      canonicalPublicRequest(new Request("https://feedback.example.com/p/slug"))
+        ?.url,
+    ).toBe("https://feedback.example.com/p/slug?schema=1");
+  });
+});
+
+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=1",
+        ),
+      ),
+    ).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();
+  });
+});

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 = "1";
+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);
+}

package/template/src/public-failure-state.test.tsx

@@ -0,0 +1,69 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { PublicPortalError } from "./public-portal-error";
+import {
+  ActionablePortalFailure,
+  runSafePortalMutation,
+  runSafePublicRead,
+} from "./safe-public-failure";
+
+describe("public portal failure state", () => {
+  it("replaces private upstream diagnostics at the public read boundary", async () => {
+    const privateFailure = new Error(
+      "Notion token secret-token and property private-field",
+    );
+
+    const failure = await runSafePublicRead(async () =>
+      Promise.reject(privateFailure),
+    ).then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+
+    expect(failure).toBeInstanceOf(Error);
+    expect((failure as Error).message).toBe(
+      "Public feedback is temporarily unavailable.",
+    );
+    expect((failure as Error).message).not.toContain("secret-token");
+  });
+
+  it("renders an explicit retry state without serializing private failure details", () => {
+    const privateFailure = new Error(
+      "Notion token secret-token, property private-field, Browser Capability private-capability",
+    );
+
+    const html = renderToStaticMarkup(
+      <PublicPortalError error={privateFailure} reset={() => undefined} />,
+    );
+
+    expect(html).toContain("Posts are temporarily unavailable");
+    expect(html).toContain("Try again");
+    expect(html).not.toContain("secret-token");
+    expect(html).not.toContain("private-field");
+    expect(html).not.toContain("private-capability");
+  });
+
+  it("preserves actionable portal failures while replacing private mutation diagnostics", async () => {
+    await expect(
+      runSafePortalMutation(async () => {
+        throw new ActionablePortalFailure(
+          "Feedback submission rate limit exceeded.",
+        );
+      }),
+    ).rejects.toThrow("Feedback submission rate limit exceeded.");
+
+    const failure = await runSafePortalMutation(async () => {
+      throw new Error("Notion private diagnostic secret-token");
+    }).then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+
+    expect(failure).toBeInstanceOf(Error);
+    expect((failure as Error).message).toBe(
+      "Public feedback mutation is temporarily unavailable.",
+    );
+    expect((failure as Error).message).not.toContain("secret-token");
+  });
+});

package/template/src/public-feedback-index.tsx

@@ -0,0 +1,124 @@
+import type { PublicPostQuery, PublicPostPage } from "@feedbax/feedback";
+import type { PortalFeatures } from "@feedbax/config";
+import { Skeleton } from "@feedbax/ui/components/skeleton";
+import { useAuthorizedDraftPosts } from "./draft-post-list";
+import {
+  BoardNavigation,
+  PostFeedControls,
+  StatusNavigation,
+} from "./post-feed-controls";
+import { PostResults } from "./post-results";
+import feedbax from "./feedbax";
+
+export function PublicPostIndex({
+  page,
+  search,
+  loadMore,
+  loadingMore,
+  loadMoreError,
+  onSearchChange,
+  pending = false,
+  maskPostLinks = false,
+  features = feedbax.features,
+}: {
+  page: PublicPostPage;
+  search: PublicPostQuery;
+  loadMore?: () => void;
+  loadingMore?: boolean;
+  loadMoreError?: boolean;
+  onSearchChange?: (search: PublicPostQuery) => void;
+  pending?: boolean;
+  maskPostLinks?: boolean;
+  features?: PortalFeatures;
+}) {
+  const drafts = useAuthorizedDraftPosts(search);
+  return (
+    <main className="mx-auto w-full max-w-[96rem] px-6 py-10 lg:px-10">
+      <div className="grid gap-12 lg:grid-cols-[minmax(0,1fr)_22rem]">
+        <div className="min-w-0">
+          <section aria-labelledby="feedback-heading">
+            <h1
+              id="feedback-heading"
+              className="text-3xl font-semibold tracking-tight"
+            >
+              Feedback
+            </h1>
+            <p className="mt-2 text-base text-muted-foreground">
+              {features.voting
+                ? "Share ideas and vote on what matters."
+                : "Share ideas and follow public progress."}
+            </p>
+          </section>
+          <div className="mt-8 flex flex-col gap-3 lg:flex-row lg:items-center">
+            <PostFeedControls
+              contextualCreatePost={maskPostLinks}
+              search={search}
+              onSearchChange={onSearchChange}
+              pending={pending}
+              features={features}
+            />
+          </div>
+          <section className="mt-8" aria-live="polite">
+            <div className="mb-4">
+              <h2 className="text-lg font-medium">Posts</h2>
+            </div>
+            <PostResults
+              drafts={drafts}
+              initialItems={page.items}
+              nextCursor={page.nextCursor}
+              loadMore={loadMore}
+              loadingMore={loadingMore}
+              loadMoreError={loadMoreError}
+              maskPostLinks={maskPostLinks}
+              features={features}
+            />
+          </section>
+        </div>
+        <aside
+          className="hidden border-l pl-8 pt-14 lg:block"
+          aria-label="Feedback navigation"
+        >
+          <BoardNavigation search={search} onSearchChange={onSearchChange} />
+          <div className="mt-8">
+            <StatusNavigation search={search} onSearchChange={onSearchChange} />
+          </div>
+        </aside>
+      </div>
+    </main>
+  );
+}
+
+export function PublicPostFeedSkeleton() {
+  return (
+    <main
+      className="feedback-index feedback-feed-skeleton"
+      aria-label="Loading Posts"
+      aria-busy="true"
+    >
+      <section className="feedback-intro" aria-hidden="true">
+        <Skeleton className="feedback-skeleton-heading" />
+        <Skeleton className="feedback-skeleton-deck" />
+      </section>
+      <div className="post-controls" aria-hidden="true">
+        <Skeleton className="feedback-skeleton-control" />
+        <Skeleton className="feedback-skeleton-control" />
+        <Skeleton className="feedback-skeleton-control" />
+      </div>
+      <section className="feedback-results" aria-hidden="true">
+        <Skeleton className="feedback-skeleton-section-heading" />
+        <ol className="feedback-list">
+          {Array.from({ length: 3 }, (_, index) => (
+            <li key={index} data-post-skeleton-row>
+              <div className="feedback-skeleton-row">
+                <Skeleton className="feedback-skeleton-meta" />
+                <Skeleton className="feedback-skeleton-title" />
+                <Skeleton className="feedback-skeleton-copy" />
+              </div>
+            </li>
+          ))}
+        </ol>
+      </section>
+      <span className="sr-only">Loading Posts…</span>
+    </main>
+  );
+}