@terrafirmagreg-team/discussions 0.0.0-stage → 1.2.0

package/src/hooks/comments/use-menu-item.ts

@@ -0,0 +1,29 @@
+'use client';
+
+import { createElement } from 'react';
+import { LogIn, LogOut } from 'lucide-react';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useCommentsEnabled } from './use-enabled';
+import { useCommentsSession } from './use-session';
+import {
+  redirectToCommentsLogin,
+  redirectToCommentsLogout,
+} from '../../lib/comments/auth';
+import type { SiteMenuItem } from '@terrafirmagreg-team/ui/components/blocks/nav/site-menu';
+
+const COMMENTS_API = '/api/comments';
+
+export function useCommentsMenuItem(): SiteMenuItem | false {
+  const t = useTranslations();
+  const enabled = useCommentsEnabled(`${COMMENTS_API}/config`);
+  const { session } = useCommentsSession(COMMENTS_API, { enabled });
+  if (!enabled) return false;
+  return {
+    label: session ? t('Sign out', { note: 'ui.sign_out' }) : t('Sign in', { note: 'ui.sign_in' }),
+    icon: session ? createElement(LogOut) : createElement(LogIn),
+    onClick: session
+      ? () => redirectToCommentsLogout(COMMENTS_API)
+      : () => redirectToCommentsLogin(COMMENTS_API),
+  };
+}
+

package/src/hooks/comments/use-session.ts

@@ -0,0 +1,21 @@
+'use client';
+
+import { useMemo } from 'react';
+import useSWRImmutable from 'swr/immutable';
+import type { AuthInfoWithRole } from '@fuma-comment/server';
+import { createCommentsClient } from '../../lib/comments/client';
+import { usePageThread } from './use-thread';
+
+export function useCommentsSession(
+  apiUrl = '/api/comments',
+  options?: { page?: string; enabled?: boolean },
+): { session: AuthInfoWithRole | null; isLoading: boolean } {
+  const thread = usePageThread(options?.page);
+  const client = useMemo(() => createCommentsClient(apiUrl), [apiUrl]);
+  const query = useSWRImmutable(
+    (options?.enabled ?? true) ? ['comments-session', thread] : null,
+    () => client.getAuthSession({ page: thread }).catch(() => null),
+  );
+  return { session: query.data ?? null, isLoading: query.isLoading };
+}
+

package/src/hooks/comments/use-thread.ts

@@ -0,0 +1,11 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+
+export function usePageThread(page?: string): string {
+  const pathname = usePathname();
+  const lang = useResolvedLang();
+  return (page ?? `${pathname}~${lang}`).replaceAll(/[/#]/g, '~');
+}
+

package/src/hooks/feedback/use-submission-storage.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { useEffect, useEffectEvent, useState } from 'react';
+
+export function useSubmissionStorage<Result>(
+  key: string,
+  validate: (v: unknown) => Result | null,
+) {
+  const storageKey = `docs-feedback-${key}`;
+  const [value, setValue] = useState<Result | null>(null);
+  const validateCallback = useEffectEvent(validate);
+
+  useEffect(() => {
+    const item = localStorage.getItem(storageKey);
+    if (item === null) return;
+    const validated = validateCallback(JSON.parse(item));
+
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- hydrate persisted submission once per key
+    if (validated !== null) setValue(validated);
+  }, [storageKey]);
+
+  return {
+    previous: value,
+    setPrevious(result: Result | null) {
+      if (result) localStorage.setItem(storageKey, JSON.stringify(result));
+      else localStorage.removeItem(storageKey);
+
+      setValue(result);
+    },
+  };
+}
+

package/src/lib/comments/auth.ts

@@ -0,0 +1,14 @@
+'use client';
+
+export function redirectToCommentsLogin(apiUrl: string): void {
+  const login = new URL(`${apiUrl}/oauth/login`, window.location.origin);
+  login.searchParams.set('return', window.location.href);
+  window.location.href = login.href;
+}
+
+export function redirectToCommentsLogout(apiUrl: string): void {
+  const logout = new URL(`${apiUrl}/oauth/logout`, window.location.origin);
+  logout.searchParams.set('return', window.location.href);
+  window.location.href = logout.href;
+}
+

package/src/lib/comments/client.ts

@@ -0,0 +1,29 @@
+'use client';
+import type { AuthInfoWithRole } from '@fuma-comment/server';
+
+export type CommentsClient = ReturnType<typeof createCommentsClient>;
+
+export function createCommentsClient(apiUrl = '/api/comments') {
+  async function fetcher<T = void>(url: string, init?: RequestInit): Promise<T> {
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      const message = await response.text();
+      let err = new Error(message);
+      try {
+        const obj = JSON.parse(message) as object;
+        if ('message' in obj && typeof obj.message === 'string') {
+          err = new Error(obj.message);
+        }
+      } catch {}
+      throw err;
+    }
+    return (await response.json()) as T;
+  }
+
+  return {
+    getAuthSession(options: { page: string }): Promise<AuthInfoWithRole> {
+      return fetcher(`${apiUrl}/${options.page}/auth`);
+    },
+  };
+}
+

package/src/lib/comments/github.ts

@@ -0,0 +1,35 @@
+import 'server-only';
+import { githubGraphql } from '@terrafirmagreg-team/data';
+import type { GDiscussion } from 'fuma-comment-github-discussions';
+
+const CREATE_DISCUSSION = `
+  mutation ($repositoryId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+    createDiscussion(
+      input: { repositoryId: $repositoryId, categoryId: $categoryId, title: $title, body: $body }
+    ) {
+      discussion { id url }
+    }
+  }`;
+
+export async function createDiscussion(
+  target: { repoId: string; categoryId: string },
+  title: string,
+  url: string | undefined,
+  token: string,
+): Promise<GDiscussion> {
+  const link = url ? ` ([${title}](${url}))` : '';
+  const data = await githubGraphql<{
+    createDiscussion: { discussion: { id: string; url: string } };
+  }>(
+    CREATE_DISCUSSION,
+    {
+      repositoryId: target.repoId,
+      categoryId: target.categoryId,
+      title,
+      body: `Comment thread for \`${title}\`${link}.`,
+    },
+    { token },
+  );
+  return data.createDiscussion.discussion as GDiscussion;
+}
+

package/src/lib/comments/local.ts

@@ -0,0 +1,168 @@
+import 'server-only';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type {
+  Comment,
+  StorageAdapter,
+  UserProfile,
+} from '@fuma-comment/server';
+import { env } from '@terrafirmagreg-team/data';
+
+interface LocalComment {
+  id: string;
+  page: string;
+  threadId?: string;
+  author: UserProfile;
+  content: object;
+  timestamp: string;
+  rates: Record<string, 1 | -1>;
+}
+
+interface LocalData {
+  comments: LocalComment[];
+}
+
+const dataFile = env('COMMENTS_DATA') || 'data/comments.json';
+const DEV_ROLE = { name: 'dev', canDelete: true };
+
+let state: LocalData | undefined;
+
+function data(): LocalData {
+  if (!state) {
+    state = { comments: [] };
+    try {
+      if (existsSync(/* turbopackIgnore: true */ dataFile))
+        state = JSON.parse(
+          readFileSync(/* turbopackIgnore: true */ dataFile, 'utf8'),
+        ) as LocalData;
+    } catch {}
+  }
+  return state;
+}
+
+function persist() {
+  mkdirSync(/* turbopackIgnore: true */ dirname(dataFile), { recursive: true });
+  writeFileSync(
+    /* turbopackIgnore: true */ dataFile,
+    `${JSON.stringify(state, null, 2)}\n`,
+  );
+}
+
+function find(id: string): LocalComment | undefined {
+  return data().comments.find((c) => c.id === id);
+}
+
+function toView(
+  c: LocalComment,
+  authId: string | undefined,
+  all: LocalComment[],
+): Comment {
+  let likes = 0;
+  let dislikes = 0;
+  for (const rate of Object.values(c.rates))
+    rate === 1 ? likes++ : dislikes++;
+  const rated = authId ? c.rates[authId] : undefined;
+  return {
+    id: c.id,
+    threadId: c.threadId,
+    page: c.page,
+    author: c.author,
+    content: c.content,
+    likes,
+    dislikes,
+    replies: all.filter((r) => r.threadId === c.id).length,
+    timestamp: new Date(c.timestamp),
+    liked: rated === undefined ? undefined : rated === 1,
+  };
+}
+
+export function createLocalComments(): StorageAdapter {
+  return {
+    getComments({ after, before, limit, sort, page, auth, thread }) {
+      const all = data().comments;
+      const authId = auth?.id;
+      return all
+        .filter(
+          (c) =>
+            (page === undefined || c.page === page) &&
+            (thread === undefined ? !c.threadId : c.threadId === thread) &&
+            (!before || new Date(c.timestamp) < before) &&
+            (!after || new Date(c.timestamp) > after),
+        )
+        .sort((a, b) =>
+          sort === 'oldest'
+            ? a.timestamp.localeCompare(b.timestamp)
+            : b.timestamp.localeCompare(a.timestamp),
+        )
+        .slice(0, limit)
+        .map((c) => toView(c, authId, all));
+    },
+    postComment({ auth, body, page }) {
+      const comment: LocalComment = {
+        id: `c_${crypto.randomUUID()}`,
+        page,
+        threadId: body.thread,
+        author: { id: auth.id, name: auth.id },
+        content: body.content,
+        timestamp: new Date().toISOString(),
+        rates: {},
+      };
+      data().comments.push(comment);
+      persist();
+      return toView(comment, auth.id, data().comments);
+    },
+    updateComment({ id, body }) {
+      const comment = find(id);
+      if (!comment) return;
+      comment.content = body.content;
+      persist();
+    },
+    deleteComment({ id }) {
+      const d = data();
+      const dead = new Set([id]);
+      let grew = true;
+      while (grew) {
+        grew = false;
+        for (const c of d.comments)
+          if (c.threadId && dead.has(c.threadId) && !dead.has(c.id)) {
+            dead.add(c.id);
+            grew = true;
+          }
+      }
+      d.comments = d.comments.filter((c) => !dead.has(c.id));
+      persist();
+    },
+    setRate({ id, auth, body }) {
+      const comment = find(id);
+      if (!comment) return;
+      comment.rates[auth.id] = body.like ? 1 : -1;
+      persist();
+    },
+    deleteRate({ id, auth }) {
+      const comment = find(id);
+      if (!comment) return;
+      delete comment.rates[auth.id];
+      persist();
+    },
+    getCommentAuthor({ id }) {
+      return find(id)?.author.id ?? null;
+    },
+    getRole({ auth }) {
+      return auth ? DEV_ROLE : null;
+    },
+    queryUsers({ name, limit }) {
+      const query = name.toLowerCase();
+      const users = new Map<string, UserProfile>();
+      for (const c of data().comments)
+        if (!users.has(c.author.id) && c.author.name.toLowerCase().includes(query))
+          users.set(c.author.id, c.author);
+      return [...users.values()].slice(0, limit);
+    },
+  };
+}
+
+let local: StorageAdapter | undefined;
+export function localComments(): StorageAdapter {
+  return (local ??= createLocalComments());
+}
+

package/src/lib/comments/server.ts

@@ -0,0 +1,204 @@
+import 'server-only';
+import { NextComment } from '@fuma-comment/server/next';
+type RouteRequest = Request & { nextUrl: { pathname: string } };
+import {
+  authConfig,
+  authCookie,
+  authEnabled,
+  authMode,
+  devAuthCookie,
+  devCookieAuth,
+} from '@terrafirmagreg-team/auth';
+import { env, githubAppToken } from '@terrafirmagreg-team/data';
+import {
+  createAuth,
+  createGitHubClient,
+  createStorage,
+  type GitHubDiscussionsConfig,
+} from 'fuma-comment-github-discussions';
+import { discussionsConfig } from '../config';
+import { createDiscussion } from './github';
+import { localComments } from './local';
+
+const APP_TOKEN = 'app';
+const CATEGORY = 'General';
+
+type DiscussionTarget = {
+  dataset: string;
+  repo: string;
+  repoId: string;
+  categoryId: string;
+};
+
+function datasets(): DiscussionTarget[] {
+  return Object.entries(discussionsConfig().datasets).flatMap(
+    ([dataset, cfg]) =>
+      cfg.repo && cfg.discussions
+        ? [
+            {
+              dataset,
+              repo: cfg.repo,
+              repoId: cfg.discussions.repoId,
+              categoryId: cfg.discussions.categoryId,
+            },
+          ]
+        : [],
+  );
+}
+
+function datasetSegs(): Set<string> {
+  return new Set(datasets().map(({ dataset }) => dataset));
+}
+
+function defaultDataset(): DiscussionTarget {
+  return datasets().find(({ dataset }) => dataset === 'dev')!;
+}
+
+function datasetOf(page: string) {
+  const segs = datasetSegs();
+  const seg = page.split('~').find((part) => segs.has(part));
+  return datasets().find(({ dataset }) => dataset === seg) ?? defaultDataset();
+}
+
+function pageToTitle(page: string): string {
+  const locales = new Set(discussionsConfig().knownLanguages);
+  const segs = datasetSegs();
+  const pretty = page
+    .split('~')
+    .slice(0, -1)
+    .filter((seg) => seg && !locales.has(seg) && !segs.has(seg))
+    .map((seg) =>
+      seg.replace(/[-_]+/g, ' ').replace(/\b\w/g, (ch) => ch.toUpperCase()),
+    );
+  return pretty.join(' › ') || 'Page';
+}
+
+type Client = ReturnType<typeof createGitHubClient>;
+type Storage = ReturnType<typeof createStorage>;
+
+let siteUrl: string | undefined;
+
+function currentSiteUrl(): string {
+  return siteUrl ?? discussionsConfig().siteUrl;
+}
+const storages = new Map<string, Storage>();
+
+function cfgFor(d: DiscussionTarget): GitHubDiscussionsConfig {
+  return {
+    repo: d.repo,
+    repoId: d.repoId,
+    categoryId: d.categoryId,
+    category: CATEGORY,
+    readToken: APP_TOKEN,
+    tokenSecret: authConfig().tokenSecret,
+    cookieName: authCookie,
+    pageToTitle,
+    pageToUrl: (page) => {
+      const segs = page.split('~');
+      segs.pop();
+      return `${currentSiteUrl()}/${segs.filter(Boolean).join('/')}`;
+    },
+  };
+}
+
+function wrapClient(d: DiscussionTarget, cfg: GitHubDiscussionsConfig): Client {
+  const base = createGitHubClient(cfg);
+  const wrapped = { ...base };
+  for (const key of Object.keys(base) as (keyof Client)[]) {
+    const fn = base[key] as (...args: unknown[]) => unknown;
+    (wrapped as Record<string, unknown>)[key] = async (...args: unknown[]) => {
+      if (args.includes(APP_TOKEN)) {
+        const token = await githubAppToken(d.repo);
+        args = args.map((arg) => (arg === APP_TOKEN ? token : arg));
+      }
+      return fn(...args);
+    };
+  }
+  wrapped.createDiscussion = async (title, url, token) => {
+    const resolved = token === APP_TOKEN ? await githubAppToken(d.repo) : token;
+    return createDiscussion(cfg, title, url, resolved);
+  };
+  return wrapped;
+}
+
+function storageFor(d: DiscussionTarget): Storage {
+  let storage = storages.get(d.dataset);
+  if (!storage) {
+    const cfg = cfgFor(d);
+    storage = createStorage(cfg, wrapClient(d, cfg));
+    storages.set(d.dataset, storage);
+  }
+  return storage;
+}
+
+type RouteHandler = (
+  req: RouteRequest,
+  context: { params: Promise<{ comment: string[] }> },
+) => Promise<Response>;
+
+export function commentsEnabled(): boolean {
+  return authEnabled() && datasets().length > 0;
+}
+
+export function feedbackEnabled(): boolean {
+  return commentsEnabled() && Boolean(env('APP_ID') && env('APP_PRIVATE_KEY'));
+}
+
+export function createCommentsRouter(
+  options: { siteUrl?: string } = {},
+):
+  | { GET: RouteHandler; POST: RouteHandler; PATCH: RouteHandler; DELETE: RouteHandler }
+  | undefined {
+  if (!commentsEnabled()) return undefined;
+  siteUrl = options.siteUrl ?? discussionsConfig().siteUrl;
+
+  if (authMode() === 'dev' || !(env('APP_ID') && env('APP_PRIVATE_KEY')))
+    return NextComment({
+      role: 'database',
+      mention: { enabled: true },
+      storage: localComments(),
+      auth: devCookieAuth({ cookieName: devAuthCookie }),
+    }) as unknown as { GET: RouteHandler; POST: RouteHandler; PATCH: RouteHandler; DELETE: RouteHandler };
+
+  const dispatch = (page: string | undefined) =>
+    storageFor(datasetOf(page ?? ''));
+
+  const storage = {
+    getComments: (args: Parameters<Storage['getComments']>[0]) =>
+      dispatch(args.page as string | undefined).getComments(args),
+    postComment: (args: Parameters<Storage['postComment']>[0]) =>
+      dispatch(args.page as string | undefined).postComment(args),
+    updateComment: (args: Parameters<Storage['updateComment']>[0]) =>
+      dispatch(args.page).updateComment(args),
+    deleteComment: (args: Parameters<Storage['deleteComment']>[0]) =>
+      dispatch(args.page).deleteComment(args),
+    setRate: (args: Parameters<Storage['setRate']>[0]) =>
+      dispatch(args.page).setRate(args),
+    deleteRate: (args: Parameters<Storage['deleteRate']>[0]) =>
+      dispatch(args.page).deleteRate(args),
+    getCommentAuthor: async (
+      args: Parameters<Storage['getCommentAuthor']>[0],
+    ) => {
+      for (const d of datasets()) {
+        const author = await Promise.resolve(
+          storageFor(d).getCommentAuthor(args),
+        ).catch(() => null);
+        if (author) return author;
+      }
+      return null;
+    },
+    getRole: (args: Parameters<Storage['getRole']>[0]) =>
+      storageFor(datasetOf(args.page)).getRole(args),
+    queryUsers: (args: Parameters<NonNullable<Storage['queryUsers']>>[0]) =>
+      dispatch(args.page).queryUsers?.(args) ?? [],
+  } as Storage;
+
+  const cfg = cfgFor(defaultDataset());
+  return NextComment({
+    role: 'database',
+    mention: { enabled: true },
+    storage,
+    auth: createAuth(cfg, wrapClient(defaultDataset(), cfg)),
+  }) as unknown as { GET: RouteHandler; POST: RouteHandler; PATCH: RouteHandler; DELETE: RouteHandler };
+}
+

package/src/lib/comments.ts

@@ -0,0 +1,18 @@
+import type { ComponentType } from 'react';
+
+export interface CommentsViewProps {
+  page?: string;
+}
+
+export type CommentsView = ComponentType<CommentsViewProps>;
+
+let view: CommentsView | undefined;
+
+export function registerCommentsView(component: CommentsView): void {
+  view = component;
+}
+
+export function commentsView(): CommentsView | undefined {
+  return view;
+}
+

package/src/lib/config.ts

@@ -0,0 +1,27 @@
+export type DiscussionsDataset = {
+  repo?: string;
+  discussions?: { repoId: string; categoryId: string };
+};
+
+export type DiscussionsConfig = {
+  datasets: Record<string, DiscussionsDataset>;
+  siteUrl: string;
+  knownLanguages: readonly string[];
+};
+
+let config: DiscussionsConfig | undefined;
+
+export function registerDiscussionsConfig(
+  input: Partial<DiscussionsConfig>,
+): void {
+  config = { ...config, ...input } as DiscussionsConfig;
+}
+
+export function discussionsConfig(): DiscussionsConfig {
+  if (!config) {
+    throw new Error(
+      'Discussions config is not registered: call registerDiscussionsConfig() at app startup.',
+    );
+  }
+  return config;
+}

package/src/lib/feedback-schema.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod/mini';
+
+export const blockFeedback = z.object({
+  url: z.url(),
+  blockId: z.string(),
+  message: z.string(),
+
+  blockBody: z.string(),
+});
+
+export const pageFeedback = z.object({
+  opinion: z.enum(['good', 'bad']),
+  url: z.url(),
+  message: z.string(),
+});
+
+export const actionResponse = z.object({
+  githubUrl: z.optional(z.string()),
+});
+
+export type BlockFeedback = z.infer<typeof blockFeedback>;
+export type PageFeedback = z.infer<typeof pageFeedback>;
+export type ActionResponse = z.infer<typeof actionResponse>;
+

package/src/lib/feedback.ts

@@ -0,0 +1,74 @@
+'use server';
+import { githubAppToken } from '@terrafirmagreg-team/data';
+import { createGitHubClient } from 'fuma-comment-github-discussions';
+import { discussionsConfig } from './config';
+import { createDiscussion } from './comments/github';
+import {
+  blockFeedback,
+  pageFeedback,
+  type ActionResponse,
+  type BlockFeedback,
+  type PageFeedback,
+} from './feedback-schema';
+
+function targetOf(pathname: string) {
+  const datasets = discussionsConfig().datasets;
+  const seg = pathname.split('/').find((part) => part in datasets);
+  const cfg = (seg && datasets[seg]) || datasets.dev;
+  if (!cfg?.repo || !cfg.discussions) return undefined;
+  return {
+    repo: cfg.repo,
+    repoId: cfg.discussions.repoId,
+    categoryId: cfg.discussions.categoryId,
+    category: 'General',
+  };
+}
+
+export async function onPageFeedbackAction(
+  feedback: PageFeedback,
+): Promise<ActionResponse> {
+  feedback = pageFeedback.parse(feedback);
+  const { pathname } = new URL(feedback.url);
+
+  return createDiscussionThread(
+    pathname,
+    `[${feedback.opinion}] ${feedback.message}\n\n> Forwarded from user feedback.`,
+  );
+}
+
+export async function onBlockFeedbackAction(
+  feedback: BlockFeedback,
+): Promise<ActionResponse> {
+  feedback = blockFeedback.parse(feedback);
+  const url = new URL(feedback.url);
+  url.hash = feedback.blockId;
+
+  return createDiscussionThread(
+    url.pathname,
+    `> ${feedback.blockBody}\n\n${feedback.message}\n\n> [Forwarded from user feedback](${url.href}).`,
+  );
+}
+
+async function createDiscussionThread(
+  pageId: string,
+  body: string,
+): Promise<ActionResponse> {
+  const target = targetOf(pageId);
+  if (!target) return { githubUrl: '' };
+  const github = createGitHubClient(target);
+  const auth = await githubAppToken(target.repo);
+  const title = `Feedback for ${pageId}`;
+
+  const discussion =
+    (await github.findDiscussion(title, auth)) ??
+    (await createDiscussion(
+      target,
+      title,
+      `${discussionsConfig().siteUrl}${pageId}`,
+      auth,
+    ));
+  await github.addComment(discussion.id, body, auth);
+
+  return { githubUrl: discussion.url };
+}
+