create-feedbax 0.1.0 → 0.2.1

package/template/src/browser-post-state.ts

@@ -0,0 +1,134 @@
+import { isValidCommentEmail } from "./comment-profile";
+
+export const capabilitiesKey = "feedbax:post-capabilities";
+export const deviceProfileKey = "feedbax:device-profile";
+export interface DeviceProfile {
+  name: string;
+  email?: string;
+}
+
+export interface CompleteDeviceProfile extends DeviceProfile {
+  email: string;
+}
+
+type DeviceProfileStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export interface StoredPostCapability {
+  id: string;
+  slug: string;
+  browserCapability: string;
+}
+
+export function readDeviceProfile(
+  storage: Pick<Storage, "getItem">,
+): DeviceProfile | undefined {
+  try {
+    const value = JSON.parse(
+      storage.getItem(deviceProfileKey) ?? "null",
+    ) as unknown;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return undefined;
+    }
+    const entries = Object.keys(value);
+    const name = Reflect.get(value, "name");
+    const email = Reflect.get(value, "email");
+    if (
+      entries.some((key) => key !== "name" && key !== "email") ||
+      typeof name !== "string" ||
+      name.trim().length === 0 ||
+      (email !== undefined && typeof email !== "string")
+    ) {
+      return undefined;
+    }
+    return {
+      name: name.trim(),
+      ...(typeof email === "string" && email.trim()
+        ? { email: email.trim() }
+        : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveDeviceProfile(
+  storage: Pick<DeviceProfileStorage, "setItem">,
+  profile: DeviceProfile,
+) {
+  const name = profile.name.trim();
+  if (!name) throw new Error("Device Profile display name is required.");
+  const email = profile.email?.trim();
+  storage.setItem(
+    deviceProfileKey,
+    JSON.stringify({ name, ...(email ? { email } : {}) }),
+  );
+}
+
+export function isCompleteDeviceProfile(
+  profile: DeviceProfile | undefined,
+): profile is CompleteDeviceProfile {
+  return Boolean(profile?.name.trim() && isValidCommentEmail(profile.email));
+}
+
+export function clearDeviceProfile(
+  storage: Pick<DeviceProfileStorage, "removeItem">,
+) {
+  storage.removeItem(deviceProfileKey);
+}
+
+export function deriveDeviceProfileInitials(profile: DeviceProfile): string {
+  return profile.name
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((part) => part[0]?.toLocaleUpperCase())
+    .join("");
+}
+export function readCapabilities(
+  storage: Pick<Storage, "getItem">,
+): Record<string, StoredPostCapability> {
+  try {
+    const value = JSON.parse(
+      storage.getItem(capabilitiesKey) ?? "{}",
+    ) as unknown;
+    if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+    return Object.fromEntries(
+      Object.entries(value).filter(
+        (entry): entry is [string, StoredPostCapability] => {
+          const [key, capability] = entry;
+          return (
+            capability !== null &&
+            typeof capability === "object" &&
+            !Array.isArray(capability) &&
+            Reflect.get(capability, "id") === key &&
+            typeof Reflect.get(capability, "slug") === "string" &&
+            Reflect.get(capability, "slug").length > 0 &&
+            typeof Reflect.get(capability, "browserCapability") === "string" &&
+            Reflect.get(capability, "browserCapability").length > 0
+          );
+        },
+      ),
+    );
+  } catch {
+    return {};
+  }
+}
+export function retainCapability(
+  storage: Pick<Storage, "getItem" | "setItem">,
+  capability: StoredPostCapability,
+) {
+  storage.setItem(
+    capabilitiesKey,
+    JSON.stringify({
+      ...readCapabilities(storage),
+      [capability.id]: capability,
+    }),
+  );
+}
+export function removeCapability(
+  storage: Pick<Storage, "getItem" | "setItem">,
+  id: string,
+) {
+  const capabilities = readCapabilities(storage);
+  delete capabilities[id];
+  storage.setItem(capabilitiesKey, JSON.stringify(capabilities));
+}

package/template/src/browser-vote-state.test.ts

@@ -0,0 +1,14 @@
+import { expect, it } from "vitest";
+import { persistVotedPost, readVotedPostSlugs } from "./browser-vote-state";
+
+it("remembers and removes voted Post identifiers in browser storage", () => {
+  const values = new Map<string, string>();
+  const storage = {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => void values.set(key, value),
+  };
+  persistVotedPost(storage, "keyboard-navigation", true);
+  expect(readVotedPostSlugs(storage)).toEqual(new Set(["keyboard-navigation"]));
+  persistVotedPost(storage, "keyboard-navigation", false);
+  expect(readVotedPostSlugs(storage)).toEqual(new Set());
+});

package/template/src/browser-vote-state.ts

@@ -0,0 +1,27 @@
+const votedPostsKey = "feedbax:voted-posts";
+
+export function readVotedPostSlugs(
+  storage: Pick<Storage, "getItem">,
+): Set<string> {
+  try {
+    const value: unknown = JSON.parse(storage.getItem(votedPostsKey) ?? "[]");
+    return new Set(
+      Array.isArray(value)
+        ? value.filter((item): item is string => typeof item === "string")
+        : [],
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+export function persistVotedPost(
+  storage: Pick<Storage, "getItem" | "setItem">,
+  slug: string,
+  voted: boolean,
+): void {
+  const slugs = readVotedPostSlugs(storage);
+  if (voted) slugs.add(slug);
+  else slugs.delete(slug);
+  storage.setItem(votedPostsKey, JSON.stringify([...slugs]));
+}

package/template/src/capability-authorization-error.ts

@@ -0,0 +1,3 @@
+export function isCapabilityAuthorizationFailure(error: unknown) {
+  return error instanceof Error && error.message.includes("did not authorize");
+}

package/template/src/changelog-page.test.tsx

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+import type { ChangelogPage as PageData } from "@feedbax/changelog";
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from "@tanstack/react-router";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ChangelogPage } from "./changelog-page";
+import { CommandPaletteProvider } from "./components/command-palette";
+
+afterEach(cleanup);
+
+describe("Changelog page", () => {
+  it("renders loader data, filters by Label, and loads the next cursor", async () => {
+    const loadPage = vi.fn().mockImplementation(async ({ cursor, label }) => {
+      if (label === "Fixed") return page([entry("fixed", "Fixed")]);
+      if (cursor === "next") return page([entry("older", "Improved")]);
+      return page([]);
+    });
+    renderChangelog({
+      initialPage: page([entry("new", "Improved")], "next"),
+      loadPage,
+    });
+
+    expect(
+      await screen.findByRole("heading", { level: 2, name: "new" }),
+    ).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Load more updates" }));
+    expect(
+      await screen.findByRole("heading", { level: 2, name: "older" }),
+    ).toBeTruthy();
+    expect(loadPage).toHaveBeenCalledWith({ cursor: "next" });
+
+    fireEvent.click(screen.getByRole("button", { name: "Improved" }));
+    await waitFor(() =>
+      expect(loadPage).toHaveBeenCalledWith({ label: "Improved" }),
+    );
+  });
+
+  it("preserves hash links and renders rich-text properties without page-body reads", async () => {
+    const loadPage = vi
+      .fn()
+      .mockResolvedValue(page([entry("anchored", "Fixed")]));
+    const { container } = renderChangelog({
+      initialPage: page([entry("first", "Improved")], "next"),
+      loadPage,
+      initialEntry: "/changelog#anchored",
+    });
+    expect(await screen.findByText("Body anchored")).toBeTruthy();
+    expect(loadPage).toHaveBeenCalledWith({ cursor: "next" });
+    expect(
+      screen
+        .getByRole("link", { name: "Link to anchored" })
+        .getAttribute("href"),
+    ).toBe("#anchored");
+    expect(container.querySelector("article#anchored")).toBeTruthy();
+  });
+
+  it("renders an accessible image and preserves text when an image is absent or expired", async () => {
+    const valid = entry("illustrated", "Improved");
+    valid.image = {
+      src: "https://files.notion.example/illustrated.png",
+      alt: "Illustrated image",
+      expiresAt: new Date(Date.now() + 60_000),
+    };
+    const expired = entry("expired", "Fixed");
+    expired.image = {
+      src: "https://files.notion.example/expired.png",
+      alt: "Expired image",
+      expiresAt: new Date(Date.now() - 1),
+    };
+
+    renderChangelog({ initialPage: page([valid, expired]), loadPage: vi.fn() });
+
+    expect(
+      await screen.findByRole("img", { name: "Illustrated image" }),
+    ).toBeTruthy();
+    expect(screen.queryByRole("img", { name: "Expired image" })).toBeNull();
+    expect(screen.getByText("Body expired")).toBeTruthy();
+  });
+});
+
+function renderChangelog({
+  initialPage,
+  loadPage,
+  initialEntry = "/changelog",
+}: {
+  initialPage: PageData;
+  loadPage: (input: { cursor?: string; label?: string }) => Promise<PageData>;
+  initialEntry?: string;
+}) {
+  const history = createMemoryHistory({ initialEntries: [initialEntry] });
+  const root = createRootRoute({
+    component: () => (
+      <CommandPaletteProvider>
+        <Outlet />
+      </CommandPaletteProvider>
+    ),
+  });
+  const changelog = createRoute({
+    getParentRoute: () => root,
+    path: "/changelog",
+    component: () => (
+      <ChangelogPage initialPage={initialPage} loadPage={loadPage} />
+    ),
+  });
+  const router = createRouter({
+    history,
+    routeTree: root.addChildren([changelog]),
+  });
+  return render(<RouterProvider router={router} />);
+}
+
+function page(items: PageData["items"], nextCursor?: string): PageData {
+  return { items, ...(nextCursor ? { nextCursor } : {}) };
+}
+
+function entry(slug: string, label: string): PageData["items"][number] {
+  return {
+    slug,
+    date: "2026-08-01",
+    title: slug,
+    summary: `Summary ${slug}`,
+    body: `Body ${slug}`,
+    labels: [label],
+    updatedAt: new Date("2026-08-01T00:00:00Z"),
+  };
+}

package/template/src/changelog-page.tsx

@@ -0,0 +1,228 @@
+import type {
+  ChangelogPage as PageData,
+  PublicChangelogEntry,
+} from "@feedbax/changelog";
+import { Badge } from "@feedbax/ui/components/badge";
+import { Button, buttonVariants } from "@feedbax/ui/components/button";
+import { ButtonGroup } from "@feedbax/ui/components/button-group";
+import { useRouterState } from "@tanstack/react-router";
+import { ChevronDown, Link2 } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { CommandPaletteTrigger } from "./components/command-palette-context";
+
+export type LoadChangelogPage = (input: {
+  cursor?: string;
+  label?: string;
+}) => Promise<PageData>;
+
+const emptyPage: PageData = { items: [] };
+
+export function ChangelogPage({
+  initialPage = emptyPage,
+  loadPage = async () => emptyPage,
+}: { initialPage?: PageData; loadPage?: LoadChangelogPage } = {}) {
+  const locationHash = useRouterState({
+    select: (state) => state.location.hash,
+  });
+  const [selectedLabel, setSelectedLabel] = useState<string>();
+  const [page, setPage] = useState(initialPage);
+  const [loading, setLoading] = useState(false);
+  const labels = useMemo(
+    () => [...new Set(initialPage.items.flatMap((entry) => entry.labels))],
+    [initialPage.items],
+  );
+
+  async function replaceForLabel(label?: string) {
+    setSelectedLabel(label);
+    setLoading(true);
+    try {
+      setPage(await loadPage(label ? { label } : {}));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function loadMore() {
+    if (!page.nextCursor) return;
+    setLoading(true);
+    try {
+      const next = await loadPage({
+        cursor: page.nextCursor,
+        ...(selectedLabel ? { label: selectedLabel } : {}),
+      });
+      setPage({
+        items: [...page.items, ...next.items],
+        ...(next.nextCursor ? { nextCursor: next.nextCursor } : {}),
+      });
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    const slug = locationHash.startsWith("#")
+      ? locationHash.slice(1)
+      : locationHash;
+    if (!slug) return;
+    const target = document.getElementById(slug);
+    if (target) {
+      target.scrollIntoView?.({ block: "start" });
+    } else if (page.nextCursor && !loading && !selectedLabel) {
+      void loadMore();
+    }
+  }, [
+    locationHash,
+    loading,
+    page.items.length,
+    page.nextCursor,
+    selectedLabel,
+  ]);
+
+  return (
+    <main className="mx-auto w-full max-w-[96rem] px-6 py-10 lg:px-10">
+      <header className="flex flex-wrap items-start justify-between gap-5">
+        <div>
+          <h1 className="text-2xl font-semibold tracking-tight">Changelog</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Product updates, fixes, and improvements.
+          </p>
+        </div>
+        <CommandPaletteTrigger className="h-10" />
+      </header>
+      {labels.length ? (
+        <ButtonGroup className="mt-6 flex-wrap" aria-label="Filter updates">
+          {[undefined, ...labels].map((label) => (
+            <Button
+              key={label ?? "all"}
+              type="button"
+              size="sm"
+              variant={selectedLabel === label ? "secondary" : "outline"}
+              aria-pressed={selectedLabel === label}
+              disabled={loading}
+              onClick={() => void replaceForLabel(label)}
+            >
+              {label ?? "All"}
+            </Button>
+          ))}
+        </ButtonGroup>
+      ) : null}
+      <ol
+        className="changelog-timeline"
+        aria-label="Product updates"
+        aria-busy={loading}
+      >
+        {page.items.map((entry) => (
+          <TimelineEntry entry={entry} key={entry.slug} />
+        ))}
+      </ol>
+      {!page.items.length && !loading ? (
+        <p className="py-12 text-sm text-muted-foreground">
+          No updates published yet.
+        </p>
+      ) : null}
+      {page.nextCursor ? (
+        <div className="mx-auto mt-8 flex max-w-5xl justify-center">
+          <Button
+            type="button"
+            variant="outline"
+            disabled={loading}
+            onClick={() => void loadMore()}
+          >
+            {loading ? "Loading updates…" : "Load more updates"}
+            <ChevronDown aria-hidden="true" />
+          </Button>
+        </div>
+      ) : null}
+    </main>
+  );
+}
+
+function TimelineEntry({ entry }: { entry: PublicChangelogEntry }) {
+  const image = useUnexpiredImage(entry.image);
+  return (
+    <li className="changelog-timeline-entry">
+      <time dateTime={entry.date}>{formatDate(entry.date)}</time>
+      <span className="changelog-timeline-marker" aria-hidden="true" />
+      <article id={entry.slug} tabIndex={-1}>
+        {entry.labels.length ? (
+          <div className="mb-3 flex flex-wrap gap-2" aria-label="Labels">
+            {entry.labels.map((label) => (
+              <Badge key={label} variant="outline">
+                {label}
+              </Badge>
+            ))}
+          </div>
+        ) : null}
+        <div className="flex items-start justify-between gap-3">
+          <h2 className="text-lg font-semibold tracking-tight">
+            {entry.title}
+          </h2>
+          <a
+            className={buttonVariants({ variant: "ghost", size: "icon-sm" })}
+            href={`#${entry.slug}`}
+            aria-label={`Link to ${entry.title}`}
+          >
+            <Link2 aria-hidden="true" />
+          </a>
+        </div>
+        <p className="mt-3 text-sm leading-relaxed">{entry.summary}</p>
+        <div className="changelog-entry-body">
+          {entry.body
+            .trim()
+            .split(/\n\s*\n/)
+            .filter(Boolean)
+            .map((paragraph, index) => (
+              <p key={index}>{paragraph}</p>
+            ))}
+        </div>
+        {image ? (
+          <img
+            className="mt-6 w-full border"
+            src={image.src}
+            alt={image.alt}
+            width={760}
+            height={420}
+          />
+        ) : null}
+      </article>
+    </li>
+  );
+}
+
+function useUnexpiredImage(image: PublicChangelogEntry["image"]) {
+  const expiry = image?.expiresAt
+    ? new Date(image.expiresAt).getTime()
+    : undefined;
+  const [available, setAvailable] = useState(
+    () => expiry === undefined || expiry > Date.now(),
+  );
+
+  useEffect(() => {
+    if (!image || expiry === undefined) {
+      setAvailable(Boolean(image));
+      return;
+    }
+    const remaining = expiry - Date.now();
+    if (remaining <= 0) {
+      setAvailable(false);
+      return;
+    }
+    setAvailable(true);
+    const timeout = window.setTimeout(() => setAvailable(false), remaining);
+    return () => window.clearTimeout(timeout);
+  }, [expiry, image]);
+
+  return available && (expiry === undefined || expiry > Date.now())
+    ? image
+    : undefined;
+}
+
+function formatDate(date: string) {
+  const [year, month, day] = date.split("-").map(Number);
+  return new Intl.DateTimeFormat("en-US", {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+    timeZone: "UTC",
+  }).format(new Date(Date.UTC(year, month - 1, day)));
+}

package/template/src/changelog-query.ts

@@ -0,0 +1,13 @@
+import type { ChangelogPage } from "@feedbax/changelog";
+import { queryOptions } from "@tanstack/react-query";
+
+export type FetchChangelogPage = (input?: {
+  data?: { cursor?: string; label?: string };
+}) => Promise<ChangelogPage>;
+
+export function changelogQuery(fetchPage: FetchChangelogPage) {
+  return queryOptions({
+    queryKey: ["public-changelog"],
+    queryFn: () => fetchPage(),
+  });
+}

package/template/src/changelog-runtime.ts

@@ -0,0 +1,27 @@
+import {
+  createChangelogModule,
+  createNotionChangelogStorage,
+} from "@feedbax/changelog";
+
+import feedbax from "./feedbax";
+import { requiredEnvironmentValue } from "./feedback-runtime";
+
+let configuredChangelog: ReturnType<typeof createChangelogModule> | undefined;
+
+export function createConfiguredChangelogModule() {
+  configuredChangelog ??= buildConfiguredChangelogModule();
+  return configuredChangelog;
+}
+
+function buildConfiguredChangelogModule() {
+  if (!feedbax.changelog) {
+    throw new Error("Changelog configuration is missing.");
+  }
+  return createChangelogModule({
+    storage: createNotionChangelogStorage({
+      token: requiredEnvironmentValue("NOTION_TOKEN"),
+      dataSourceId: feedbax.changelog.dataSourceId,
+      propertyIds: feedbax.changelog.properties,
+    }),
+  });
+}

package/template/src/cloudflare-turnstile.ts

@@ -0,0 +1,31 @@
+export interface TurnstileVerifier {
+  verify(options: { token: string; remoteIp?: string }): Promise<boolean>;
+}
+
+export function createCloudflareTurnstileVerifier({
+  secretKey,
+  request = fetch,
+}: {
+  secretKey: string;
+  request?: typeof fetch;
+}): TurnstileVerifier {
+  return {
+    async verify({ token, remoteIp }) {
+      try {
+        const body = new URLSearchParams({
+          secret: secretKey,
+          response: token,
+          ...(remoteIp ? { remoteip: remoteIp } : {}),
+        });
+        const response = await request(
+          "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+          { method: "POST", body },
+        );
+        const result = (await response.json()) as { success?: unknown };
+        return response.ok && result.success === true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/template/src/cloudflare-workers-test.ts

@@ -0,0 +1,3 @@
+export const cache = {
+  delete: async () => false,
+};

package/template/src/cloudflare-workers.d.ts

@@ -0,0 +1,24 @@
+declare module "cloudflare:workers" {
+  export const cache: {
+    purge(options: { tags: string[] }): Promise<{
+      success: boolean;
+      errors: Array<{ code: number; message: string }>;
+    }>;
+  };
+  export const env: {
+    FEEDBAX_UPDATES?: import("@cloudflare/workers-types").Queue<string>;
+    FEEDBAX_EMAIL?: import("@feedbax/feedback").CloudflareEmailBinding;
+    EMAIL_PROVIDER_SECRET?: string;
+    FEEDBAX_IMAGES?: import("@cloudflare/workers-types").R2Bucket;
+    FEEDBAX_DB?: import("@feedbax/feedback").ConnectedDatabase;
+    IDENTITY_HANDOFF_SECRET?: string;
+    TRUSTED_SUBMISSIONS_RATE_LIMITER: {
+      limit(options: { key: string }): Promise<{ success: boolean }>;
+    };
+    PORTAL_SUBMISSIONS_RATE_LIMITER: {
+      limit(options: { key: string }): Promise<{ success: boolean }>;
+    };
+    TURNSTILE_SECRET_KEY?: string;
+    PARTICIPATION_SIGNING_SECRET?: string;
+  };
+}