create-feedbax 0.1.0 → 0.2.1

package/template/src/portal-feedback-server-function.ts

@@ -0,0 +1,96 @@
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest, getRequestIP } from "@tanstack/react-start/server";
+
+import {
+  requestParticipant,
+  createConfiguredFeedbackModule,
+  feedbackSubmissionLimits,
+} from "./feedback-runtime";
+import {
+  createPortalDraftManagement,
+  createPortalFeedbackSubmission,
+  createPortalPostSubmission,
+} from "./portal-feedback-submission";
+import {
+  createPortalSubmissionSecurity,
+  warnIfTurnstileDisabled,
+} from "./portal-feedback-runtime";
+import { runSafePortalMutation } from "./safe-public-failure";
+
+export const submitPortalFeedback = createServerFn({ method: "POST" })
+  .validator((input: unknown) => input)
+  .handler(async ({ data }) => {
+    const { env } = await import("cloudflare:workers");
+    warnIfTurnstileDisabled({
+      environment: env,
+      nodeEnv: import.meta.env.PROD ? "production" : "development",
+    });
+    const participant = await requestParticipant(getRequest());
+    return runSafePortalMutation(() =>
+      createPortalFeedbackSubmission({
+        feedback: createConfiguredFeedbackModule(participant),
+        limits: feedbackSubmissionLimits,
+        ...createPortalSubmissionSecurity({
+          environment: env,
+          rateLimitKey: getRequestIP() ?? "unknown-participant-ip",
+        }),
+      })(data),
+    );
+  });
+
+export const submitPortalPost = createServerFn({ method: "POST" })
+  .validator((input: unknown) => input)
+  .handler(async ({ data }) => {
+    const { env } = await import("cloudflare:workers");
+    const participant = await requestParticipant(getRequest());
+    return runSafePortalMutation(() =>
+      createPortalPostSubmission({
+        feedback: createConfiguredFeedbackModule(participant),
+        limits: feedbackSubmissionLimits,
+        ...createPortalSubmissionSecurity({
+          environment: env,
+          rateLimitKey: getRequestIP() ?? "unknown-participant-ip",
+        }),
+      })(data),
+    );
+  });
+
+export const editPortalFeedbackDraft = createServerFn({ method: "POST" })
+  .validator((input: unknown) => input)
+  .handler(({ data }) =>
+    runSafePortalMutation(() =>
+      createPortalDraftManagement({
+        feedback: createConfiguredFeedbackModule(),
+        limits: feedbackSubmissionLimits,
+      }).edit(data),
+    ),
+  );
+
+export const withdrawPortalFeedbackDraft = createServerFn({ method: "POST" })
+  .validator((input: unknown) => input)
+  .handler(({ data }) =>
+    runSafePortalMutation(() =>
+      createPortalDraftManagement({
+        feedback: createConfiguredFeedbackModule(),
+        limits: feedbackSubmissionLimits,
+      }).withdraw(data),
+    ),
+  );
+
+export const getPortalDraftPost = createServerFn({ method: "POST" })
+  .validator((input: unknown) => input)
+  .handler(({ data }) => {
+    if (!data || typeof data !== "object")
+      throw new Error("Draft Post request is invalid.");
+    const id = Reflect.get(data, "id");
+    const browserCapability = Reflect.get(data, "browserCapability");
+    if (typeof id !== "string" || typeof browserCapability !== "string")
+      throw new Error("Draft Post request is invalid.");
+    return runSafePortalMutation(() =>
+      createConfiguredFeedbackModule().getDraftPost({
+        id,
+        browserCapability:
+          browserCapability as import("@feedbax/feedback").BrowserCapability,
+      }),
+    );
+  });

package/template/src/portal-feedback-submission.test.ts

@@ -0,0 +1,307 @@
+import {
+  createFeedbackModule,
+  createNotionFeedbackModule,
+  type FeedbackPropertyIds,
+} from "@feedbax/feedback";
+import { describe, expect, it, vi } from "vitest";
+
+import { createCloudflareTurnstileVerifier } from "./cloudflare-turnstile";
+import {
+  createPortalDraftManagement,
+  createPortalFeedbackSubmission,
+} from "./portal-feedback-submission";
+
+const propertyIds: FeedbackPropertyIds = {
+  title: "title-id",
+  slug: "slug-id",
+  description: "description-id",
+  type: "type-id",
+  status: "status-id",
+  published: "published-id",
+  voteCount: "vote-count-id",
+  teamResponse: "team-response-id",
+  releaseNotesUrl: "release-notes-url-id",
+  submitterName: "submitter-name-id",
+  submitterEmail: "submitter-email-id",
+  source: "source-id",
+  externalId: "external-id",
+  editTokenHash: "edit-token-hash-id",
+  createdAt: "created-at-id",
+  updatedAt: "updated-at-id",
+};
+
+describe("Notion-only feedback submission", () => {
+  it("edits permitted draft fields through the portal mutation boundary", async () => {
+    const feedback = createFeedbackModule();
+    const submitted = await feedback.submitPost({
+      title: "Original title",
+      description: "Original description",
+      type: "General Feedback",
+    });
+    const drafts = createPortalDraftManagement({
+      feedback,
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+    });
+
+    await expect(
+      drafts.edit({
+        id: submitted.id,
+        browserCapability: submitted.browserCapability,
+        title: "Corrected title",
+        description: "Corrected description",
+        type: "Bug Report",
+      }),
+    ).resolves.toMatchObject({
+      id: submitted.id,
+      title: "Corrected title",
+      description: "Corrected description",
+      type: "Bug Report",
+    });
+  });
+
+  it("withdraws an eligible draft through the portal mutation boundary", async () => {
+    const feedback = createFeedbackModule();
+    const submitted = await feedback.submitPost({
+      title: "Withdraw this draft",
+      description: "This submission is no longer needed.",
+      type: "General Feedback",
+    });
+    const drafts = createPortalDraftManagement({
+      feedback,
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+    });
+
+    await expect(
+      drafts.withdraw({
+        id: submitted.id,
+        browserCapability: submitted.browserCapability,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("creates a New unpublished Post and returns its Browser Capability", async () => {
+    const submit = createPortalFeedbackSubmission({
+      feedback: createFeedbackModule(),
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      ...allowedSubmissionSecurity(),
+    });
+
+    const result = await submit({
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+      submitter: { name: "Ama", email: "ama@example.com" },
+    });
+
+    expect(result).toMatchObject({
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+      status: "New",
+      published: false,
+    });
+    expect(result.browserCapability).toEqual(expect.any(String));
+    expect(result.browserCapability.length).toBeGreaterThanOrEqual(32);
+  });
+
+  it("rejects invalid or out-of-bounds input before the Feedback module writes", async () => {
+    const notionRequest = vi.fn<typeof fetch>();
+    const submit = createPortalFeedbackSubmission({
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      ...allowedSubmissionSecurity(),
+    });
+
+    const completeSubmitter = { name: "Ama", email: "ama@example.com" };
+    const invalidInputs = [
+      null,
+      {},
+      {
+        title: "A title",
+        description: "A description",
+        type: "Bug Report",
+      },
+      {
+        title: "A title",
+        description: "A description",
+        type: "Bug Report",
+        submitter: { name: "Ama" },
+      },
+      {
+        title: "A title",
+        description: "A description",
+        type: "Bug Report",
+        submitter: { name: "Ama", email: "not-an-email" },
+      },
+      {
+        title: "",
+        description: "A description",
+        type: "Bug Report",
+        submitter: completeSubmitter,
+      },
+      {
+        title: "t".repeat(161),
+        description: "A description",
+        type: "Bug Report",
+        submitter: completeSubmitter,
+      },
+      {
+        title: "A title",
+        description: "",
+        type: "Bug Report",
+        submitter: completeSubmitter,
+      },
+      {
+        title: "A title",
+        description: "d".repeat(5_001),
+        type: "Bug Report",
+        submitter: completeSubmitter,
+      },
+      {
+        title: "A title",
+        description: "A description",
+        type: "Other",
+        submitter: completeSubmitter,
+      },
+    ];
+
+    for (const input of invalidInputs) {
+      await expect(submit(input)).rejects.toThrow(
+        "Feedback submission is invalid.",
+      );
+    }
+    expect(notionRequest).not.toHaveBeenCalled();
+  });
+
+  it("keeps required unverified profile details inside the private submission", async () => {
+    const feedback = createFeedbackModule();
+    const submit = createPortalFeedbackSubmission({
+      feedback,
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      ...allowedSubmissionSecurity(),
+    });
+
+    const submitted = await submit({
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+      submitter: { name: "Ama", email: "ama@example.com" },
+      published: true,
+      status: "Shipped",
+    });
+
+    expect(submitted.submitter).toEqual({
+      name: "Ama",
+      email: "ama@example.com",
+    });
+    expect(submitted).toMatchObject({ status: "New", published: false });
+    await expect(feedback.listPublicPosts()).resolves.toEqual({ items: [] });
+  });
+
+  it("rejects a burst-limited submission before Notion writes", async () => {
+    const notionRequest = vi.fn<typeof fetch>();
+    const submit = createPortalFeedbackSubmission({
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      rateLimiter: {
+        limit: vi.fn().mockResolvedValue({ success: false }),
+      },
+      rateLimitKey: "participant-ip",
+    });
+
+    await expect(
+      submit({
+        title: "Keyboard navigation",
+        description: "Let participants navigate without a mouse.",
+        type: "Feature Request",
+      }),
+    ).rejects.toThrow("Feedback submission rate limit exceeded.");
+    expect(notionRequest).not.toHaveBeenCalled();
+  });
+
+  it("fails closed when enabled Turnstile verification rejects the token", async () => {
+    const notionRequest = vi.fn<typeof fetch>();
+    const siteverifyRequest = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(Response.json({ success: false }));
+    const submit = createPortalFeedbackSubmission({
+      feedback: createNotionFeedbackModule({
+        token: "notion-token",
+        dataSourceId: "feedback-data-source",
+        propertyIds,
+        request: notionRequest,
+      }),
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      ...allowedSubmissionSecurity(),
+      turnstileVerifier: createCloudflareTurnstileVerifier({
+        secretKey: "private-turnstile-secret",
+        request: siteverifyRequest,
+      }),
+    });
+
+    const rejection = submit({
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+      submitter: { name: "Ama", email: "ama@example.com" },
+      turnstileToken: "private-participant-token",
+    });
+
+    await expect(rejection).rejects.toThrow(
+      "Feedback submission verification failed.",
+    );
+    await expect(rejection).rejects.not.toThrow("private-turnstile-secret");
+    await expect(rejection).rejects.not.toThrow("private-participant-token");
+    expect(notionRequest).not.toHaveBeenCalled();
+    expect(siteverifyRequest).toHaveBeenCalledOnce();
+  });
+
+  it("verifies every Turnstile-enabled submission and strips the token before storage", async () => {
+    const siteverifyRequest = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(Response.json({ success: true }));
+    const submit = createPortalFeedbackSubmission({
+      feedback: createFeedbackModule(),
+      limits: { maxTitleLength: 160, maxDescriptionLength: 5_000 },
+      ...allowedSubmissionSecurity(),
+      turnstileVerifier: createCloudflareTurnstileVerifier({
+        secretKey: "private-turnstile-secret",
+        request: siteverifyRequest,
+      }),
+    });
+
+    const result = await submit({
+      title: "Keyboard navigation",
+      description: "Let participants navigate without a mouse.",
+      type: "Feature Request",
+      submitter: { name: "Ama", email: "ama@example.com" },
+      turnstileToken: "private-participant-token",
+    });
+
+    expect(result).not.toHaveProperty("turnstileToken");
+    expect(siteverifyRequest).toHaveBeenCalledOnce();
+    const [url, init] = siteverifyRequest.mock.calls[0]!;
+    expect(url).toBe(
+      "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+    );
+    expect(init?.method).toBe("POST");
+    expect(String(init?.body)).toContain("response=private-participant-token");
+  });
+});
+
+function allowedSubmissionSecurity() {
+  return {
+    rateLimiter: { limit: vi.fn().mockResolvedValue({ success: true }) },
+    rateLimitKey: "participant-ip",
+  };
+}

package/template/src/portal-feedback-submission.ts

@@ -0,0 +1,224 @@
+import type {
+  BrowserCapability,
+  Post,
+  FeedbackModule,
+  SubmitPostInput,
+  SubmittedPost,
+} from "@feedbax/feedback";
+
+import type { TurnstileVerifier } from "./cloudflare-turnstile";
+import { isValidCommentEmail } from "./comment-profile";
+import { ActionablePortalFailure } from "./safe-public-failure";
+
+interface PortalFeedbackSubmissionOptions {
+  feedback: Pick<FeedbackModule, "submitPost">;
+  limits: {
+    maxTitleLength: number;
+    maxDescriptionLength: number;
+  };
+  rateLimiter: PortalSubmissionRateLimiter;
+  rateLimitKey: string;
+  turnstileVerifier?: TurnstileVerifier;
+}
+
+export function createPortalPostSubmission(
+  options: Omit<PortalFeedbackSubmissionOptions, "feedback"> & {
+    feedback: Pick<FeedbackModule, "submitPost">;
+  },
+): (input: unknown) => Promise<SubmittedPost> {
+  return async (input) => {
+    const { success } = await options.rateLimiter.limit({
+      key: options.rateLimitKey,
+    });
+    if (!success)
+      throw new ActionablePortalFailure("Post submission rate limit exceeded.");
+    if (options.turnstileVerifier)
+      await verifyTurnstile(
+        input,
+        options.rateLimitKey,
+        options.turnstileVerifier,
+      );
+    return options.feedback.submitPost(validateInput(input, options.limits));
+  };
+}
+
+export interface PortalSubmissionRateLimiter {
+  limit(options: { key: string }): Promise<{ success: boolean }>;
+}
+
+interface PortalDraftManagementOptions {
+  feedback: Pick<FeedbackModule, "editDraftPost" | "withdrawDraftPost">;
+  limits: PortalFeedbackSubmissionOptions["limits"];
+}
+
+export function createPortalDraftManagement({
+  feedback,
+  limits,
+}: PortalDraftManagementOptions): {
+  edit(input: unknown): Promise<Post>;
+  withdraw(input: unknown): Promise<void>;
+} {
+  return {
+    edit(input) {
+      const draft = validateDraftIdentity(input);
+      const value = input as Record<string, unknown>;
+      if (
+        !isBoundedRequiredText(value.title, limits.maxTitleLength) ||
+        !isBoundedRequiredText(
+          value.description,
+          limits.maxDescriptionLength,
+        ) ||
+        !isPostType(value.type)
+      ) {
+        throw invalidSubmission();
+      }
+      return feedback.editDraftPost({
+        ...draft,
+        title: value.title,
+        description: value.description,
+        type: value.type,
+      });
+    },
+    withdraw(input) {
+      return feedback.withdrawDraftPost(validateDraftIdentity(input));
+    },
+  };
+}
+
+export function createPortalFeedbackSubmission({
+  feedback,
+  limits,
+  rateLimiter,
+  rateLimitKey,
+  turnstileVerifier,
+}: PortalFeedbackSubmissionOptions): (
+  input: unknown,
+) => Promise<SubmittedPost> {
+  return async (input) => {
+    const { success } = await rateLimiter.limit({ key: rateLimitKey });
+    if (!success) {
+      throw new ActionablePortalFailure(
+        "Feedback submission rate limit exceeded.",
+      );
+    }
+    if (turnstileVerifier) {
+      await verifyTurnstile(input, rateLimitKey, turnstileVerifier);
+    }
+    return feedback.submitPost(validateInput(input, limits));
+  };
+}
+
+async function verifyTurnstile(
+  input: unknown,
+  remoteIp: string,
+  turnstileVerifier: TurnstileVerifier,
+): Promise<void> {
+  const token =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? Reflect.get(input, "turnstileToken")
+      : undefined;
+  if (typeof token !== "string" || token.length === 0) {
+    throw turnstileFailure();
+  }
+
+  const verified = await turnstileVerifier.verify({ token, remoteIp });
+  if (!verified) throw turnstileFailure();
+}
+
+function turnstileFailure(): Error {
+  return new ActionablePortalFailure(
+    "Feedback submission verification failed.",
+  );
+}
+
+function validateInput(
+  input: unknown,
+  limits: PortalFeedbackSubmissionOptions["limits"],
+): SubmitPostInput {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw invalidSubmission();
+  }
+  const value = input as Record<string, unknown>;
+  if (
+    !isBoundedRequiredText(value.title, limits.maxTitleLength) ||
+    !isBoundedRequiredText(value.description, limits.maxDescriptionLength) ||
+    !isPostType(value.type)
+  ) {
+    throw invalidSubmission();
+  }
+  if (!isValidSubmitter(value.submitter)) throw invalidSubmission();
+  if (
+    value.imageIds !== undefined &&
+    (!Array.isArray(value.imageIds) ||
+      value.imageIds.length > 4 ||
+      value.imageIds.some(
+        (id) => typeof id !== "string" || !/^[-a-f0-9]{36}$/.test(id),
+      ))
+  )
+    throw invalidSubmission();
+
+  return {
+    ...(value.imageIds ? { imageIds: value.imageIds as string[] } : {}),
+    title: value.title,
+    description: value.description,
+    type: value.type,
+    ...(value.submitter ? { submitter: value.submitter } : {}),
+  };
+}
+
+function validateDraftIdentity(input: unknown): {
+  id: string;
+  browserCapability: BrowserCapability;
+} {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw invalidSubmission();
+  }
+  const value = input as Record<string, unknown>;
+  if (
+    typeof value.id !== "string" ||
+    value.id.length === 0 ||
+    typeof value.browserCapability !== "string" ||
+    value.browserCapability.length === 0
+  ) {
+    throw invalidSubmission();
+  }
+  return {
+    id: value.id,
+    browserCapability: value.browserCapability as BrowserCapability,
+  };
+}
+
+function isBoundedRequiredText(
+  value: unknown,
+  maximum: number,
+): value is string {
+  return (
+    typeof value === "string" &&
+    value.trim().length > 0 &&
+    value.length <= maximum
+  );
+}
+
+function isPostType(value: unknown): value is SubmitPostInput["type"] {
+  return (
+    value === "Feature Request" ||
+    value === "Bug Report" ||
+    value === "General Feedback"
+  );
+}
+
+function isValidSubmitter(
+  value: unknown,
+): value is SubmitPostInput["submitter"] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const submitter = value as Record<string, unknown>;
+  return (
+    typeof submitter.name === "string" &&
+    submitter.name.trim().length > 0 &&
+    isValidCommentEmail(submitter.email)
+  );
+}
+
+function invalidSubmission(): Error {
+  return new ActionablePortalFailure("Feedback submission is invalid.");
+}

package/template/src/portal-head.ts

@@ -0,0 +1,58 @@
+import type { ProductConfiguration } from "@feedbax/config";
+
+export function createPortalHead(
+  product: ProductConfiguration,
+  stylesheetHref?: string,
+) {
+  return {
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: product.name },
+      { name: "description", content: product.description },
+      { property: "og:title", content: product.name },
+      { property: "og:description", content: product.description },
+      { property: "og:type", content: "website" },
+      ...(product.siteUrl
+        ? [{ property: "og:url", content: product.siteUrl }]
+        : []),
+    ],
+    links: [
+      { rel: "icon", href: product.logo },
+      ...(product.siteUrl ? [{ rel: "canonical", href: product.siteUrl }] : []),
+      ...(stylesheetHref ? [{ rel: "stylesheet", href: stylesheetHref }] : []),
+    ],
+  };
+}
+
+export function createRouteHead(
+  product: ProductConfiguration,
+  route: {
+    title?: string;
+    description?: string;
+    path: string;
+    noIndex?: boolean;
+  },
+) {
+  const title = route.title ? `${route.title} · ${product.name}` : product.name;
+  const description = route.description ?? product.description;
+  const canonical = product.siteUrl
+    ? new URL(route.path, ensureTrailingSlash(product.siteUrl)).toString()
+    : undefined;
+  return {
+    meta: [
+      { title },
+      { name: "description", content: description },
+      { property: "og:title", content: title },
+      { property: "og:description", content: description },
+      { property: "og:type", content: "website" },
+      ...(canonical ? [{ property: "og:url", content: canonical }] : []),
+      ...(route.noIndex ? [{ name: "robots", content: "noindex" }] : []),
+    ],
+    links: canonical ? [{ rel: "canonical", href: canonical }] : [],
+  };
+}
+
+function ensureTrailingSlash(value: string) {
+  return value.endsWith("/") ? value : `${value}/`;
+}