@btst/stack 2.7.0 → 2.8.0

package/dist/shared/stack.C-b3Sn8j.d.mts

@@ -0,0 +1,142 @@
+/**
+ * Comment status values
+ */
+type CommentStatus = "pending" | "approved" | "spam";
+/**
+ * A comment record as stored in the database
+ */
+type Comment = {
+    id: string;
+    resourceId: string;
+    resourceType: string;
+    parentId: string | null;
+    authorId: string;
+    body: string;
+    status: CommentStatus;
+    likes: number;
+    editedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/**
+ * A comment enriched with server-resolved author info and like status.
+ * All dates are ISO strings (safe for serialisation over HTTP / React Query cache).
+ */
+interface SerializedComment {
+    id: string;
+    resourceId: string;
+    resourceType: string;
+    parentId: string | null;
+    authorId: string;
+    /** Resolved from resolveUser(authorId). Falls back to "[deleted]" when user cannot be found. */
+    resolvedAuthorName: string;
+    /** Resolved avatar URL or null */
+    resolvedAvatarUrl: string | null;
+    body: string;
+    status: CommentStatus;
+    /** Denormalized counter — updated atomically on toggleLike */
+    likes: number;
+    /** True when the currentUserId query param matches an existing commentLike row */
+    isLikedByCurrentUser: boolean;
+    /** ISO string set when the comment body was edited; null for unedited comments */
+    editedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Number of direct replies visible to the requesting user.
+     * Includes approved replies plus any pending replies authored by `currentUserId`.
+     * Always 0 for reply comments (non-null parentId).
+     */
+    replyCount: number;
+}
+/**
+ * Paginated list result for comments
+ */
+interface CommentListResult {
+    items: SerializedComment[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Internal query key constants for the Comments plugin.
+ * Shared between query-keys.ts (HTTP path) and any SSG/direct DB path
+ * to prevent key drift between loaders and prefetch calls.
+ */
+interface CommentsListDiscriminator {
+    resourceId: string | undefined;
+    resourceType: string | undefined;
+    parentId: string | null | undefined;
+    status: string | undefined;
+    currentUserId: string | undefined;
+    authorId: string | undefined;
+    sort: string | undefined;
+    limit: number;
+    offset: number;
+}
+interface CommentCountDiscriminator {
+    resourceId: string;
+    resourceType: string;
+    status: string | undefined;
+}
+/**
+ * Discriminator for the infinite thread query (top-level comments only).
+ * Intentionally excludes `offset` — pages are driven by `pageParam`, not the key.
+ */
+interface CommentsThreadDiscriminator {
+    resourceId: string | undefined;
+    resourceType: string | undefined;
+    parentId: string | null | undefined;
+    status: string | undefined;
+    currentUserId: string | undefined;
+    limit: number;
+}
+/** Full query key builders — use with queryClient.setQueryData() */
+declare const COMMENTS_QUERY_KEYS: {
+    /**
+     * Key for comments list query.
+     * Full key: ["comments", "list", { resourceId, resourceType, parentId, status, currentUserId, limit, offset }]
+     */
+    commentsList: (params?: {
+        resourceId?: string;
+        resourceType?: string;
+        parentId?: string | null;
+        status?: string;
+        currentUserId?: string;
+        authorId?: string;
+        sort?: string;
+        limit?: number;
+        offset?: number;
+    }) => readonly ["comments", "list", CommentsListDiscriminator];
+    /**
+     * Key for a single comment detail query.
+     * Full key: ["comments", "detail", id]
+     */
+    commentDetail: (id: string) => readonly ["comments", "detail", string];
+    /**
+     * Key for comment count query.
+     * Full key: ["comments", "count", { resourceId, resourceType, status }]
+     */
+    commentCount: (params: {
+        resourceId: string;
+        resourceType: string;
+        status?: string;
+    }) => readonly ["comments", "count", CommentCountDiscriminator];
+    /**
+     * Key for the infinite thread query (top-level comments, load-more).
+     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+     * Offset is excluded — it is driven by `pageParam`, not baked into the key.
+     */
+    commentsThread: (params?: {
+        resourceId?: string;
+        resourceType?: string;
+        parentId?: string | null;
+        status?: string;
+        currentUserId?: string;
+        limit?: number;
+    }) => readonly ["commentsThread", "list", CommentsThreadDiscriminator];
+};
+
+export { COMMENTS_QUERY_KEYS as e };
+export type { CommentListResult as C, SerializedComment as S, CommentsThreadDiscriminator as a, CommentsListDiscriminator as b, CommentCountDiscriminator as c, Comment as d };

package/dist/shared/stack.C-b3Sn8j.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Comment status values
+ */
+type CommentStatus = "pending" | "approved" | "spam";
+/**
+ * A comment record as stored in the database
+ */
+type Comment = {
+    id: string;
+    resourceId: string;
+    resourceType: string;
+    parentId: string | null;
+    authorId: string;
+    body: string;
+    status: CommentStatus;
+    likes: number;
+    editedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/**
+ * A comment enriched with server-resolved author info and like status.
+ * All dates are ISO strings (safe for serialisation over HTTP / React Query cache).
+ */
+interface SerializedComment {
+    id: string;
+    resourceId: string;
+    resourceType: string;
+    parentId: string | null;
+    authorId: string;
+    /** Resolved from resolveUser(authorId). Falls back to "[deleted]" when user cannot be found. */
+    resolvedAuthorName: string;
+    /** Resolved avatar URL or null */
+    resolvedAvatarUrl: string | null;
+    body: string;
+    status: CommentStatus;
+    /** Denormalized counter — updated atomically on toggleLike */
+    likes: number;
+    /** True when the currentUserId query param matches an existing commentLike row */
+    isLikedByCurrentUser: boolean;
+    /** ISO string set when the comment body was edited; null for unedited comments */
+    editedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Number of direct replies visible to the requesting user.
+     * Includes approved replies plus any pending replies authored by `currentUserId`.
+     * Always 0 for reply comments (non-null parentId).
+     */
+    replyCount: number;
+}
+/**
+ * Paginated list result for comments
+ */
+interface CommentListResult {
+    items: SerializedComment[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Internal query key constants for the Comments plugin.
+ * Shared between query-keys.ts (HTTP path) and any SSG/direct DB path
+ * to prevent key drift between loaders and prefetch calls.
+ */
+interface CommentsListDiscriminator {
+    resourceId: string | undefined;
+    resourceType: string | undefined;
+    parentId: string | null | undefined;
+    status: string | undefined;
+    currentUserId: string | undefined;
+    authorId: string | undefined;
+    sort: string | undefined;
+    limit: number;
+    offset: number;
+}
+interface CommentCountDiscriminator {
+    resourceId: string;
+    resourceType: string;
+    status: string | undefined;
+}
+/**
+ * Discriminator for the infinite thread query (top-level comments only).
+ * Intentionally excludes `offset` — pages are driven by `pageParam`, not the key.
+ */
+interface CommentsThreadDiscriminator {
+    resourceId: string | undefined;
+    resourceType: string | undefined;
+    parentId: string | null | undefined;
+    status: string | undefined;
+    currentUserId: string | undefined;
+    limit: number;
+}
+/** Full query key builders — use with queryClient.setQueryData() */
+declare const COMMENTS_QUERY_KEYS: {
+    /**
+     * Key for comments list query.
+     * Full key: ["comments", "list", { resourceId, resourceType, parentId, status, currentUserId, limit, offset }]
+     */
+    commentsList: (params?: {
+        resourceId?: string;
+        resourceType?: string;
+        parentId?: string | null;
+        status?: string;
+        currentUserId?: string;
+        authorId?: string;
+        sort?: string;
+        limit?: number;
+        offset?: number;
+    }) => readonly ["comments", "list", CommentsListDiscriminator];
+    /**
+     * Key for a single comment detail query.
+     * Full key: ["comments", "detail", id]
+     */
+    commentDetail: (id: string) => readonly ["comments", "detail", string];
+    /**
+     * Key for comment count query.
+     * Full key: ["comments", "count", { resourceId, resourceType, status }]
+     */
+    commentCount: (params: {
+        resourceId: string;
+        resourceType: string;
+        status?: string;
+    }) => readonly ["comments", "count", CommentCountDiscriminator];
+    /**
+     * Key for the infinite thread query (top-level comments, load-more).
+     * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+     * Offset is excluded — it is driven by `pageParam`, not baked into the key.
+     */
+    commentsThread: (params?: {
+        resourceId?: string;
+        resourceType?: string;
+        parentId?: string | null;
+        status?: string;
+        currentUserId?: string;
+        limit?: number;
+    }) => readonly ["commentsThread", "list", CommentsThreadDiscriminator];
+};
+
+export { COMMENTS_QUERY_KEYS as e };
+export type { CommentListResult as C, SerializedComment as S, CommentsThreadDiscriminator as a, CommentsListDiscriminator as b, CommentCountDiscriminator as c, Comment as d };

package/dist/shared/stack.CJE9sAjV.d.ts

@@ -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.js';
+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 };