create-feedbax 0.1.0 → 0.2.1

package/template/src/feedback-cache-invalidation.test.ts

@@ -0,0 +1,185 @@
+import { createFeedbackModule } from "@feedbax/feedback";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createInvalidatingFeedbackModule,
+  createPublicCacheInvalidator,
+} from "./feedback-cache-invalidation";
+
+describe("feedback cache invalidation", () => {
+  it("purges only feedback-list and changed-Post tags after a successful write", async () => {
+    const purge = vi.fn().mockResolvedValue({ success: true, errors: [] });
+    const feedback = createInvalidatingFeedbackModule({
+      feedback: createFeedbackModule(),
+      invalidator: createPublicCacheInvalidator({ purge }),
+    });
+
+    const submitted = await feedback.submitPost({
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+    });
+
+    expect(purge).toHaveBeenCalledWith({
+      tags: ["feedbax-feedback", `feedbax-post-${submitted.slug}`],
+    });
+    expect(purge.mock.calls[0]?.[0].tags).not.toContain("feedbax-roadmap");
+  });
+
+  it("invalidates public feedback after a trusted submission", async () => {
+    const invalidatePost = vi.fn().mockResolvedValue(undefined);
+    const feedback = createInvalidatingFeedbackModule({
+      feedback: createFeedbackModule(),
+      invalidator: { invalidatePost, invalidateVote: invalidatePost },
+    });
+
+    const submitted = await feedback.submitTrustedPost({
+      externalId: "product-a:feedback-123",
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+    });
+
+    expect(invalidatePost).toHaveBeenCalledExactlyOnceWith(submitted.slug);
+  });
+
+  it("invalidates feed, Post detail, and roadmap projections after a confirmed Vote", async () => {
+    const purge = vi.fn().mockResolvedValue({ success: true, errors: [] });
+    const now = new Date("2026-08-25T10:00:00.000Z");
+    const feedback = createInvalidatingFeedbackModule({
+      feedback: createFeedbackModule({
+        initialItems: [
+          {
+            id: "post-id",
+            slug: "keyboard-navigation",
+            title: "Keyboard navigation",
+            description: "Navigate without a mouse.",
+            type: "Feature Request",
+            status: "Planned",
+            published: true,
+            voteCount: 2,
+            createdAt: now,
+            updatedAt: now,
+          },
+        ],
+      }),
+      invalidator: createPublicCacheInvalidator({ purge }),
+    });
+
+    await feedback.changeVote({
+      slug: "keyboard-navigation",
+      intention: "add",
+    });
+
+    expect(purge).toHaveBeenCalledWith({
+      tags: [
+        "feedbax-feedback",
+        "feedbax-post-keyboard-navigation",
+        "feedbax-roadmap",
+      ],
+    });
+  });
+
+  it("keeps a confirmed Vote successful when cache invalidation fails", async () => {
+    const now = new Date("2026-08-25T10:00:00.000Z");
+    const feedback = createInvalidatingFeedbackModule({
+      feedback: createFeedbackModule({
+        initialItems: [
+          {
+            id: "post-id",
+            slug: "keyboard-navigation",
+            title: "Keyboard navigation",
+            description: "Navigate without a mouse.",
+            type: "Feature Request",
+            status: "Planned",
+            published: true,
+            voteCount: 2,
+            createdAt: now,
+            updatedAt: now,
+          },
+        ],
+      }),
+      invalidator: {
+        invalidatePost: vi.fn(),
+        invalidateVote: vi.fn().mockRejectedValue(new Error("purge failed")),
+      },
+    });
+
+    await expect(
+      feedback.changeVote({
+        slug: "keyboard-navigation",
+        intention: "add",
+      }),
+    ).resolves.toEqual({ slug: "keyboard-navigation", voteCount: 3 });
+  });
+
+  it("invalidates after edits and withdrawals without passing private write data", async () => {
+    const invalidatePost = vi.fn().mockResolvedValue(undefined);
+    const feedback = createInvalidatingFeedbackModule({
+      feedback: createFeedbackModule(),
+      invalidator: { invalidatePost, invalidateVote: invalidatePost },
+    });
+    const submitted = await feedback.submitPost({
+      title: "Original title",
+      description: "Original description",
+      type: "General Feedback",
+      submitter: { email: "private@example.com" },
+    });
+    invalidatePost.mockClear();
+
+    await feedback.editDraftPost({
+      id: submitted.id,
+      browserCapability: submitted.browserCapability,
+      title: "Revised title",
+      description: "Revised description",
+      type: "Bug Report",
+    });
+    await feedback.withdrawDraftPost({
+      id: submitted.id,
+      browserCapability: submitted.browserCapability,
+    });
+
+    expect(invalidatePost.mock.calls).toEqual([
+      [submitted.slug],
+      [submitted.slug],
+    ]);
+  });
+
+  it("does not purge when a write fails", async () => {
+    const invalidatePost = vi.fn().mockResolvedValue(undefined);
+    const feedback = createInvalidatingFeedbackModule({
+      feedback: {
+        ...createFeedbackModule(),
+        submitPost: vi.fn().mockRejectedValue(new Error("write failed")),
+      },
+      invalidator: { invalidatePost, invalidateVote: invalidatePost },
+    });
+
+    await expect(
+      feedback.submitPost({
+        title: "Keyboard navigation",
+        description: "Let participants navigate without a mouse.",
+        type: "Feature Request",
+      }),
+    ).rejects.toThrow("write failed");
+    expect(invalidatePost).not.toHaveBeenCalled();
+  });
+
+  it("reports purge rejection without exposing Cloudflare details", async () => {
+    const invalidator = createPublicCacheInvalidator({
+      purge: vi.fn().mockResolvedValue({
+        success: false,
+        errors: [{ code: 1234, message: "private infrastructure detail" }],
+      }),
+    });
+
+    const invalidation = invalidator.invalidatePost("feedback-123");
+
+    await expect(invalidation).rejects.toThrow(
+      "Public feedback cache invalidation failed.",
+    );
+    await expect(invalidation).rejects.not.toThrow(
+      "private infrastructure detail",
+    );
+  });
+});

package/template/src/feedback-cache-invalidation.ts

@@ -0,0 +1,98 @@
+import type { FeedbackModule } from "@feedbax/feedback";
+
+import {
+  publicFeedbackCacheTag,
+  publicPostCacheTag,
+  publicRoadmapCacheTag,
+} from "./public-cache-tags";
+
+interface PublicCacheInvalidator {
+  invalidatePost(slug: string): Promise<void>;
+  invalidateVote(slug: string): Promise<void>;
+}
+
+interface CachePurgeResult {
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+}
+
+type PurgePublicCache = (options: {
+  tags: string[];
+}) => Promise<CachePurgeResult>;
+
+export function createPublicCacheInvalidator({
+  purge,
+}: {
+  purge: PurgePublicCache;
+}): PublicCacheInvalidator {
+  async function purgePost(slug: string, tags: string[]) {
+    const result = await purge({
+      tags: [publicFeedbackCacheTag, publicPostCacheTag(slug), ...tags],
+    });
+    if (!result.success) {
+      throw new Error("Public feedback cache invalidation failed.");
+    }
+  }
+  return {
+    invalidatePost: (slug) => purgePost(slug, []),
+    invalidateVote: (slug) => purgePost(slug, [publicRoadmapCacheTag]),
+  };
+}
+
+export function createInvalidatingFeedbackModule({
+  feedback,
+  invalidator,
+}: {
+  feedback: FeedbackModule;
+  invalidator: PublicCacheInvalidator;
+}): FeedbackModule {
+  return {
+    getAttachmentPostState: (slug) => feedback.getAttachmentPostState(slug),
+    editComment: (input) => feedback.editComment(input),
+    deleteComment: (input) => feedback.deleteComment(input),
+    async createComment(input) {
+      const comment = await feedback.createComment(input);
+      await invalidator.invalidatePost(input.slug).catch(() => undefined);
+      return comment;
+    },
+    async replyToCommentThread(input) {
+      const comment = await feedback.replyToCommentThread(input);
+      await invalidator.invalidatePost(input.slug).catch(() => undefined);
+      return comment;
+    },
+    async changeVote(input) {
+      const result = await feedback.changeVote(input);
+      await invalidator.invalidateVote(result.slug).catch(() => undefined);
+      return result;
+    },
+    submitPost: (input) =>
+      runInvalidatingWrite(() => feedback.submitPost(input), invalidator),
+    editDraftPost: (input) =>
+      runInvalidatingWrite(() => feedback.editDraftPost(input), invalidator),
+    getPublicPost: (slug) => feedback.getPublicPost(slug),
+    listCommentThreads: (input) => feedback.listCommentThreads(input),
+    getDraftPost: (input) => feedback.getDraftPost(input),
+    listPublicPosts: (query) => feedback.listPublicPosts(query),
+    listPublicRoadmapPosts: (query) => feedback.listPublicRoadmapPosts(query),
+    submitTrustedPost: (input) =>
+      runInvalidatingWrite(
+        () => feedback.submitTrustedPost(input),
+        invalidator,
+      ),
+    async withdrawDraftPost(input) {
+      const draft = await feedback.getDraftPost(input);
+      await feedback.withdrawDraftPost(input);
+      await invalidator.invalidatePost(draft.slug);
+    },
+    getPublicPostRoadmap: () => feedback.getPublicPostRoadmap(),
+  };
+}
+
+async function runInvalidatingWrite<Item extends { slug: string }>(
+  write: () => Promise<Item>,
+  invalidator: PublicCacheInvalidator,
+): Promise<Item> {
+  const item = await write();
+  await invalidator.invalidatePost(item.slug);
+  return item;
+}

package/template/src/feedback-runtime.ts

@@ -0,0 +1,105 @@
+import {
+  createImageModule,
+  createImageFeedbackModule,
+  createNotionImageReviewWriter,
+  createConnectedStore,
+  createConnectedFeedbackModule,
+  type VerifiedParticipant,
+  createNotionFeedbackModule,
+} from "@feedbax/feedback";
+import { cache, env } from "cloudflare:workers";
+
+import {
+  createInvalidatingFeedbackModule,
+  createPublicCacheInvalidator,
+} from "./feedback-cache-invalidation";
+import feedbax from "./feedbax";
+
+export const feedbackSubmissionLimits = {
+  maxTitleLength: feedbax.submissions.maxTitleLength,
+  maxDescriptionLength: feedbax.submissions.maxDescriptionLength,
+} as const;
+
+export function createConfiguredNotionFeedbackModule() {
+  configuredFeedback ??= createNotionFeedbackModule({
+    votingEnabled: feedbax.features.voting,
+    commentsEnabled: feedbax.features.comments,
+    token: requiredEnvironmentValue("NOTION_TOKEN"),
+    dataSourceId: feedbax.notion.dataSourceId,
+    propertyIds: feedbax.notion.properties,
+  });
+  return configuredFeedback;
+}
+
+export function createConfiguredFeedbackModule(
+  participant?: VerifiedParticipant,
+) {
+  const content = createConfiguredNotionFeedbackModule();
+  const feedback = feedbax.connected
+    ? createConnectedFeedbackModule(content, getConnectedStore(), participant)
+    : content;
+  const images = feedbax.connected?.images
+    ? configuredImages(feedback, participant)
+    : undefined;
+  const withImages = images
+    ? createImageFeedbackModule(
+        feedback,
+        images,
+        createNotionImageReviewWriter({
+          token: requiredEnvironmentValue("NOTION_TOKEN"),
+          reviewUrl: (id) => images.reviewUrl(id, feedbax.product.siteUrl!),
+        }),
+      )
+    : feedback;
+  return createInvalidatingFeedbackModule({
+    feedback: withImages,
+    invalidator: createPublicCacheInvalidator({
+      purge: (options) => cache.purge(options),
+    }),
+  });
+}
+
+let configuredFeedback:
+  ReturnType<typeof createInvalidatingFeedbackModule> | undefined;
+
+export function requiredEnvironmentValue(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error("Feedback configuration is missing.");
+  return value;
+}
+
+export function getConnectedStore() {
+  if (!feedbax.connected || !env.FEEDBAX_DB)
+    throw new Error("Connected Profile requires the FEEDBAX_DB D1 binding.");
+  return createConnectedStore(env.FEEDBAX_DB);
+}
+
+export function configuredImages(
+  feedback: import("@feedbax/feedback").FeedbackModule,
+  participant?: VerifiedParticipant,
+) {
+  if (
+    !env.FEEDBAX_DB ||
+    !env.FEEDBAX_IMAGES ||
+    !env.PARTICIPATION_SIGNING_SECRET ||
+    env.PARTICIPATION_SIGNING_SECRET.length < 32
+  )
+    throw new Error(
+      "Image attachments require D1, private R2, and the participation signing secret.",
+    );
+  return createImageModule({
+    database: env.FEEDBAX_DB,
+    bucket: env.FEEDBAX_IMAGES,
+    feedback,
+    participant,
+    reviewSecret: env.PARTICIPATION_SIGNING_SECRET,
+    processing: feedbax.connected?.processing ?? "small",
+  });
+}
+export async function requestParticipant(request: Request) {
+  if (!feedbax.connected) return;
+  const { readSessionToken, sessionHash } =
+    await import("./connected-identity");
+  const token = readSessionToken(request);
+  return token ? getConnectedStore().session(sessionHash(token)) : undefined;
+}

package/template/src/feedbax/changelog/index.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createChangelogModule,
+  createInMemoryChangelogStorage,
+  type ChangelogDate,
+  type StoredChangelogEntry,
+} from ".";
+
+describe("Changelog module", () => {
+  it("returns only Published Changelog Entries in deterministic Date order", async () => {
+    const changelog = createChangelogModule({
+      storage: createInMemoryChangelogStorage([
+        entry({ id: "z", slug: "draft", published: false, date: "2026-08-30" }),
+        entry({ id: "b", slug: "second", date: "2026-08-20" }),
+        entry({ id: "a", slug: "first", date: "2026-08-20" }),
+        entry({ id: "c", slug: "older", date: "2026-08-10" }),
+      ]),
+    });
+
+    await expect(changelog.listPublishedEntries()).resolves.toMatchObject({
+      items: [{ slug: "first" }, { slug: "second" }, { slug: "older" }],
+    });
+  });
+
+  it("filters Labels and continues in stable batches of 20", async () => {
+    const changelog = createChangelogModule({
+      storage: createInMemoryChangelogStorage(
+        Array.from({ length: 22 }, (_, index) =>
+          entry({
+            id: String(index).padStart(2, "0"),
+            slug: `entry-${index}`,
+            date: `2026-08-${String(22 - index).padStart(2, "0")}` as ChangelogDate,
+            labels: index === 21 ? ["Fixed"] : ["Improved"],
+          }),
+        ),
+      ),
+    });
+
+    const first = await changelog.listPublishedEntries({ label: "Improved" });
+    expect(first.items).toHaveLength(20);
+    expect(first.nextCursor).toBeTruthy();
+    const second = await changelog.listPublishedEntries({
+      label: "Improved",
+      cursor: first.nextCursor,
+    });
+    expect(second.items.map(({ slug }) => slug)).toEqual(["entry-20"]);
+    await expect(
+      changelog.listPublishedEntries({ label: "Fixed" }),
+    ).resolves.toMatchObject({ items: [{ slug: "entry-21" }] });
+  });
+
+  it("starts empty and projects at most one image", async () => {
+    await expect(
+      createChangelogModule({
+        storage: createInMemoryChangelogStorage(),
+      }).listPublishedEntries(),
+    ).resolves.toEqual({ items: [] });
+
+    const changelog = createChangelogModule({
+      storage: createInMemoryChangelogStorage([
+        entry({
+          images: [
+            { src: "https://files.example/first", alt: "First" },
+            { src: "https://files.example/second", alt: "Second" },
+          ],
+        }),
+      ]),
+    });
+    await expect(changelog.listPublishedEntries()).resolves.toMatchObject({
+      items: [{ image: { src: "https://files.example/first", alt: "First" } }],
+    });
+  });
+
+  it("preserves Changelog text while discarding an image before cache freshness could outlive it", async () => {
+    const changelog = createChangelogModule({
+      storage: createInMemoryChangelogStorage([
+        entry({
+          title: "Safe release",
+          body: "The release text remains available.",
+          images: [
+            {
+              src: "https://files.example/expiring",
+              alt: "Safe release image",
+              expiresAt: new Date("2026-08-26T12:00:30Z"),
+            },
+          ],
+        }),
+      ]),
+      now: () => new Date("2026-08-26T12:00:00Z"),
+    });
+
+    const page = await changelog.listPublishedEntries();
+    expect(page.items[0]).toMatchObject({
+      title: "Safe release",
+      body: "The release text remains available.",
+    });
+    expect(page.items[0]).not.toHaveProperty("image");
+  });
+
+  it("falls back to a bounded text-only projection when an upstream refresh fails", async () => {
+    let available = true;
+    let currentTime = new Date("2026-08-26T12:00:00Z");
+    const changelog = createChangelogModule({
+      storage: {
+        async listPublished() {
+          if (!available) throw new Error("Notion is unavailable");
+          return {
+            items: [
+              {
+                ...entry({ title: "Release remains readable" }),
+                image: {
+                  src: "https://files.example/temporary",
+                  alt: "Release image",
+                  expiresAt: new Date("2026-08-26T12:02:00Z"),
+                },
+              },
+            ],
+          };
+        },
+      },
+      now: () => currentTime,
+    });
+
+    expect((await changelog.listPublishedEntries()).items[0]).toHaveProperty(
+      "image",
+    );
+    available = false;
+    currentTime = new Date("2026-08-26T12:03:00Z");
+    await expect(changelog.listPublishedEntries()).resolves.toMatchObject({
+      items: [{ title: "Release remains readable" }],
+    });
+    expect(
+      (await changelog.listPublishedEntries()).items[0],
+    ).not.toHaveProperty("image");
+  });
+});
+
+function entry(
+  overrides: Partial<StoredChangelogEntry> & { date?: ChangelogDate } = {},
+): StoredChangelogEntry {
+  return {
+    id: "entry",
+    slug: "entry",
+    date: "2026-08-01",
+    title: "Entry",
+    summary: "Summary",
+    body: "Body",
+    labels: ["Improved"],
+    images: [],
+    published: true,
+    createdAt: new Date("2026-08-01T00:00:00Z"),
+    updatedAt: new Date("2026-08-01T00:00:00Z"),
+    ...overrides,
+  };
+}