@btst/stack 2.11.8 → 2.12.1

package/dist/plugins/cms/query-keys.d.ts

@@ -1,11 +1,401 @@
-import { C as CMSApiRouter, a as ContentListDiscriminator } from '../../shared/stack.fXlShnhv.js';
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import { a as SerializedContentItemWithType, S as SerializedContentType, b as ContentType, c as ContentItem, d as SerializedContentItem, e as ContentItemWithType, f as CMSBackendConfig, I as InverseRelation, P as PaginatedContentItems } from '../../shared/stack.DFtpFS00.js';
+import * as better_call from 'better-call';
+import { z } from 'zod';
+import { DBAdapter } from '@btst/db';
 import * as _tanstack_react_query from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
 import { createApiClient } from '@btst/stack/plugins/client';
-import { S as SerializedContentType, P as PaginatedContentItems, a as SerializedContentItemWithType } from '../../shared/stack.B8QD11QU.js';
-import '@btst/stack/plugins/api';
-import 'better-call';
-import 'zod';
-import '@btst/db';
+
+/**
+ * Serialize a ContentType for SSR/SSG use (convert dates to strings).
+ * Applies lazy migration for legacy schemas (version 1 → 2).
+ */
+declare function serializeContentType(ct: ContentType): SerializedContentType;
+/**
+ * Serialize a ContentItem for SSR/SSG use (convert dates to strings).
+ */
+declare function serializeContentItem(item: ContentItem): SerializedContentItem;
+/**
+ * Serialize a ContentItem with parsed data and joined ContentType.
+ * Throws a SyntaxError if `item.data` is not valid JSON, so corrupted rows
+ * produce a visible, debuggable error rather than silently returning null.
+ */
+declare function serializeContentItemWithType(item: ContentItemWithType): SerializedContentItemWithType;
+/**
+ * Retrieve all content types.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ */
+declare function getAllContentTypes(adapter: DBAdapter): Promise<SerializedContentType[]>;
+/**
+ * Retrieve all content items for a given content type, with optional pagination.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListItems`) are NOT
+ * called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param contentTypeSlug - The slug of the content type to query
+ * @param params - Optional filter/pagination parameters
+ */
+declare function getAllContentItems(adapter: DBAdapter, contentTypeSlug: string, params?: {
+    slug?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    items: SerializedContentItemWithType[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}>;
+/**
+ * Retrieve a single content item by its ID.
+ * Returns null if the item is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param id - The content item ID (UUID)
+ */
+declare function getContentItemById(adapter: DBAdapter, id: string): Promise<SerializedContentItemWithType | null>;
+/**
+ * Retrieve a single content item by its slug within a content type.
+ * Returns null if the content type or item is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param contentTypeSlug - The slug of the content type
+ * @param slug - The slug of the content item
+ */
+declare function getContentItemBySlug(adapter: DBAdapter, contentTypeSlug: string, slug: string): Promise<SerializedContentItemWithType | null>;
+
+/**
+ * Input for creating a new CMS content item.
+ */
+interface CreateCMSContentItemInput {
+    /** URL-safe slug for the item */
+    slug: string;
+    /** Arbitrary data payload — should match the content type schema */
+    data: Record<string, unknown>;
+}
+/**
+ * Options for {@link createCMSContentItem}.
+ */
+interface CreateCMSContentItemOptions {
+    /**
+     * When `true`, persist relation fields (`belongsTo`, `hasMany`,
+     * `manyToMany`) into the `contentRelation` junction table in addition to
+     * the item's JSON payload.
+     *
+     * This is what the HTTP `POST /content/:typeSlug` route does, and is
+     * required for the admin "Related Items" panel / inverse-relation queries
+     * to find the item.
+     *
+     * Seeds and other programmatic callers that want the admin UI to work
+     * should enable this flag. Callers are still expected to pass
+     * pre-created target IDs (`{ id }` or `[{ id }, ...]`) — inline `_new`
+     * creation is only supported via the HTTP route.
+     *
+     * Defaults to `false` for backwards compatibility (a no-op for content
+     * types without relations).
+     */
+    syncRelations?: boolean;
+}
+/**
+ * Create a new content item for a content type (looked up by slug).
+ *
+ * Bypasses Zod schema validation and inline `_new` relation creation — the
+ * caller is responsible for providing valid data and pre-created relation
+ * IDs. For schema validation or inline creation of related items, use the
+ * HTTP endpoint instead.
+ *
+ * Throws if the content type is not found or the slug is already taken within
+ * that content type.
+ *
+ * @remarks **Security:** No authorization hooks (`onBeforeCreate`, `onAfterCreate`)
+ * are called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param contentTypeSlug - Slug of the target content type
+ * @param input - Item slug and data payload
+ * @param options - See {@link CreateCMSContentItemOptions}. Pass
+ *   `{ syncRelations: true }` to also populate the `contentRelation`
+ *   junction table for relation fields in the payload.
+ */
+declare function createCMSContentItem(adapter: DBAdapter, contentTypeSlug: string, input: CreateCMSContentItemInput, options?: CreateCMSContentItemOptions): Promise<SerializedContentItem>;
+
+/**
+ * Route keys for the CMS plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+type CMSRouteKey = "dashboard" | "contentList" | "newContent" | "editContent";
+interface CMSPrefetchForRoute {
+    (key: "dashboard" | "newContent", qc: QueryClient): Promise<void>;
+    (key: "contentList", qc: QueryClient, params: {
+        typeSlug: string;
+    }): Promise<void>;
+    (key: "editContent", qc: QueryClient, params: {
+        typeSlug: string;
+        id: string;
+    }): Promise<void>;
+}
+/**
+ * CMS backend plugin
+ * Provides API endpoints for managing content types and content items
+ *
+ * @param config - Configuration with content types and optional hooks
+ */
+declare const cmsBackendPlugin: (config: CMSBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+    listContentTypes: better_call.StrictEndpoint<"/content-types", {} & {
+        method: "GET";
+    }, {
+        itemCount: number;
+        createdAt: string;
+        updatedAt: string;
+        name: string;
+        id: string;
+        slug: string;
+        description?: string | undefined;
+        jsonSchema: string;
+        fieldConfig?: string | undefined;
+        autoFormVersion?: number | undefined;
+    }[]>;
+    getContentTypeBySlug: better_call.StrictEndpoint<"/content-types/:slug", {
+        params: z.ZodObject<{
+            slug: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    }, SerializedContentType>;
+    listContentItems: better_call.StrictEndpoint<"/content/:typeSlug", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            slug?: string | undefined;
+            limit?: unknown;
+            offset?: unknown;
+        }, {
+            slug?: string | undefined;
+            limit?: unknown;
+            offset?: unknown;
+        }>;
+    }, {
+        items: SerializedContentItemWithType[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    }, SerializedContentItemWithType<Record<string, unknown>>>;
+    createContentItem: better_call.StrictEndpoint<"/content/:typeSlug", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            slug: string;
+            data: {
+                [x: string]: unknown;
+            };
+        }, {
+            slug: string;
+            data: {
+                [x: string]: unknown;
+            };
+        }>;
+    }, {
+        parsedData: Record<string, unknown>;
+        createdAt: string;
+        updatedAt: string;
+        id: string;
+        slug: string;
+        contentTypeId: string;
+        data: string;
+        authorId?: string | undefined;
+    }>;
+    updateContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "PUT";
+        body: better_call.StandardSchemaV1<{
+            slug?: string | undefined;
+            data?: {
+                [x: string]: unknown;
+            } | undefined;
+        }, {
+            slug?: string | undefined;
+            data?: {
+                [x: string]: unknown;
+            } | undefined;
+        }>;
+    }, SerializedContentItemWithType<Record<string, unknown>>>;
+    deleteContentItem: better_call.StrictEndpoint<"/content/:typeSlug/:id", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        success: boolean;
+    }>;
+    getContentItemPopulated: better_call.StrictEndpoint<"/content/:typeSlug/:id/populated", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    }, {
+        _relations: Record<string, SerializedContentItemWithType<Record<string, unknown>>[]>;
+        parsedData: Record<string, unknown>;
+        contentType?: SerializedContentType;
+        createdAt: string;
+        updatedAt: string;
+        id: string;
+        slug: string;
+        contentTypeId: string;
+        data: string;
+        authorId?: string | undefined;
+    }>;
+    listContentByRelation: better_call.StrictEndpoint<"/content/:typeSlug/by-relation", {
+        params: z.ZodObject<{
+            typeSlug: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            field: string;
+            targetId: string;
+            limit?: unknown;
+            offset?: unknown;
+        }, {
+            field: string;
+            targetId: string;
+            limit?: unknown;
+            offset?: unknown;
+        }>;
+    }, {
+        items: SerializedContentItemWithType<Record<string, unknown>>[];
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    getInverseRelations: better_call.StrictEndpoint<"/content-types/:slug/inverse-relations", {
+        params: z.ZodObject<{
+            slug: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            itemId?: string | undefined;
+        }, {
+            itemId?: string | undefined;
+        }>;
+    }, {
+        inverseRelations: InverseRelation[];
+    }>;
+    listInverseRelationItems: better_call.StrictEndpoint<"/content-types/:slug/inverse-relations/:sourceType", {
+        params: z.ZodObject<{
+            slug: z.ZodString;
+            sourceType: z.ZodString;
+        }, z.core.$strip>;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            itemId: string;
+            fieldName: string;
+            limit?: unknown;
+            offset?: unknown;
+        }, {
+            itemId: string;
+            fieldName: string;
+            limit?: unknown;
+            offset?: unknown;
+        }>;
+    }, {
+        items: SerializedContentItemWithType<Record<string, unknown>>[];
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+}, {
+    getAllContentTypes: () => Promise<SerializedContentType[]>;
+    getAllContentItems: (contentTypeSlug: string, params?: Parameters<typeof getAllContentItems>[2]) => Promise<{
+        items: SerializedContentItemWithType[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getContentItemBySlug: (contentTypeSlug: string, slug: string) => Promise<SerializedContentItemWithType<Record<string, unknown>> | null>;
+    getContentItemById: (id: string) => Promise<SerializedContentItemWithType<Record<string, unknown>> | null>;
+    prefetchForRoute: CMSPrefetchForRoute;
+    createContentItem: (typeSlug: string, input: Parameters<typeof createCMSContentItem>[2], options?: Parameters<typeof createCMSContentItem>[3]) => Promise<SerializedContentItem>;
+}>;
+type CMSApiRouter = ReturnType<ReturnType<typeof cmsBackendPlugin>["routes"]>;
+
+/**
+ * Internal query key constants for the CMS plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+interface ContentListDiscriminator {
+    typeSlug: string;
+    limit: number;
+    offset: number;
+}
+/** Full query key builders — use these with queryClient.setQueryData() */
+declare const CMS_QUERY_KEYS: {
+    /**
+     * Key for the cmsTypes.list() query.
+     * Full key: ["cmsTypes", "list", "list"]
+     */
+    typesList: () => readonly ["cmsTypes", "list", "list"];
+    /**
+     * Key for the cmsContent.list({ typeSlug, limit, offset }) query.
+     * Full key: ["cmsContent", "list", { typeSlug, limit, offset }]
+     */
+    contentList: (params: {
+        typeSlug: string;
+        limit?: number;
+        offset?: number;
+    }) => readonly ["cmsContent", "list", ContentListDiscriminator];
+    /**
+     * Key for the cmsContent.detail(typeSlug, id) query.
+     * Full key: ["cmsContent", "detail", typeSlug, id]
+     */
+    contentDetail: (typeSlug: string, id: string) => readonly ["cmsContent", "detail", string, string];
+};
 
 interface ContentListParams {
     limit?: number;
@@ -70,4 +460,5 @@ declare function createCMSQueryKeys(client: ReturnType<typeof createApiClient<CM
     };
 };
 
-export { createCMSQueryKeys };
+export { getAllContentItems as b, cmsBackendPlugin as c, createCMSQueryKeys, getContentItemBySlug as d, getContentItemById as e, serializeContentItem as f, getAllContentTypes as g, serializeContentItemWithType as h, createCMSContentItem as i, CMS_QUERY_KEYS as l, serializeContentType as s };
+export type { CMSApiRouter as C, CMSRouteKey as a, CreateCMSContentItemInput as j, CreateCMSContentItemOptions as k };

package/dist/plugins/comments/api/index.d.cts

@@ -1,8 +1,8 @@
-import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CmHRdhl8.cjs';
-export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CmHRdhl8.cjs';
+import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CCncwK6g.cjs';
+export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CCncwK6g.cjs';
 import { DBAdapter } from '@btst/db';
-import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C-b3Sn8j.cjs';
-export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C-b3Sn8j.cjs';
+import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C7KNNiJm.cjs';
+export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C7KNNiJm.cjs';
 import { z } from 'zod';
 import '@btst/stack/plugins/api';
 import 'better-call';

package/dist/plugins/comments/api/index.d.mts

@@ -1,8 +1,8 @@
-import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.Dcz6636A.mjs';
-export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.Dcz6636A.mjs';
+import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CO1g47IS.mjs';
+export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CO1g47IS.mjs';
 import { DBAdapter } from '@btst/db';
-import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C-b3Sn8j.mjs';
-export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C-b3Sn8j.mjs';
+import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C7KNNiJm.mjs';
+export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C7KNNiJm.mjs';
 import { z } from 'zod';
 import '@btst/stack/plugins/api';
 import 'better-call';

package/dist/plugins/comments/api/index.d.ts

@@ -1,8 +1,8 @@
-import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.CJE9sAjV.js';
-export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.CJE9sAjV.js';
+import { a as CommentListParamsSchema, b as CommentCountQuerySchema } from '../../../shared/stack.Bq3kiUaM.js';
+export { d as CommentsApiContext, C as CommentsApiRouter, e as CommentsBackendOptions, c as commentsBackendPlugin } from '../../../shared/stack.Bq3kiUaM.js';
 import { DBAdapter } from '@btst/db';
-import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C-b3Sn8j.js';
-export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C-b3Sn8j.js';
+import { C as CommentListResult, S as SerializedComment, d as Comment } from '../../../shared/stack.C7KNNiJm.js';
+export { e as COMMENTS_QUERY_KEYS } from '../../../shared/stack.C7KNNiJm.js';
 import { z } from 'zod';
 import '@btst/stack/plugins/api';
 import 'better-call';

package/dist/plugins/comments/client/components/index.d.cts

@@ -59,6 +59,17 @@ interface CommentThreadProps {
      * Defaults to true.
      */
     allowEditing?: boolean;
+    /**
+     * Sort direction for top-level comments by `createdAt`.
+     * - `"desc"` (default): newest first.
+     * - `"asc"`: oldest first.
+     *
+     * Replies inside each thread always render chronologically (oldest → newest)
+     * and are unaffected by this prop.
+     *
+     * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+     */
+    sort?: "asc" | "desc";
 }
 declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
 

package/dist/plugins/comments/client/components/index.d.mts

@@ -59,6 +59,17 @@ interface CommentThreadProps {
      * Defaults to true.
      */
     allowEditing?: boolean;
+    /**
+     * Sort direction for top-level comments by `createdAt`.
+     * - `"desc"` (default): newest first.
+     * - `"asc"`: oldest first.
+     *
+     * Replies inside each thread always render chronologically (oldest → newest)
+     * and are unaffected by this prop.
+     *
+     * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+     */
+    sort?: "asc" | "desc";
 }
 declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
 

package/dist/plugins/comments/client/components/index.d.ts

@@ -59,6 +59,17 @@ interface CommentThreadProps {
      * Defaults to true.
      */
     allowEditing?: boolean;
+    /**
+     * Sort direction for top-level comments by `createdAt`.
+     * - `"desc"` (default): newest first.
+     * - `"asc"`: oldest first.
+     *
+     * Replies inside each thread always render chronologically (oldest → newest)
+     * and are unaffected by this prop.
+     *
+     * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+     */
+    sort?: "asc" | "desc";
 }
 declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
 

package/dist/plugins/comments/client/hooks/index.d.cts

@@ -1,4 +1,4 @@
-import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.cjs';
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C7KNNiJm.cjs';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { InfiniteData } from '@tanstack/react-query';
 
@@ -81,6 +81,11 @@ declare function useInfiniteComments(config: CommentsClientConfig, params: {
     parentId?: string | null;
     status?: "pending" | "approved" | "spam";
     currentUserId?: string;
+    /**
+     * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+     * the server-side default. Pass `"desc"` for newest-first threads.
+     */
+    sort?: "asc" | "desc";
     pageSize?: number;
 }, options?: {
     enabled?: boolean;
@@ -129,6 +134,17 @@ declare function usePostComment(config: CommentsClientConfig, params: {
      * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
      */
     pageSize?: number;
+    /**
+     * Sort direction of the surrounding infinite thread.
+     * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+     *   item is appended to `pages[last].items`.
+     * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+     *   is prepended to `pages[0].items`.
+     *
+     * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+     * item appears in the same position the server will place it.
+     */
+    sort?: "asc" | "desc";
 }): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
     body: string;
     parentId?: string | null;

package/dist/plugins/comments/client/hooks/index.d.mts

@@ -1,4 +1,4 @@
-import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.mjs';
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C7KNNiJm.mjs';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { InfiniteData } from '@tanstack/react-query';
 
@@ -81,6 +81,11 @@ declare function useInfiniteComments(config: CommentsClientConfig, params: {
     parentId?: string | null;
     status?: "pending" | "approved" | "spam";
     currentUserId?: string;
+    /**
+     * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+     * the server-side default. Pass `"desc"` for newest-first threads.
+     */
+    sort?: "asc" | "desc";
     pageSize?: number;
 }, options?: {
     enabled?: boolean;
@@ -129,6 +134,17 @@ declare function usePostComment(config: CommentsClientConfig, params: {
      * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
      */
     pageSize?: number;
+    /**
+     * Sort direction of the surrounding infinite thread.
+     * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+     *   item is appended to `pages[last].items`.
+     * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+     *   is prepended to `pages[0].items`.
+     *
+     * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+     * item appears in the same position the server will place it.
+     */
+    sort?: "asc" | "desc";
 }): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
     body: string;
     parentId?: string | null;

package/dist/plugins/comments/client/hooks/index.d.ts

@@ -1,4 +1,4 @@
-import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.js';
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C7KNNiJm.js';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { InfiniteData } from '@tanstack/react-query';
 
@@ -81,6 +81,11 @@ declare function useInfiniteComments(config: CommentsClientConfig, params: {
     parentId?: string | null;
     status?: "pending" | "approved" | "spam";
     currentUserId?: string;
+    /**
+     * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+     * the server-side default. Pass `"desc"` for newest-first threads.
+     */
+    sort?: "asc" | "desc";
     pageSize?: number;
 }, options?: {
     enabled?: boolean;
@@ -129,6 +134,17 @@ declare function usePostComment(config: CommentsClientConfig, params: {
      * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
      */
     pageSize?: number;
+    /**
+     * Sort direction of the surrounding infinite thread.
+     * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+     *   item is appended to `pages[last].items`.
+     * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+     *   is prepended to `pages[0].items`.
+     *
+     * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+     * item appears in the same position the server will place it.
+     */
+    sort?: "asc" | "desc";
 }): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
     body: string;
     parentId?: string | null;

package/dist/plugins/comments/client/index.d.cts

@@ -197,6 +197,15 @@ interface CommentsPluginOverrides {
      * Defaults to 100 when not set.
      */
     defaultCommentPageSize?: number;
+    /**
+     * Default sort direction (by `createdAt`) for top-level comments in
+     * `CommentThread`.
+     * - `"desc"` (default): newest comments first.
+     * - `"asc"`: oldest comments first.
+     *
+     * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+     */
+    defaultCommentSort?: "asc" | "desc";
     /**
      * When false, the comment form and reply buttons are hidden in all
      * `CommentThread` instances. Users can still read existing comments.

package/dist/plugins/comments/client/index.d.mts

@@ -197,6 +197,15 @@ interface CommentsPluginOverrides {
      * Defaults to 100 when not set.
      */
     defaultCommentPageSize?: number;
+    /**
+     * Default sort direction (by `createdAt`) for top-level comments in
+     * `CommentThread`.
+     * - `"desc"` (default): newest comments first.
+     * - `"asc"`: oldest comments first.
+     *
+     * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+     */
+    defaultCommentSort?: "asc" | "desc";
     /**
      * When false, the comment form and reply buttons are hidden in all
      * `CommentThread` instances. Users can still read existing comments.

package/dist/plugins/comments/client/index.d.ts

@@ -197,6 +197,15 @@ interface CommentsPluginOverrides {
      * Defaults to 100 when not set.
      */
     defaultCommentPageSize?: number;
+    /**
+     * Default sort direction (by `createdAt`) for top-level comments in
+     * `CommentThread`.
+     * - `"desc"` (default): newest comments first.
+     * - `"asc"`: oldest comments first.
+     *
+     * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+     */
+    defaultCommentSort?: "asc" | "desc";
     /**
      * When false, the comment form and reply buttons are hidden in all
      * `CommentThread` instances. Users can still read existing comments.