@btst/stack 2.7.0 → 2.8.0

package/dist/shared/stack.CmHRdhl8.d.cts

@@ -0,0 +1,335 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import { d as Comment, S as SerializedComment, C as CommentListResult } from './stack.C-b3Sn8j.cjs';
+import * as better_call from 'better-call';
+import { z } from 'zod';
+
+/**
+ * Schema for the POST /comments request body.
+ * authorId is intentionally absent — the server resolves identity from the
+ * session inside onBeforePost and injects it. Never trust authorId from the
+ * client body.
+ */
+declare const createCommentSchema: z.ZodObject<{
+    resourceId: z.ZodString;
+    resourceType: z.ZodString;
+    parentId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for GET /comments query parameters.
+ *
+ * `currentUserId` is intentionally absent — it is never accepted from the client.
+ * The server always resolves the caller's identity via the `resolveCurrentUserId`
+ * hook and injects it internally. Accepting it from the client would allow any
+ * anonymous caller to supply an arbitrary user ID and read that user's pending
+ * (pre-moderation) comments.
+ */
+declare const CommentListQuerySchema: z.ZodObject<{
+    resourceId: z.ZodOptional<z.ZodString>;
+    resourceType: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        spam: "spam";
+    }>>;
+    authorId: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * Internal params schema used by `listComments()` and the `api` factory.
+ * Extends the HTTP query schema with `currentUserId`, which is always injected
+ * server-side (either by the HTTP handler via `resolveCurrentUserId`, or by a
+ * trusted server-side caller such as a Server Component or cron job).
+ */
+declare const CommentListParamsSchema: z.ZodObject<{
+    resourceId: z.ZodOptional<z.ZodString>;
+    resourceType: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        spam: "spam";
+    }>>;
+    authorId: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    currentUserId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const CommentCountQuerySchema: z.ZodObject<{
+    resourceId: z.ZodString;
+    resourceType: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        spam: "spam";
+    }>>;
+}, z.core.$strip>;
+
+/**
+ * Context passed to comments API hooks
+ */
+interface CommentsApiContext {
+    body?: unknown;
+    params?: unknown;
+    query?: unknown;
+    request?: Request;
+    headers?: Headers;
+    [key: string]: unknown;
+}
+/** Shared hook and config fields that are always present regardless of allowPosting. */
+interface CommentsBackendOptionsBase {
+    /**
+     * When true, new comments are automatically approved (status: "approved").
+     * Default: false — all comments start as "pending" until a moderator approves.
+     */
+    autoApprove?: boolean;
+    /**
+     * When false, the `PATCH /comments/:id` endpoint is not registered and
+     * comment bodies cannot be edited.
+     * Default: true.
+     */
+    allowEditing?: boolean;
+    /**
+     * Server-side user resolution hook. Called once per unique authorId when
+     * serving GET /comments. Return null for deleted/unknown users (shown as "[deleted]").
+     * Deduplicates lookups — each unique authorId is resolved only once per request.
+     */
+    resolveUser?: (authorId: string) => Promise<{
+        name: string;
+        avatarUrl?: string;
+    } | null>;
+    /**
+     * Called before the comment list or count is returned. Throw to reject.
+     * When this hook is absent, any request with `status` other than "approved"
+     * is automatically rejected with 403 on both `GET /comments` and
+     * `GET /comments/count` — preventing anonymous callers from reading or
+     * probing the pending/spam moderation queues. Configure this hook to
+     * authorize admin callers (e.g. check session role).
+     */
+    onBeforeList?: (query: z.infer<typeof CommentListQuerySchema>, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called after a comment is successfully created.
+     */
+    onAfterPost?: (comment: Comment, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called before a comment body is edited. Throw an error to reject the edit.
+     * Use this to enforce that only the comment owner can edit (compare authorId to session).
+     */
+    onBeforeEdit?: (commentId: string, update: {
+        body: string;
+    }, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called after a comment is successfully edited.
+     */
+    onAfterEdit?: (comment: Comment, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called before a like is toggled. Throw to reject.
+     *
+     * When this hook is **absent**, any like/unlike request is automatically
+     * rejected with 403 — preventing unauthenticated callers from toggling likes
+     * on behalf of arbitrary user IDs. Configure this hook to verify `authorId`
+     * matches the authenticated session.
+     */
+    onBeforeLike?: (commentId: string, authorId: string, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called before a comment's status is changed. Throw to reject.
+     *
+     * When this hook is **absent**, any status-change request is automatically
+     * rejected with 403 — preventing unauthenticated callers from moderating
+     * comments. Configure this hook to verify the caller has admin/moderator
+     * privileges.
+     */
+    onBeforeStatusChange?: (commentId: string, status: "pending" | "approved" | "spam", context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called after a comment status is changed to "approved".
+     */
+    onAfterApprove?: (comment: Comment, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called before a comment is deleted. Throw to reject.
+     *
+     * When this hook is **absent**, any delete request is automatically rejected
+     * with 403 — preventing unauthenticated callers from deleting comments.
+     * Configure this hook to enforce admin-only access.
+     */
+    onBeforeDelete?: (commentId: string, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called after a comment is deleted.
+     */
+    onAfterDelete?: (commentId: string, context: CommentsApiContext) => Promise<void> | void;
+    /**
+     * Called before the comment list is returned for an author-scoped query
+     * (i.e. when `authorId` is present in `GET /comments`). Throw to reject.
+     *
+     * When this hook is **absent**, any request that includes `authorId` is
+     * automatically rejected with 403 — preventing anonymous callers from
+     * reading or probing any user's comment history.
+     */
+    onBeforeListByAuthor?: (authorId: string, query: z.infer<typeof CommentListQuerySchema>, context: CommentsApiContext) => Promise<void> | void;
+}
+/**
+ * Configuration options for the comments backend plugin.
+ *
+ * TypeScript enforces the security-critical hooks based on `allowPosting`:
+ * - When `allowPosting` is absent or `true`, `onBeforePost` and
+ *   `resolveCurrentUserId` are **required**.
+ * - When `allowPosting` is `false`, both become optional (the POST endpoint
+ *   is not registered so neither hook is ever called).
+ */
+type CommentsBackendOptions = CommentsBackendOptionsBase & ({
+    /**
+     * Posting is enabled (default). `onBeforePost` and `resolveCurrentUserId`
+     * are required to prevent anonymous authorship and impersonation.
+     */
+    allowPosting?: true;
+    /**
+     * Called before a comment is created. Must return `{ authorId: string }` —
+     * the server-resolved identity of the commenter.
+     *
+     * ⚠️  SECURITY REQUIRED: Derive `authorId` from the authenticated session
+     * (e.g. JWT / session cookie). Never trust any ID supplied by the client.
+     * Throw to reject the request (e.g. when the user is not authenticated).
+     *
+     * `authorId` is intentionally absent from the POST body schema. This hook
+     * is the only place it can be set.
+     */
+    onBeforePost: (input: z.infer<typeof createCommentSchema>, context: CommentsApiContext) => Promise<{
+        authorId: string;
+    }> | {
+        authorId: string;
+    };
+    /**
+     * Resolve the current authenticated user's ID from the request context
+     * (e.g. session cookie or JWT). Used to include the user's own pending
+     * comments alongside approved ones in `GET /comments` responses so they
+     * remain visible immediately after posting.
+     *
+     * Return `null` or `undefined` for unauthenticated requests.
+     *
+     * ```ts
+     * resolveCurrentUserId: async (ctx) => {
+     *   const session = await getSession(ctx.headers)
+     *   return session?.user?.id ?? null
+     * }
+     * ```
+     */
+    resolveCurrentUserId: (context: CommentsApiContext) => Promise<string | null | undefined> | string | null | undefined;
+} | {
+    /**
+     * When `false`, the `POST /comments` endpoint is not registered.
+     * No new comments or replies can be submitted — users can only read
+     * existing comments. `onBeforePost` and `resolveCurrentUserId` become
+     * optional because they are never called.
+     */
+    allowPosting: false;
+    onBeforePost?: (input: z.infer<typeof createCommentSchema>, context: CommentsApiContext) => Promise<{
+        authorId: string;
+    }> | {
+        authorId: string;
+    };
+    resolveCurrentUserId?: (context: CommentsApiContext) => Promise<string | null | undefined> | string | null | undefined;
+});
+declare const commentsBackendPlugin: (options: CommentsBackendOptions) => _btst_stack_plugins_api.BackendPlugin<{
+    readonly getCommentCount: better_call.StrictEndpoint<"/comments/count", {} & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            resourceId: string;
+            resourceType: string;
+            status?: "pending" | "approved" | "spam" | undefined;
+        }, {
+            resourceId: string;
+            resourceType: string;
+            status?: "pending" | "approved" | "spam" | undefined;
+        }>;
+    }, {
+        count: number;
+    }>;
+    readonly toggleLike: better_call.StrictEndpoint<"/comments/:id/like", {} & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            authorId: string;
+        }, {
+            authorId: string;
+        }>;
+    }, {
+        likes: number;
+        isLiked: boolean;
+    }>;
+    readonly updateCommentStatus: better_call.StrictEndpoint<"/comments/:id/status", {} & {
+        method: "PATCH";
+        body: better_call.StandardSchemaV1<{
+            status: "pending" | "approved" | "spam";
+        }, {
+            status: "pending" | "approved" | "spam";
+        }>;
+    }, SerializedComment>;
+    readonly deleteComment: better_call.StrictEndpoint<"/comments/:id", {} & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        success: boolean;
+    }>;
+    readonly updateComment?: better_call.StrictEndpoint<"/comments/:id", {} & {
+        method: "PATCH";
+        body: better_call.StandardSchemaV1<{
+            body: string;
+        }, {
+            body: string;
+        }>;
+    }, SerializedComment> | undefined;
+    readonly createComment?: better_call.StrictEndpoint<"/comments", {} & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            resourceId: string;
+            resourceType: string;
+            body: string;
+            parentId?: string | null | undefined;
+        }, {
+            resourceId: string;
+            resourceType: string;
+            body: string;
+            parentId?: string | null | undefined;
+        }>;
+    }, SerializedComment> | undefined;
+    readonly listComments: better_call.StrictEndpoint<"/comments", {} & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            resourceId?: string | undefined;
+            resourceType?: string | undefined;
+            parentId?: string | null | undefined;
+            status?: "pending" | "approved" | "spam" | undefined;
+            authorId?: string | undefined;
+            sort?: "asc" | "desc" | undefined;
+            limit?: unknown;
+            offset?: unknown;
+        }, {
+            resourceId?: string | undefined;
+            resourceType?: string | undefined;
+            parentId?: string | null | undefined;
+            status?: "pending" | "approved" | "spam" | undefined;
+            authorId?: string | undefined;
+            sort?: "asc" | "desc" | undefined;
+            limit?: unknown;
+            offset?: unknown;
+        }>;
+    }, CommentListResult>;
+}, {
+    listComments: (params: z.infer<typeof CommentListParamsSchema>) => Promise<CommentListResult>;
+    getCommentById: (id: string, currentUserId?: string) => Promise<SerializedComment | null>;
+    getCommentCount: (params: z.infer<typeof CommentCountQuerySchema>) => Promise<number>;
+}>;
+type CommentsApiRouter = ReturnType<ReturnType<typeof commentsBackendPlugin>["routes"]>;
+
+export { CommentListParamsSchema as a, CommentCountQuerySchema as b, commentsBackendPlugin as c };
+export type { CommentsApiRouter as C, CommentsApiContext as d, CommentsBackendOptions as e };

package/dist/shared/{stack.CNLHlv7r.d.mts → stack.DOZ1EXjM.d.mts}

@@ -184,13 +184,10 @@ interface UseNextPreviousPostsResult {
     refetch: () => void;
 }
 /**
- * Hook for fetching previous and next posts relative to a given date
- * Uses useInView to only fetch when the component is in view
+ * Hook for fetching previous and next posts relative to a given date.
+ * Pair with `<WhenVisible>` in the render tree for lazy loading.
  */
-declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNextPreviousPostsOptions): UseNextPreviousPostsResult & {
-    ref: (node: Element | null) => void;
-    inView: boolean;
-};
+declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNextPreviousPostsOptions): UseNextPreviousPostsResult;
 /**
  * Options for the useRecentPosts hook
  */
@@ -216,13 +213,10 @@ interface UseRecentPostsResult {
     refetch: () => void;
 }
 /**
- * Hook for fetching recent posts
- * Uses useInView to only fetch when the component is in view
+ * Hook for fetching recent posts.
+ * Pair with `<WhenVisible>` in the render tree for lazy loading.
  */
-declare function useRecentPosts(options?: UseRecentPostsOptions): UseRecentPostsResult & {
-    ref: (node: Element | null) => void;
-    inView: boolean;
-};
+declare function useRecentPosts(options?: UseRecentPostsOptions): UseRecentPostsResult;
 
 export { useSuspensePosts as f, usePost as g, useSuspensePost as h, useTags as i, useSuspenseTags as j, useCreatePost as k, useUpdatePost as l, useDeletePost as m, usePostSearch as n, useNextPreviousPosts as q, useRecentPosts as t, usePosts as u };
 export type { PostCreateInput as P, UsePostsOptions as U, UsePostsResult as a, UsePostSearchOptions as b, UsePostSearchResult as c, UsePostResult as d, PostUpdateInput as e, UseNextPreviousPostsOptions as o, UseNextPreviousPostsResult as p, UseRecentPostsOptions as r, UseRecentPostsResult as s };

package/dist/shared/{stack.FeaWkglm.d.mts → stack.DRpeDS6X.d.ts}

@@ -1,4 +1,5 @@
-import { ComponentType } from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { b as SerializedTask } from './stack.DJaKVY7v.js';
 
 interface KanbanCommonLocalization {
     backToBoards: string;
@@ -185,6 +186,28 @@ interface KanbanPluginOverrides {
      * @param context - Route context
      */
     onBeforeNewBoardPageRendered?: (context: RouteContext) => boolean;
+    /**
+     * Optional slot rendered at the bottom of the task detail dialog.
+     * Use this to inject a comment thread or any custom content without
+     * coupling the kanban plugin to the comments plugin.
+     *
+     * @example
+     * ```tsx
+     * kanban: {
+     *   taskDetailBottomSlot: (task) => (
+     *     <CommentThread
+     *       resourceId={task.id}
+     *       resourceType="kanban-task"
+     *       apiBaseURL={apiBaseURL}
+     *       apiBasePath="/api/data"
+     *       currentUserId={session?.userId}
+     *       loginHref="/login"
+     *     />
+     *   ),
+     * }
+     * ```
+     */
+    taskDetailBottomSlot?: (task: SerializedTask) => ReactNode;
 }
 
 export type { KanbanPluginOverrides as K, KanbanUser as a };

package/dist/shared/{stack.CQAZwXhV.d.cts → stack.DX-tQ93o.d.cts}

@@ -184,13 +184,10 @@ interface UseNextPreviousPostsResult {
     refetch: () => void;
 }
 /**
- * Hook for fetching previous and next posts relative to a given date
- * Uses useInView to only fetch when the component is in view
+ * Hook for fetching previous and next posts relative to a given date.
+ * Pair with `<WhenVisible>` in the render tree for lazy loading.
  */
-declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNextPreviousPostsOptions): UseNextPreviousPostsResult & {
-    ref: (node: Element | null) => void;
-    inView: boolean;
-};
+declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNextPreviousPostsOptions): UseNextPreviousPostsResult;
 /**
  * Options for the useRecentPosts hook
  */
@@ -216,13 +213,10 @@ interface UseRecentPostsResult {
     refetch: () => void;
 }
 /**
- * Hook for fetching recent posts
- * Uses useInView to only fetch when the component is in view
+ * Hook for fetching recent posts.
+ * Pair with `<WhenVisible>` in the render tree for lazy loading.
  */
-declare function useRecentPosts(options?: UseRecentPostsOptions): UseRecentPostsResult & {
-    ref: (node: Element | null) => void;
-    inView: boolean;
-};
+declare function useRecentPosts(options?: UseRecentPostsOptions): UseRecentPostsResult;
 
 export { useSuspensePosts as f, usePost as g, useSuspensePost as h, useTags as i, useSuspenseTags as j, useCreatePost as k, useUpdatePost as l, useDeletePost as m, usePostSearch as n, useNextPreviousPosts as q, useRecentPosts as t, usePosts as u };
 export type { PostCreateInput as P, UsePostsOptions as U, UsePostsResult as a, UsePostSearchOptions as b, UsePostSearchResult as c, UsePostResult as d, PostUpdateInput as e, UseNextPreviousPostsOptions as o, UseNextPreviousPostsResult as p, UseRecentPostsOptions as r, UseRecentPostsResult as s };