create-feedbax 0.2.0 → 0.2.2

package/template/src/feedback-runtime.ts

@@ -1,38 +1,148 @@
-import { createNotionFeedbackModule } from "@feedbax/feedback";
-import { cache } from "cloudflare:workers";
+import {
+  createImageModule,
+  createImageFeedbackModule,
+  createNotionImageReviewWriter,
+  createConnectedStore,
+  createConnectedFeedbackModule,
+  createObservedHistoryModule,
+  type VerifiedParticipant,
+} from "@feedbax/feedback";
+import { cache, env } from "cloudflare:workers";
 
 import {
   createInvalidatingFeedbackModule,
   createPublicCacheInvalidator,
 } from "./feedback-cache-invalidation";
 import feedbax from "./feedbax";
+import { createContentFeedbackModule } from "./configured-feedback";
+import { createPortalIntegration } from "./integration-runtime";
+import { createPublicReleaseFeedbackModule } from "./public-release-links";
+import { createConfiguredChangelogModule } from "./changelog-runtime";
 
 export const feedbackSubmissionLimits = {
   maxTitleLength: feedbax.submissions.maxTitleLength,
   maxDescriptionLength: feedbax.submissions.maxDescriptionLength,
 } as const;
 
-export function createConfiguredFeedbackModule() {
-  configuredFeedback ??= createInvalidatingFeedbackModule({
-    feedback: createNotionFeedbackModule({
-      votingEnabled: feedbax.features.voting,
-      commentsEnabled: feedbax.features.comments,
-      token: requiredEnvironmentValue("NOTION_TOKEN"),
-      dataSourceId: feedbax.notion.dataSourceId,
-      propertyIds: feedbax.notion.properties,
+export function createConfiguredContentFeedbackModule(
+  participant?: VerifiedParticipant,
+) {
+  return createContentFeedbackModule(
+    feedbax,
+    {
+      FEEDBAX_DB: env.FEEDBAX_DB,
+      NOTION_TOKEN: process.env.NOTION_TOKEN,
+      GITHUB_SERVICE_SECRET: env.GITHUB_SERVICE_SECRET,
+      ...(feedbax.provider === "github" && env.FEEDBAX_DB
+        ? {
+            getGitHubServiceSecret: () =>
+              configuredIntegration().portalSecret(),
+          }
+        : {}),
+    },
+    fetch,
+    participant,
+  );
+}
+
+export function createConfiguredFeedbackModule(
+  participant?: VerifiedParticipant,
+) {
+  const source = createConfiguredContentFeedbackModule(participant);
+  const history = feedbax.history ? configuredHistory(source) : undefined;
+  const content = history
+    ? { ...source, getPublicPost: history.observe }
+    : source;
+  const feedback = feedbax.connected
+    ? createConnectedFeedbackModule(content, getConnectedStore(), participant)
+    : content;
+  const images = feedbax.connected?.images
+    ? configuredImages(feedback, participant)
+    : undefined;
+  const withImages = images
+    ? createImageFeedbackModule(
+        feedback,
+        images,
+        feedbax.provider === "github"
+          ? undefined
+          : createNotionImageReviewWriter({
+              token: requiredEnvironmentValue("NOTION_TOKEN"),
+              reviewUrl: (id) => images.reviewUrl(id, feedbax.product.siteUrl!),
+            }),
+      )
+    : feedback;
+  return createInvalidatingFeedbackModule({
+    feedback: createPublicReleaseFeedbackModule({
+      feedback: withImages,
+      siteUrl: feedbax.product.siteUrl,
+      ...(feedbax.features.changelog && feedbax.changelog
+        ? { changelog: createConfiguredChangelogModule(true) }
+        : {}),
     }),
     invalidator: createPublicCacheInvalidator({
       purge: (options) => cache.purge(options),
     }),
   });
-  return configuredFeedback;
 }
 
-let configuredFeedback:
-  ReturnType<typeof createInvalidatingFeedbackModule> | undefined;
+export function configuredHistory(
+  feedback = createConfiguredContentFeedbackModule(),
+) {
+  if (!feedbax.history || !env.FEEDBAX_DB)
+    throw new Error(
+      "Observed history requires explicit history configuration and FEEDBAX_DB.",
+    );
+  return createObservedHistoryModule({ database: env.FEEDBAX_DB, feedback });
+}
 
 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;
+}
+
+export function configuredIntegration() {
+  if (!env.FEEDBAX_DB)
+    throw new Error("GitHub requires the FEEDBAX_DB D1 binding.");
+  return createPortalIntegration({
+    config: feedbax,
+    database: env.FEEDBAX_DB,
+    pairingSecret: env.GITHUB_PAIRING_SECRET,
+  });
+}

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

@@ -8,6 +8,41 @@ import {
 } from ".";
 
 describe("Changelog module", () => {
+  it("puts newer same-day entries first and uses Slug for exact ties", async () => {
+    const changelog = createChangelogModule({
+      storage: createInMemoryChangelogStorage([
+        entry({ id: "a", slug: "older-creation", date: "2026-10-15" }),
+        entry({
+          id: "z",
+          slug: "a-newer-creation",
+          date: "2026-10-15",
+          createdAt: new Date("2026-10-15T12:00:00Z"),
+        }),
+        entry({
+          id: "b",
+          slug: "z-newer-creation",
+          date: "2026-10-15",
+          createdAt: new Date("2026-10-15T12:00:00Z"),
+        }),
+        entry({
+          id: "c",
+          slug: "older-release-date",
+          date: "2026-10-14",
+          createdAt: new Date("2026-10-16T12:00:00Z"),
+        }),
+      ]),
+    });
+
+    expect(
+      (await changelog.listPublishedEntries()).items.map(({ slug }) => slug),
+    ).toEqual([
+      "a-newer-creation",
+      "z-newer-creation",
+      "older-creation",
+      "older-release-date",
+    ]);
+  });
+
   it("returns only Published Changelog Entries in deterministic Date order", async () => {
     const changelog = createChangelogModule({
       storage: createInMemoryChangelogStorage([

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

@@ -160,7 +160,11 @@ function compareEntries(
   left: StoredChangelogEntry,
   right: StoredChangelogEntry,
 ): number {
-  return right.date.localeCompare(left.date) || left.id.localeCompare(right.id);
+  return (
+    right.date.localeCompare(left.date) ||
+    right.createdAt.getTime() - left.createdAt.getTime() ||
+    left.slug.localeCompare(right.slug)
+  );
 }
 
 function toPublicEntry(entry: StoredChangelogEntry): PublicChangelogEntry {

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

@@ -183,7 +183,7 @@ describe("Notion Changelog query contract", () => {
       },
       sorts: [
         { property: propertyIds.date, direction: "descending" },
-        { timestamp: "created_time", direction: "ascending" },
+        { timestamp: "created_time", direction: "descending" },
         { property: propertyIds.slug, direction: "ascending" },
       ],
     });

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

@@ -168,7 +168,7 @@ export function createNotionChangelogStorage({
           },
           sorts: [
             { property: propertyIds.date, direction: "descending" },
-            { timestamp: "created_time", direction: "ascending" },
+            { timestamp: "created_time", direction: "descending" },
             { property: propertyIds.slug, direction: "ascending" },
           ],
         }),

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

@@ -1,10 +1,22 @@
 import { describe, expect, it } from "vitest";
 import {
+  assertRuntimeBindings,
   assertProductionConfiguration,
   defineFeedbax,
   type FeedbaxConfig,
 } from "./index";
 
+it("keeps observed history opt-in and requires explicitly provisioned D1 without enabling identity", () => {
+  expect(defineFeedbax(input).history).toBeUndefined();
+  const config = defineFeedbax({ ...input, history: true });
+  expect(config.connected).toBeUndefined();
+  expect(() => assertRuntimeBindings(config, {})).toThrow("FEEDBAX_DB");
+  expect(() => assertRuntimeBindings(config, { FEEDBAX_DB: {} })).not.toThrow();
+  expect(() =>
+    defineFeedbax({ ...input, history: "yes" } as unknown as FeedbaxConfig),
+  ).toThrow("history must be true or false");
+});
+
 const properties = Object.fromEntries(
   [
     "title",
@@ -24,7 +36,7 @@ const properties = Object.fromEntries(
     "createdAt",
     "updatedAt",
   ].map((key) => [key, `${key}-id`]),
-) as FeedbaxConfig["notion"]["properties"];
+) as NonNullable<FeedbaxConfig["notion"]>["properties"];
 const changelogProperties = Object.fromEntries(
   [
     "title",
@@ -63,6 +75,38 @@ const input: FeedbaxConfig = {
 };
 
 describe("Feedbax configuration", () => {
+  it("selects GitHub without Notion or verified identity and rejects mixed providers", () => {
+    const github = {
+      installationId: "portal-acme",
+      serviceUrl: "https://app.feedbax.example",
+      repository: { id: 123, owner: "acme", name: "feedback" },
+      botUserId: 456,
+    };
+    const configuration = {
+      ...input,
+      provider: "github",
+      notion: undefined,
+      changelog: undefined,
+      features: { ...input.features, changelog: false },
+      github,
+    };
+    const parsed = defineFeedbax(configuration as unknown as FeedbaxConfig);
+    expect(parsed).toMatchObject({ provider: "github", github });
+    expect(parsed.notion).toBeUndefined();
+    expect(parsed.connected).toBeUndefined();
+    expect(() =>
+      defineFeedbax({
+        ...configuration,
+        notion: input.notion,
+      } as unknown as FeedbaxConfig),
+    ).toThrow("one Content Provider");
+    expect(() =>
+      defineFeedbax({
+        ...configuration,
+        features: input.features,
+      } as unknown as FeedbaxConfig),
+    ).toThrow("disable Changelog");
+  });
   it("accepts the complete generated contract", () =>
     expect(defineFeedbax(input)).toEqual(input));
   it("requires enabled capability dependencies", () =>
@@ -109,3 +153,31 @@ it.each(["/portal", "//example.com", "http://example.com"])(
     ).toThrow("product.siteUrl must be an HTTPS URL");
   },
 );
+
+it("keeps Connected Profile opt-in and rejects secrets and unsafe handoff configuration", () => {
+  const connected = {
+    issuer: "https://app.example.com",
+    loginUrl: "https://app.example.com/login",
+  };
+  expect(defineFeedbax({ ...input, connected }).connected).toEqual(connected);
+  expect(defineFeedbax(input).connected).toBeUndefined();
+  expect(() =>
+    defineFeedbax({
+      ...input,
+      product: { ...input.product, siteUrl: undefined },
+      connected,
+    }),
+  ).toThrow("siteUrl");
+  expect(() =>
+    defineFeedbax({
+      ...input,
+      connected: { ...connected, loginUrl: "http://app.example.com/login" },
+    }),
+  ).toThrow("HTTPS");
+  expect(() =>
+    defineFeedbax({
+      ...input,
+      connected: { ...connected, secret: "never-public" },
+    } as unknown as FeedbaxConfig),
+  ).toThrow("Unknown connected key");
+});

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

@@ -51,10 +51,33 @@ export type ChangelogConfiguration = {
   readonly dataSourceId: string;
   readonly properties: ChangelogPropertyIds;
 };
-export type FeedbaxConfig = {
+export type EmailConfiguration = {
+  readonly provider: "cloudflare" | "resend" | "custom";
+  readonly from: string;
+  readonly endpoint?: string;
+};
+export type ConnectedConfiguration = {
+  readonly processing?: "small" | "standard";
+  readonly email?: EmailConfiguration;
+  readonly images?: boolean;
+  readonly issuer: string;
+  readonly loginUrl: string;
+};
+export type GitHubConfiguration = {
+  readonly installationId: string;
+  readonly serviceUrl: string;
+  readonly repository: {
+    readonly id: number;
+    readonly owner: string;
+    readonly name: string;
+  };
+  readonly botUserId: number;
+};
+type CommonConfiguration = {
+  readonly history?: boolean;
+  readonly connected?: ConnectedConfiguration;
   readonly product: ProductConfiguration;
   readonly theme: { readonly preset: string };
-  readonly notion: NotionConfiguration;
   readonly changelog?: ChangelogConfiguration;
   readonly features: PortalFeatures;
   readonly submissions: {
@@ -65,7 +88,25 @@ export type FeedbaxConfig = {
   readonly turnstile: { readonly enabled: boolean; readonly siteKey?: string };
 };
 
+export type FeedbaxConfig = CommonConfiguration &
+  (
+    | {
+        readonly provider?: "notion";
+        readonly notion: NotionConfiguration;
+        readonly github?: never;
+      }
+    | {
+        readonly provider: "github";
+        readonly github: GitHubConfiguration;
+        readonly notion?: never;
+      }
+  );
+
 const rootKeys = [
+  "history",
+  "provider",
+  "github",
+  "connected",
   "product",
   "theme",
   "notion",
@@ -110,6 +151,8 @@ export function defineFeedbax(config: FeedbaxConfig): FeedbaxConfig;
 export function defineFeedbax(config: unknown): FeedbaxConfig {
   const value = object(config, "Feedbax configuration");
   rejectUnknown(value, rootKeys, "Feedbax configuration");
+  if (value.history !== undefined && typeof value.history !== "boolean")
+    throw new Error("history must be true or false.");
   const product = object(value.product, "product");
   rejectUnknown(
     product,
@@ -124,13 +167,108 @@ export function defineFeedbax(config: unknown): FeedbaxConfig {
     ...optionalPublicUrl(product, "supportUrl"),
     ...optionalPublicUrl(product, "privacyUrl"),
   };
+  let connected: ConnectedConfiguration | undefined;
+  if (value.connected !== undefined) {
+    const input = object(value.connected, "connected");
+    rejectUnknown(
+      input,
+      ["issuer", "loginUrl", "email", "images", "processing"],
+      "connected",
+    );
+    const issuer = publicUrl(input.issuer, "connected.issuer", false);
+    const loginUrl = publicUrl(input.loginUrl, "connected.loginUrl", false);
+    if (!validatedProduct.siteUrl)
+      throw new Error("Connected Profile requires product.siteUrl.");
+    if (
+      new URL(loginUrl).username ||
+      new URL(loginUrl).password ||
+      new URL(loginUrl).hash
+    )
+      throw new Error(
+        "connected.loginUrl must not contain credentials or a fragment.",
+      );
+    let email: EmailConfiguration | undefined;
+    if (input.email !== undefined) {
+      const sender = object(input.email, "connected.email");
+      rejectUnknown(
+        sender,
+        ["provider", "from", "endpoint"],
+        "connected.email",
+      );
+      if (!["cloudflare", "resend", "custom"].includes(String(sender.provider)))
+        throw new Error(
+          "connected.email.provider must be cloudflare, resend, or custom.",
+        );
+      const from = text(sender.from, "connected.email.from");
+      if (from.length > 254 || !/^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/.test(from))
+        throw new Error(
+          "connected.email.from must be a plain sender email address.",
+        );
+      const endpoint =
+        sender.endpoint === undefined
+          ? undefined
+          : publicUrl(sender.endpoint, "connected.email.endpoint", false);
+      if (sender.provider === "custom" && !endpoint)
+        throw new Error("Custom email requires connected.email.endpoint.");
+      if (sender.provider !== "custom" && endpoint)
+        throw new Error("Only custom email uses connected.email.endpoint.");
+      if (
+        endpoint &&
+        (new URL(endpoint).username ||
+          new URL(endpoint).password ||
+          new URL(endpoint).hash)
+      )
+        throw new Error(
+          "Custom email endpoint must not contain credentials or a fragment.",
+        );
+      email = {
+        provider: sender.provider as EmailConfiguration["provider"],
+        from,
+        ...(endpoint ? { endpoint } : {}),
+      };
+    }
+    if (input.images !== undefined && typeof input.images !== "boolean")
+      throw new Error("connected.images must be true or false.");
+    if (
+      input.processing !== undefined &&
+      input.processing !== "small" &&
+      input.processing !== "standard"
+    )
+      throw new Error("connected.processing must be small or standard.");
+    connected = {
+      issuer,
+      loginUrl,
+      ...(input.processing !== undefined
+        ? { processing: input.processing }
+        : {}),
+      ...(email ? { email } : {}),
+      ...(input.images !== undefined ? { images: input.images } : {}),
+    };
+  }
   const theme = object(value.theme, "theme");
   rejectUnknown(theme, ["preset"], "theme");
-  const notion = storage(
-    value.notion,
-    feedbackPropertyKeys,
-    "notion",
-  ) as NotionConfiguration;
+  if (
+    value.provider !== undefined &&
+    !["notion", "github"].includes(String(value.provider))
+  )
+    throw new Error("provider must be notion or github.");
+  const githubMode = value.provider === "github";
+  if (
+    (githubMode && value.notion !== undefined) ||
+    (!githubMode && value.github !== undefined)
+  )
+    throw new Error("Select exactly one Content Provider: notion or github.");
+  const content: Pick<FeedbaxConfig, "provider" | "notion" | "github"> =
+    githubMode
+      ? { provider: "github", github: githubConfiguration(value.github) }
+      : {
+          ...(value.provider ? { provider: "notion" as const } : {}),
+          notion: storage(
+            value.notion,
+            feedbackPropertyKeys,
+            "notion",
+          ) as NotionConfiguration,
+        };
   const features = object(value.features, "features");
   rejectUnknown(features, featureKeys, "features");
   const validatedFeatures = Object.fromEntries(
@@ -140,6 +278,13 @@ export function defineFeedbax(config: unknown): FeedbaxConfig {
       return [key, features[key]];
     }),
   ) as PortalFeatures;
+  if (
+    githubMode &&
+    (validatedFeatures.changelog || value.changelog !== undefined)
+  )
+    throw new Error(
+      "GitHub Installations must disable Changelog (features.changelog: false) and remove Notion Changelog configuration.",
+    );
   const changelog =
     value.changelog === undefined
       ? undefined
@@ -172,8 +317,10 @@ export function defineFeedbax(config: unknown): FeedbaxConfig {
     throw new Error("Turnstile is enabled but turnstile.siteKey is missing.");
   return {
     product: validatedProduct,
+    ...(value.history !== undefined ? { history: value.history } : {}),
+    ...(connected ? { connected } : {}),
     theme: { preset: text(theme.preset, "theme.preset") },
-    notion,
+    ...content,
     ...(changelog ? { changelog } : {}),
     features: validatedFeatures,
     submissions: {
@@ -188,7 +335,7 @@ export function defineFeedbax(config: unknown): FeedbaxConfig {
       ),
     },
     turnstile: { enabled: turnstile.enabled, ...(siteKey ? { siteKey } : {}) },
-  };
+  } as FeedbaxConfig;
 }
 
 export function assertProductionConfiguration(
@@ -269,3 +416,52 @@ function publicUrl(
     `${label} must be ${allowRelative ? "root-relative or " : ""}an HTTPS URL.`,
   );
 }
+
+function githubConfiguration(value: unknown): GitHubConfiguration {
+  const input = object(value, "github");
+  rejectUnknown(
+    input,
+    ["installationId", "serviceUrl", "repository", "botUserId"],
+    "github",
+  );
+  const installationId = text(input.installationId, "github.installationId");
+  if (!/^[a-zA-Z0-9_-]{1,128}$/.test(installationId))
+    throw new Error(
+      "github.installationId must be a stable Installation identifier.",
+    );
+  const serviceUrl = publicUrl(input.serviceUrl, "github.serviceUrl", false);
+  const url = new URL(serviceUrl);
+  if (url.origin !== serviceUrl || url.username || url.password)
+    throw new Error(
+      "github.serviceUrl must be an HTTPS origin without a path or credentials.",
+    );
+  const repository = object(input.repository, "github.repository");
+  rejectUnknown(repository, ["id", "owner", "name"], "github.repository");
+  const owner = text(repository.owner, "github.repository.owner");
+  const name = text(repository.name, "github.repository.name");
+  if (!/^[A-Za-z0-9-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(name))
+    throw new Error("Use a valid GitHub repository owner and name.");
+  return {
+    installationId,
+    serviceUrl,
+    repository: {
+      id: positiveInteger(repository.id, "github.repository.id"),
+      owner,
+      name,
+    },
+    botUserId: positiveInteger(input.botUserId, "github.botUserId"),
+  };
+}
+
+export function assertRuntimeBindings(
+  config: FeedbaxConfig,
+  bindings: { FEEDBAX_DB?: unknown },
+) {
+  if (
+    (config.provider === "github" || config.connected || config.history) &&
+    !bindings.FEEDBAX_DB
+  )
+    throw new Error(
+      "This Installation requires the FEEDBAX_DB D1 binding. Provision D1 and apply the included migrations; D1 does not enable verified identity.",
+    );
+}

package/template/src/feedbax/feedback/comment-storage.ts

@@ -0,0 +1,38 @@
+import type { CommentAuthor } from "./index";
+
+export interface StoredComment {
+  recoverable?: boolean;
+  id: string;
+  postId: string;
+  discussionId: string;
+  body: string;
+  author: CommentAuthor;
+  createdAt: Date;
+  resolved: boolean;
+  scope?: "page" | "block";
+}
+
+export interface CommentStorage {
+  supportsIntentRecovery?: boolean;
+  createPageComment(input: {
+    submissionKey?: string;
+    recoveryCommentId?: string;
+    postId: string;
+    body: string;
+    displayName: string;
+  }): Promise<StoredComment>;
+  createDiscussionReply(input: {
+    submissionKey?: string;
+    recoveryCommentId?: string;
+    postId: string;
+    discussionId: string;
+    body: string;
+    displayName: string;
+  }): Promise<StoredComment>;
+  listPageComments(
+    postId: string,
+    cursor?: string,
+  ): Promise<{ items: StoredComment[]; nextCursor?: string }>;
+  updateComment(commentId: string, body: string): Promise<StoredComment>;
+  deleteComment(commentId: string): Promise<void>;
+}