create-feedbax 0.1.0 → 0.2.0

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,
+  };
+}

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

@@ -0,0 +1,206 @@
+export type ChangelogDate = `${number}-${number}-${number}`;
+
+export interface ChangelogImage {
+  src: string;
+  alt: string;
+  expiresAt?: Date;
+}
+
+export interface StoredChangelogEntry {
+  id: string;
+  slug: string;
+  date: ChangelogDate;
+  title: string;
+  summary: string;
+  body: string;
+  labels: string[];
+  images: ChangelogImage[];
+  published: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export type PublicChangelogEntry = Pick<
+  StoredChangelogEntry,
+  "slug" | "date" | "title" | "summary" | "body" | "labels" | "updatedAt"
+> & { image?: ChangelogImage };
+
+export interface ChangelogPage {
+  items: PublicChangelogEntry[];
+  nextCursor?: string;
+}
+
+export interface ChangelogQuery {
+  cursor?: string;
+  label?: string;
+}
+
+export interface ChangelogStorage {
+  listPublished(query: ChangelogQuery): Promise<ChangelogPage>;
+}
+
+export interface ChangelogModule {
+  listPublishedEntries(query?: ChangelogQuery): Promise<ChangelogPage>;
+}
+
+export {
+  createNotionChangelogDataSource,
+  createNotionChangelogStorage,
+  validateNotionChangelogDataSource,
+  type ChangelogDataSourceConfiguration,
+  type ChangelogPropertyIds,
+  type NotionChangelogStorageOptions,
+} from "./notion-changelog";
+
+export function createChangelogModule({
+  storage,
+  now = () => new Date(),
+}: {
+  storage: ChangelogStorage;
+  now?: () => Date;
+}): ChangelogModule {
+  const textFallbacks = new Map<
+    string,
+    { cachedAt: number; page: ChangelogPage }
+  >();
+  return {
+    async listPublishedEntries(query = {}) {
+      const key = fallbackKey(query);
+      try {
+        const page = await storage.listPublished(query);
+        const projected = projectSafeImages(page, now());
+        rememberTextFallback(textFallbacks, key, page, now());
+        return projected;
+      } catch (error) {
+        const fallback = textFallbacks.get(key);
+        if (fallback && fallback.cachedAt + 86_400_000 > now().getTime()) {
+          return fallback.page;
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+function projectSafeImages(page: ChangelogPage, now: Date): ChangelogPage {
+  return {
+    ...page,
+    items: page.items.map((entry) =>
+      entry.image && !isSafeForProjection(entry.image, now)
+        ? withoutImage(entry)
+        : entry,
+    ),
+  };
+}
+
+function rememberTextFallback(
+  fallbacks: Map<string, { cachedAt: number; page: ChangelogPage }>,
+  key: string,
+  page: ChangelogPage,
+  now: Date,
+): void {
+  if (!fallbacks.has(key) && fallbacks.size >= 100) {
+    const oldestKey = fallbacks.keys().next().value as string | undefined;
+    if (oldestKey) fallbacks.delete(oldestKey);
+  }
+  fallbacks.set(key, {
+    cachedAt: now.getTime(),
+    page: {
+      ...page,
+      items: page.items.map(withoutImage),
+    },
+  });
+}
+
+function fallbackKey(query: ChangelogQuery): string {
+  return JSON.stringify({
+    cursor: query.cursor ?? null,
+    label: query.label ?? null,
+  });
+}
+
+function isSafeForProjection(image: ChangelogImage, now: Date): boolean {
+  if (!image.expiresAt) return true;
+  return image.expiresAt.getTime() > now.getTime() + 60_000;
+}
+
+function withoutImage(entry: PublicChangelogEntry): PublicChangelogEntry {
+  const textEntry = { ...entry };
+  delete textEntry.image;
+  return textEntry;
+}
+
+export function createInMemoryChangelogStorage(
+  initialEntries: StoredChangelogEntry[] = [],
+): ChangelogStorage {
+  const entries = structuredClone(initialEntries);
+  return {
+    async listPublished(query) {
+      const offset = decodeCursor(query.cursor, query.label);
+      const matching = entries
+        .filter(
+          (entry) =>
+            entry.published &&
+            (!query.label || entry.labels.includes(query.label)),
+        )
+        .sort(compareEntries);
+      const page = matching.slice(offset, offset + 20);
+      const nextOffset = offset + page.length;
+      return {
+        items: page.map(toPublicEntry),
+        ...(nextOffset < matching.length
+          ? { nextCursor: encodeCursor(nextOffset, query.label) }
+          : {}),
+      };
+    },
+  };
+}
+
+function compareEntries(
+  left: StoredChangelogEntry,
+  right: StoredChangelogEntry,
+): number {
+  return right.date.localeCompare(left.date) || left.id.localeCompare(right.id);
+}
+
+function toPublicEntry(entry: StoredChangelogEntry): PublicChangelogEntry {
+  const [image] = entry.images;
+  return {
+    slug: entry.slug,
+    date: entry.date,
+    title: entry.title,
+    summary: entry.summary,
+    body: entry.body,
+    labels: [...entry.labels],
+    updatedAt: new Date(entry.updatedAt),
+    ...(image ? { image: structuredClone(image) } : {}),
+  };
+}
+
+function encodeCursor(offset: number, label?: string): string {
+  return Buffer.from(JSON.stringify({ offset, label: label ?? null })).toString(
+    "base64url",
+  );
+}
+
+function decodeCursor(cursor: string | undefined, label?: string): number {
+  if (!cursor) return 0;
+  try {
+    const value: unknown = JSON.parse(
+      Buffer.from(cursor, "base64url").toString("utf8"),
+    );
+    if (!value || typeof value !== "object") throw new Error();
+    const offset = Reflect.get(value, "offset");
+    const cursorLabel = Reflect.get(value, "label");
+    if (
+      !Number.isSafeInteger(offset) ||
+      offset < 0 ||
+      cursorLabel !== (label ?? null)
+    ) {
+      throw new Error();
+    }
+    return offset as number;
+  } catch {
+    throw new Error("Changelog cursor does not match this timeline view.");
+  }
+}