Comments Plugin

import { stack } from "@btst/stack"
import { commentsBackendPlugin } from "@btst/stack/plugins/comments/api"

const { handler, dbSchema } = stack({
  basePath: "/api/data",
  plugins: {
    comments: commentsBackendPlugin({
      // Automatically approve comments (default: false — requires moderation)
      autoApprove: false,

      // Resolve author display name and avatar from your auth system
      resolveUser: async (authorId) => {
        const user = await db.users.findById(authorId)
        return user
          ? { name: user.displayName, avatarUrl: user.avatarUrl }
          : null
      },

      // Lifecycle hooks — see Security section below for required configuration
      onBeforeList: async (query, ctx) => {
        // Restrict non-approved status filters (pending/spam) to admin sessions only
        if (query.status && query.status !== "approved") {
          const session = await getSession(ctx.headers)
          if (!session?.user?.isAdmin) throw new Error("Admin access required")
        }
      },
      onBeforePost: async (comment, ctx) => {
        // Required: resolve the authorId from the authenticated session
        // Never use any ID supplied by the client
        const session = await getSession(ctx.headers)
        if (!session?.user) throw new Error("Authentication required")
        return { authorId: session.user.id }
      },
      onAfterPost: async (comment, ctx) => {
        console.log("New comment posted:", comment.id)
      },
      onBeforeEdit: async (commentId, update, ctx) => {
        // Required: verify the caller owns the comment they are editing.
        // Without this hook all edit requests return 403 by default.
        const session = await getSession(ctx.headers)
        if (!session?.user) throw new Error("Authentication required")
        const comment = await db.comments.findById(commentId)
        if (comment?.authorId !== session.user.id && !session.user.isAdmin)
          throw new Error("Forbidden")
      },
      onBeforeLike: async (commentId, authorId, ctx) => {
        // Verify authorId matches the authenticated session
        const session = await getSession(ctx.headers)
        if (!session?.user) throw new Error("Authentication required")
        if (authorId !== session.user.id) throw new Error("Forbidden")
      },
      onBeforeStatusChange: async (commentId, status, ctx) => {
        // Require admin/moderator role for the moderation endpoint
        const session = await getSession(ctx.headers)
        if (!session?.user?.isAdmin) throw new Error("Admin access required")
      },
      onAfterApprove: async (comment, ctx) => {
        // Send notification to comment author
        await sendApprovalEmail(comment.authorId)
      },
      onBeforeDelete: async (commentId, ctx) => {
        // Require admin/moderator role — the Delete button is client-side only
        const session = await getSession(ctx.headers)
        if (!session?.user?.isAdmin) throw new Error("Admin access required")
      },

      // Required to show authors their own pending comments after posting.
      // Without this hook the feature is disabled — client-supplied
      // currentUserId is ignored server-side to prevent impersonation.
      resolveCurrentUserId: async (ctx) => {
        const session = await getSession(ctx.headers)
        return session?.user?.id ?? null
      },
    })
  },
  adapter: (db) => createMemoryAdapter(db)({})
})

export { handler, dbSchema }

import { createStackClient } from "@btst/stack/client"
import { commentsClientPlugin } from "@btst/stack/plugins/comments/client"
import { QueryClient } from "@tanstack/react-query"

const getBaseURL = () =>
  process.env.BASE_URL || "http://localhost:3000"

export const getStackClient = (queryClient: QueryClient) => {
  const baseURL = getBaseURL()
  return createStackClient({
    plugins: {
      comments: commentsClientPlugin({
        apiBaseURL: baseURL,
        apiBasePath: "/api/data",
        queryClient,
        siteBaseURL: baseURL,
        siteBasePath: "/pages",
        // optional headers + lifecycle hooks:
        // headers: { cookie: request.headers.get("cookie") ?? "" },
        // hooks: {
        //   beforeLoadModeration: async (ctx) => { ... },
        //   beforeLoadUserComments: async (ctx) => { ... },
        //   onLoadError: async (error, ctx) => { ... },
        // },
      }),
    },
    queryClient,
  })
}

import { CommentThread } from "@btst/stack/plugins/comments/client/components"

<CommentThread
  resourceId={post.slug}          // Unique identifier for the resource being commented on
  resourceType="blog-post"        // Namespace — avoids ID collisions across resource types
  apiBaseURL="https://example.com"
  apiBasePath="/api/data"
  currentUserId={session?.user?.id}  // Own-comment affordances (edit, delete, pending badge, dedup likes)
  loginHref="/login"              // Shows "Please log in to comment" when currentUserId is not set
  components={{
    // Optional: replace the plain textarea with a rich editor
    Input: MarkdownEditor,
    // Optional: replace plain text rendering with markdown
    Renderer: MarkdownContent,
  }}
/>

import { CommentThread } from "@btst/stack/plugins/comments/client/components"

overrides={{
  blog: {
    postBottomSlot: (post) => (
      <CommentThread
        resourceId={post.slug}
        resourceType="blog-post"
        apiBaseURL={baseURL}
        apiBasePath="/api/data"
        currentUserId={session?.user?.id}
        loginHref="/login"
      />
    ),
  }
}}

import { CommentThread } from "@btst/stack/plugins/comments/client/components"

overrides={{
  kanban: {
    taskDetailBottomSlot: (task) => (
      <CommentThread
        resourceId={task.id}
        resourceType="kanban-task"
        apiBaseURL={baseURL}
        apiBasePath="/api/data"
        currentUserId={session?.user?.id}
        loginHref="/login"
      />
    ),
  }
}}

import { CommentCount } from "@btst/stack/plugins/comments/client/components"

<CommentCount
  resourceId={post.slug}
  resourceType="blog-post"
  apiBaseURL={baseURL}
  apiBasePath="/api/data"
/>

const items = await myStack.api.comments.listComments({
  resourceId: "my-post",
  resourceType: "blog-post",
  status: "approved",
})

const count = await myStack.api.comments.getCommentCount({
  resourceId: "my-post",
  resourceType: "blog-post",
})

import {
  useComments,
  useCommentCount,
  usePostComment,
  useUpdateComment,
  useDeleteComment,
  useToggleLike,
  useUpdateCommentStatus,
} from "@btst/stack/plugins/comments/client/hooks"

// Fetch approved comments for a resource
const { data, isLoading } = useComments({
  resourceId: "my-post",
  resourceType: "blog-post",
  status: "approved",
})

// Post a new comment (includes optimistic update)
const { mutate: postComment } = usePostComment()
postComment({
  resourceId: "my-post",
  resourceType: "blog-post",
  authorId: "user-123",
  body: "Great post!",
})

// Toggle like (one per user; optimistic update)
const { mutate: toggleLike } = useToggleLike()
toggleLike({ commentId: "comment-id", authorId: "user-123" })

// Moderate a comment
const { mutate: updateStatus } = useUpdateCommentStatus()
updateStatus({ id: "comment-id", status: "approved" })

overrides={{
  comments: {
    apiBaseURL: baseURL,
    apiBasePath: "/api/data",

    // Provide the current user's ID so the page can scope the query
    currentUserId: session?.user?.id,

    // Map resource types to URLs so comments link back to their resource
    resourceLinks: {
      "blog-post": (slug) => `/pages/blog/${slug}`,
      "kanban-task": (id) => `/pages/kanban?task=${id}`,
    },

    onBeforeUserCommentsPageRendered: (context) => {
      if (!session?.user) throw new Error("Authentication required")
    },
  }
}}

commentsBackendPlugin({
  // ...
  onBeforeListByAuthor: async (authorId, _query, ctx) => {
    const session = await getSession(ctx.headers)
    if (!session?.user) throw new Error("Authentication required")
    if (authorId !== session.user.id && !session.user.isAdmin)
      throw new Error("Forbidden")
  },
})