create-feedbax 0.1.0 → 0.2.1

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

package/template/src/feedbax/changelog/notion-changelog.test.ts

@@ -0,0 +1,395 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createChangelogModule,
+  createNotionChangelogDataSource,
+  createNotionChangelogStorage,
+  validateNotionChangelogDataSource,
+  type ChangelogPropertyIds,
+} from ".";
+
+const propertyIds: ChangelogPropertyIds = {
+  title: "title-id",
+  slug: "slug-id",
+  date: "date-id",
+  summary: "summary-id",
+  body: "body-id",
+  labels: "labels-id",
+  image: "image-id",
+  published: "published-id",
+  createdAt: "created-id",
+  updatedAt: "updated-id",
+};
+
+describe("Notion Changelog Data Source contract", () => {
+  it("creates an empty sibling data source with the canonical schema", async () => {
+    const request = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(Response.json(notionDataSource()));
+
+    await expect(
+      createNotionChangelogDataSource({
+        token: "token",
+        databaseId: "feedbax-database",
+        request,
+      }),
+    ).resolves.toEqual({
+      databaseId: "feedbax-database",
+      dataSourceId: "changelog-source",
+      propertyIds,
+    });
+    const body = JSON.parse(String(request.mock.calls[0]?.[1]?.body));
+    expect(request.mock.calls[0]?.[0]).toBe(
+      "https://api.notion.com/v1/data_sources",
+    );
+    expect(body.parent).toEqual({ database_id: "feedbax-database" });
+    expect(body.properties).toMatchObject({
+      Title: { title: {} },
+      Slug: { rich_text: {} },
+      Date: { date: {} },
+      Summary: { rich_text: {} },
+      Body: { rich_text: {} },
+      Labels: { multi_select: { options: [] } },
+      Image: { files: {} },
+      Published: { checkbox: {} },
+      "Created At": { created_time: {} },
+      "Updated At": { last_edited_time: {} },
+    });
+    expect(request).toHaveBeenCalledTimes(1);
+  });
+
+  it("accepts a compatible data source in another database and reports wrong types", async () => {
+    const validRequest = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(
+        Response.json(notionDataSource({ databaseId: "marketing-database" })),
+      );
+    await expect(
+      validateNotionChangelogDataSource({
+        token: "token",
+        dataSourceId: "changelog-source",
+        propertyIds,
+        request: validRequest,
+      }),
+    ).resolves.toMatchObject({ databaseId: "marketing-database" });
+
+    const invalid = notionDataSource();
+    invalid.properties.Summary.type = "number";
+    await expect(
+      validateNotionChangelogDataSource({
+        token: "token",
+        dataSourceId: "changelog-source",
+        propertyIds,
+        request: vi
+          .fn<typeof fetch>()
+          .mockResolvedValue(Response.json(invalid)),
+      }),
+    ).rejects.toThrow(
+      'Change the property configured as "Summary" (ID "summary-id") from "number" to "rich_text"',
+    );
+  });
+});
+
+describe("Notion Changelog query contract", () => {
+  it("maps projected properties when Notion keys them by property name", async () => {
+    const page = notionPage();
+    page.properties = Object.fromEntries(
+      Object.entries(page.properties).map(([id, property]) => [
+        id === propertyIds.title
+          ? "Title"
+          : id === propertyIds.slug
+            ? "Slug"
+            : id === propertyIds.date
+              ? "Date"
+              : id === propertyIds.summary
+                ? "Summary"
+                : id === propertyIds.body
+                  ? "Body"
+                  : id === propertyIds.labels
+                    ? "Labels"
+                    : "Image",
+        { ...property, id },
+      ]),
+    );
+    const storage = createNotionChangelogStorage({
+      token: "token",
+      dataSourceId: "changelog-source",
+      propertyIds,
+      request: vi
+        .fn<typeof fetch>()
+        .mockResolvedValueOnce(
+          Response.json({ results: [page], has_more: false }),
+        ),
+    });
+
+    await expect(storage.listPublished({})).resolves.toMatchObject({
+      items: [{ slug: "entry", title: "Entry", body: "Body text" }],
+    });
+  });
+
+  it("queries only Published entries with public properties, ordering, Labels, and cursors", async () => {
+    const request = vi.fn<typeof fetch>().mockResolvedValueOnce(
+      Response.json({
+        results: [notionPage()],
+        has_more: true,
+        next_cursor: "notion-next",
+      }),
+    );
+    const storage = createNotionChangelogStorage({
+      token: "token",
+      dataSourceId: "changelog-source",
+      propertyIds,
+      request,
+    });
+
+    await expect(
+      storage.listPublished({ cursor: "notion-current", label: "Improved" }),
+    ).resolves.toMatchObject({
+      items: [
+        {
+          slug: "entry",
+          title: "Entry",
+          summary: "Summary text",
+          body: "Body text",
+          labels: ["Improved"],
+        },
+      ],
+      nextCursor: "notion-next",
+    });
+    const [url, init] = request.mock.calls[0] ?? [];
+    const query = new URL(String(url)).searchParams.getAll("filter_properties");
+    expect(query).toEqual([
+      propertyIds.title,
+      propertyIds.slug,
+      propertyIds.date,
+      propertyIds.summary,
+      propertyIds.body,
+      propertyIds.labels,
+      propertyIds.image,
+      propertyIds.updatedAt,
+    ]);
+    expect(query).not.toContain(propertyIds.published);
+    expect(JSON.parse(String(init?.body))).toEqual({
+      page_size: 20,
+      start_cursor: "notion-current",
+      filter: {
+        and: [
+          { property: propertyIds.published, checkbox: { equals: true } },
+          {
+            property: propertyIds.labels,
+            multi_select: { contains: "Improved" },
+          },
+        ],
+      },
+      sorts: [
+        { property: propertyIds.date, direction: "descending" },
+        { timestamp: "created_time", direction: "ascending" },
+        { property: propertyIds.slug, direction: "ascending" },
+      ],
+    });
+  });
+
+  it("maps one temporary File reference with its expiry and reports additional files", async () => {
+    const page = notionPage();
+    page.properties[propertyIds.image] = {
+      type: "files",
+      files: [
+        {
+          name: "release.png",
+          type: "file",
+          file: {
+            url: "https://files.notion.example/release.png",
+            expiry_time: "2026-08-26T14:00:00.000Z",
+          },
+        },
+        {
+          name: "extra.png",
+          type: "external",
+          external: { url: "https://cdn.example/extra.png" },
+        },
+      ],
+    };
+    const diagnostics: string[] = [];
+    const storage = createNotionChangelogStorage({
+      token: "token",
+      dataSourceId: "changelog-source",
+      propertyIds,
+      request: vi
+        .fn<typeof fetch>()
+        .mockResolvedValueOnce(
+          Response.json({ results: [page], has_more: false }),
+        ),
+      onDiagnostic: (message) => diagnostics.push(message),
+    });
+
+    await expect(storage.listPublished({})).resolves.toMatchObject({
+      items: [
+        {
+          title: "Entry",
+          image: {
+            src: "https://files.notion.example/release.png",
+            alt: "Entry image",
+            expiresAt: new Date("2026-08-26T14:00:00.000Z"),
+          },
+        },
+      ],
+    });
+    expect(diagnostics).toEqual([
+      'Changelog Entry "entry" has 2 Image files; only the first file is in the public contract.',
+    ]);
+  });
+
+  it("maps a temporary File reference's exact expiry while preserving entry text", async () => {
+    const page = notionPage();
+    page.properties[propertyIds.image] = {
+      type: "files",
+      files: [
+        {
+          name: "release.png",
+          type: "file",
+          file: {
+            url: "https://files.notion.example/release.png",
+            expiry_time: "2026-08-26T12:00:30.000Z",
+          },
+        },
+      ],
+    };
+    const storage = createNotionChangelogStorage({
+      token: "token",
+      dataSourceId: "changelog-source",
+      propertyIds,
+      request: vi
+        .fn<typeof fetch>()
+        .mockResolvedValueOnce(
+          Response.json({ results: [page], has_more: false }),
+        ),
+    });
+
+    await expect(storage.listPublished({})).resolves.toMatchObject({
+      items: [
+        {
+          title: "Entry",
+          summary: "Summary text",
+          body: "Body text",
+          image: { expiresAt: new Date("2026-08-26T12:00:30.000Z") },
+        },
+      ],
+    });
+  });
+
+  it("refreshes a discarded temporary reference and contains malformed Image data", async () => {
+    const expiringPage = notionPage();
+    expiringPage.properties[propertyIds.image] = {
+      type: "files",
+      files: [
+        {
+          type: "file",
+          file: {
+            url: "https://files.notion.example/release.png",
+            expiry_time: "2026-08-26T12:00:30.000Z",
+          },
+        },
+      ],
+    };
+    const refreshedPage = notionPage();
+    refreshedPage.properties[propertyIds.image] = {
+      type: "files",
+      files: [
+        {
+          type: "file",
+          file: {
+            url: "https://files.notion.example/release.png",
+            expiry_time: "2026-08-26T14:00:00.000Z",
+          },
+        },
+      ],
+    };
+    const malformedPage = notionPage();
+    malformedPage.properties[propertyIds.image] = {
+      type: "files",
+      files: ["not-a-file"],
+    };
+    const request = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(
+        Response.json({ results: [expiringPage], has_more: false }),
+      )
+      .mockResolvedValueOnce(
+        Response.json({ results: [refreshedPage], has_more: false }),
+      )
+      .mockResolvedValueOnce(
+        Response.json({ results: [malformedPage], has_more: false }),
+      );
+    const storage = createNotionChangelogStorage({
+      token: "token",
+      dataSourceId: "changelog-source",
+      propertyIds,
+      request,
+      onDiagnostic: vi.fn(),
+    });
+    const changelog = createChangelogModule({
+      storage,
+      now: () => new Date("2026-08-26T12:00:00.000Z"),
+    });
+
+    expect(
+      (await changelog.listPublishedEntries()).items[0],
+    ).not.toHaveProperty("image");
+    expect((await changelog.listPublishedEntries()).items[0]).toHaveProperty(
+      "image.src",
+      "https://files.notion.example/release.png",
+    );
+    await expect(changelog.listPublishedEntries()).resolves.toMatchObject({
+      items: [{ title: "Entry", summary: "Summary text", body: "Body text" }],
+    });
+  });
+});
+
+function notionDataSource({ databaseId = "feedbax-database" } = {}) {
+  const properties = Object.fromEntries(
+    [
+      ["Title", propertyIds.title, "title"],
+      ["Slug", propertyIds.slug, "rich_text"],
+      ["Date", propertyIds.date, "date"],
+      ["Summary", propertyIds.summary, "rich_text"],
+      ["Body", propertyIds.body, "rich_text"],
+      ["Labels", propertyIds.labels, "multi_select"],
+      ["Image", propertyIds.image, "files"],
+      ["Published", propertyIds.published, "checkbox"],
+      ["Created At", propertyIds.createdAt, "created_time"],
+      ["Updated At", propertyIds.updatedAt, "last_edited_time"],
+    ].map(([name, id, type]) => [name, { id, name, type }]),
+  );
+  return {
+    id: "changelog-source",
+    parent: { type: "database_id", database_id: databaseId },
+    properties,
+  };
+}
+
+function notionPage() {
+  return {
+    id: "page-id",
+    created_time: "2026-08-01T00:00:00.000Z",
+    last_edited_time: "2026-08-02T00:00:00.000Z",
+    properties: {
+      [propertyIds.title]: { type: "title", title: [text("Entry")] },
+      [propertyIds.slug]: { type: "rich_text", rich_text: [text("entry")] },
+      [propertyIds.date]: { type: "date", date: { start: "2026-08-01" } },
+      [propertyIds.summary]: {
+        type: "rich_text",
+        rich_text: [text("Summary "), text("text")],
+      },
+      [propertyIds.body]: { type: "rich_text", rich_text: [text("Body text")] },
+      [propertyIds.labels]: {
+        type: "multi_select",
+        multi_select: [{ name: "Improved" }],
+      },
+      [propertyIds.image]: { type: "files", files: [] as unknown[] },
+    },
+  };
+}
+
+function text(content: string) {
+  return { type: "text", plain_text: content, text: { content } };
+}