@sublay/js 7.9.2 → 8.0.0-beta.1

package/dist/index.d.ts

@@ -771,6 +771,19 @@ interface PaginatedResponse<T> {
     data: T[];
     pagination: PaginationMetadata;
 }
+/**
+ * Cursor pagination (comment lists). `nextCursor` continues after the last
+ * item of this page — pass it back as `cursor` — and is `null` when `hasMore`
+ * is `false`. `hasMore` is exact.
+ */
+interface CursorPagination {
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+interface CursorPaginatedResponse<T> {
+    data: T[];
+    pagination: CursorPagination;
+}
 
 /**
  * Shared optional params for text-searching a list of users
@@ -887,156 +900,22 @@ interface FetchConnectionsCountByUserIdProps {
 }
 declare function fetchConnectionsCountByUserId(client: SublayHttpClient, data: FetchConnectionsCountByUserIdProps): Promise<ConnectionCountResponse>;
 
-interface CreateFollowProps {
-    /** The user being followed (the target). The follower is the token holder. */
-    userId: string;
-}
-declare function createFollow(client: SublayHttpClient, data: CreateFollowProps): Promise<Follow>;
-
-interface DeleteFollowProps {
-    /** The user being unfollowed (the target). The follower is the token holder. */
-    userId: string;
-}
-declare function deleteFollow$1(client: SublayHttpClient, data: DeleteFollowProps): Promise<void>;
-
-interface FetchFollowStatusProps {
-    /**
-     * The user whose follow relationship is being checked (the target). The
-     * status is from the perspective of the token holder.
-     */
-    userId: string;
-}
-interface FollowStatusResponse {
-    isFollowing: boolean;
-    followId?: string;
-    followedAt?: string;
-}
-declare function fetchFollowStatus(client: SublayHttpClient, data: FetchFollowStatusProps): Promise<FollowStatusResponse>;
-
-interface RequestConnectionProps {
-    /**
-     * The user the connection is requested with (the target). The requester is
-     * the token holder.
-     */
-    userId: string;
-    message?: string;
-}
-declare function requestConnection(client: SublayHttpClient, data: RequestConnectionProps): Promise<ConnectionRequestResponse>;
-
-interface FetchConnectionStatusProps {
-    /**
-     * The other user in the connection (the target). The status is from the
-     * perspective of the token holder.
-     */
-    userId: string;
-}
-declare function fetchConnectionStatus(client: SublayHttpClient, data: FetchConnectionStatusProps): Promise<ConnectionStatusResponse>;
-
-interface RemoveConnectionByUserIdProps {
-    /**
-     * The other user in the connection (the target). The token holder is the
-     * user withdrawing/declining/disconnecting.
-     */
-    userId: string;
-}
-declare function removeConnectionByUserId(client: SublayHttpClient, data: RemoveConnectionByUserIdProps): Promise<RemoveConnectionByUserIdResponse>;
-
-interface CreateBlockProps {
-    /** The user being blocked (the target). The blocker is the token holder. */
-    userId: string;
-}
-interface BlockResponse {
-    id: string;
-    blockerId: string;
-    blockedId: string;
-    createdAt: string;
-}
-/**
- * POST /users/:userId/block — block `:userId`.
- *
- * The blocker is derived from the token (Rule A — no `actingUserId`). Idempotent:
- * re-blocking an already-blocked user succeeds. Self-block is rejected server-side.
- * On a new block the server tears down existing follows/connections both ways.
- */
-declare function createBlock(client: SublayHttpClient, data: CreateBlockProps): Promise<BlockResponse>;
-
-interface DeleteBlockProps {
-    /** The user being unblocked (the target). The blocker is the token holder. */
-    userId: string;
-}
-/**
- * DELETE /users/:userId/block — unblock `:userId`.
- *
- * The blocker is derived from the token (Rule A — no `actingUserId`). Idempotent:
- * unblocking a user who isn't blocked succeeds. Restores nothing (torn-down
- * follows/connections are gone for good).
- */
-declare function deleteBlock(client: SublayHttpClient, data: DeleteBlockProps): Promise<void>;
-
-interface FetchBlockStatusProps {
-    /**
-     * The user whose block status is being checked (the target). The status is the
-     * token holder's OUTBOUND state only: do *I* block `:userId`?
-     */
-    userId: string;
-}
-/**
- * The block-status response is outbound-only by design: it reports whether the
- * token holder blocks the target, and NEVER whether the target blocked the
- * caller (the inbound direction is deliberately not disclosed).
- */
-interface BlockStatusResponse {
-    blocked: boolean;
-    blockId?: string;
-    createdAt?: string;
-}
+/** Sorts that rank one way only: the server refuses `sortDir` with them. */
+type OneWaySort = "hot" | "controversial";
 /**
- * GET /users/:userId/block — the token holder's outbound block status toward
- * `:userId` (Rule A — no `actingUserId`).
+ * A request's sort fields with `sortDir` ruled out for a one-way sort: with
+ * `sortBy: "hot"` or `"controversial"`, no `sortDir`; with any other sort (or
+ * none), `sortDir` as usual.
  */
-declare function fetchBlockStatus(client: SublayHttpClient, data: FetchBlockStatusProps): Promise<BlockStatusResponse>;
-
-interface FetchBlockedUsersProps {
-    page?: number;
-    limit?: number;
-}
-/** An entry in the token holder's own block list (their outbound blocks). */
-interface BlockedUserListItem {
-    id: string;
-    blockedUser: User | null;
-    createdAt: string;
-}
-/**
- * GET /blocks — the token holder's own block list (their outbound blocks),
- * paginated. This is the private "manage / way back to unblock" surface (Rule A
- * — the subject is derived from the token, no `actingUserId`).
- */
-declare function fetchBlockedUsers(client: SublayHttpClient, data?: FetchBlockedUsersProps): Promise<PaginatedResponse<BlockedUserListItem>>;
-
-declare const Users_checkUsernameAvailability: typeof checkUsernameAvailability;
-declare const Users_createBlock: typeof createBlock;
-declare const Users_createFollow: typeof createFollow;
-declare const Users_deleteBlock: typeof deleteBlock;
-declare const Users_fetchBlockStatus: typeof fetchBlockStatus;
-declare const Users_fetchBlockedUsers: typeof fetchBlockedUsers;
-declare const Users_fetchConnectionStatus: typeof fetchConnectionStatus;
-declare const Users_fetchConnectionsByUserId: typeof fetchConnectionsByUserId;
-declare const Users_fetchConnectionsCountByUserId: typeof fetchConnectionsCountByUserId;
-declare const Users_fetchFollowStatus: typeof fetchFollowStatus;
-declare const Users_fetchFollowersByUserId: typeof fetchFollowersByUserId;
-declare const Users_fetchFollowersCountByUserId: typeof fetchFollowersCountByUserId;
-declare const Users_fetchFollowingByUserId: typeof fetchFollowingByUserId;
-declare const Users_fetchFollowingCountByUserId: typeof fetchFollowingCountByUserId;
-declare const Users_fetchUserByForeignId: typeof fetchUserByForeignId;
-declare const Users_fetchUserById: typeof fetchUserById;
-declare const Users_fetchUserByUsername: typeof fetchUserByUsername;
-declare const Users_fetchUserSuggestions: typeof fetchUserSuggestions;
-declare const Users_removeConnectionByUserId: typeof removeConnectionByUserId;
-declare const Users_requestConnection: typeof requestConnection;
-declare const Users_updateUser: typeof updateUser;
-declare namespace Users {
-  export { Users_checkUsernameAvailability as checkUsernameAvailability, Users_createBlock as createBlock, Users_createFollow as createFollow, Users_deleteBlock as deleteBlock, deleteFollow$1 as deleteFollow, Users_fetchBlockStatus as fetchBlockStatus, Users_fetchBlockedUsers as fetchBlockedUsers, Users_fetchConnectionStatus as fetchConnectionStatus, Users_fetchConnectionsByUserId as fetchConnectionsByUserId, Users_fetchConnectionsCountByUserId as fetchConnectionsCountByUserId, Users_fetchFollowStatus as fetchFollowStatus, Users_fetchFollowersByUserId as fetchFollowersByUserId, Users_fetchFollowersCountByUserId as fetchFollowersCountByUserId, Users_fetchFollowingByUserId as fetchFollowingByUserId, Users_fetchFollowingCountByUserId as fetchFollowingCountByUserId, Users_fetchUserByForeignId as fetchUserByForeignId, Users_fetchUserById as fetchUserById, Users_fetchUserByUsername as fetchUserByUsername, Users_fetchUserSuggestions as fetchUserSuggestions, Users_removeConnectionByUserId as removeConnectionByUserId, Users_requestConnection as requestConnection, Users_updateUser as updateUser };
-}
+type WithOneWaySortDir<T extends {
+    sortBy?: unknown;
+    sortDir?: unknown;
+}> = (Omit<T, "sortBy" | "sortDir"> & {
+    sortBy: Extract<NonNullable<T["sortBy"]>, OneWaySort>;
+    sortDir?: never;
+}) | (Omit<T, "sortBy"> & {
+    sortBy?: Exclude<NonNullable<T["sortBy"]>, OneWaySort> | null;
+});
 
 /** The three grantable target kinds. Polymorphic — `targetId` carries no FK. */
 type ReputationGrantTargetType = "entity" | "comment" | "chat-message";
@@ -1288,13 +1167,6 @@ interface Reaction {
     user?: User;
 }
 
-interface TopComment {
-    id: string;
-    user: User;
-    upvotesCount: number;
-    content: string;
-    createdAt: string;
-}
 interface Entity {
     id: string;
     foreignId: string | null;
@@ -1315,7 +1187,7 @@ interface Entity {
     downvotes: string[];
     reactionCounts: ReactionCounts;
     userReaction?: ReactionType | null;
-    repliesCount: number;
+    commentsCount: number;
     views: number;
     score: number;
     scoreUpdatedAt: string;
@@ -1326,7 +1198,7 @@ interface Entity {
     metadata: Record<string, any>;
     nsfw: boolean;
     nsfwEffective: boolean;
-    topComment: TopComment | null;
+    topComments?: Comment[];
     isSaved?: boolean;
     /**
      * Reputation-grant summary. Opt-in — present exactly when the read requested
@@ -1345,6 +1217,292 @@ interface Entity {
     updatedAt: string;
     deletedAt: string | null;
 }
+/** `include` values the entity fetches (by id, short id, foreign id, and lists) accept. */
+type EntityInclude = "user" | "space" | "topComments" | "saved" | "files" | "grants";
+/** `include` values the collection-entities fetch accepts (no `saved`). */
+type CollectionEntityInclude = Exclude<EntityInclude, "saved">;
+type CollectionEntityIncludeArray = CollectionEntityInclude[];
+type CollectionEntityIncludeParam = CollectionEntityInclude | CollectionEntityIncludeArray;
+/** `include` values the drafts fetch accepts. */
+type DraftInclude = "user" | "space" | "files" | "grants";
+type DraftIncludeArray = DraftInclude[];
+type DraftIncludeParam = DraftInclude | DraftIncludeArray;
+/** Options for `include=topComments` (rejected without that include). */
+interface TopCommentsParams {
+    /** How many top comments per entity (default 1, max 5). */
+    topCommentsLimit?: number;
+    /** Which reaction's raw count ranks them (default "upvote"). */
+    topCommentsSortByReaction?: ReactionType;
+}
+
+interface GifData {
+    id: string;
+    url: string;
+    gifUrl: string;
+    gifPreviewUrl: string;
+    altText: string;
+    aspectRatio: string;
+}
+/**
+ * The entity attached to a comment by `include=entity` / `include=space`: the
+ * stored entity record only. The computed and associated fields an entity
+ * fetch adds (`commentsCount`, `userReaction`, `nsfwEffective`, `user`,
+ * `files`, `topComments`, `isSaved`, `grants`) are not included.
+ */
+type CommentEntity = Omit<Entity, "commentsCount" | "userReaction" | "nsfwEffective" | "user" | "files" | "topComments" | "isSaved" | "grants" | "space"> & {
+    space?: Omit<Space, "avatarFile" | "bannerFile"> | null;
+};
+interface Comment {
+    id: string;
+    foreignId: string | null;
+    entityId: string;
+    spaceId: string | null;
+    entity?: CommentEntity | null;
+    userId: string | null;
+    user?: User | null;
+    parentId: string | null;
+    parentComment?: Comment | null;
+    referencedCommentId: string | null;
+    content: string | null;
+    gif: GifData | null;
+    mentions: Mention[];
+    attachments: Record<string, any>[];
+    upvotes: string[];
+    downvotes: string[];
+    reactionCounts: ReactionCounts;
+    userReaction?: ReactionType | null;
+    repliesCount: number;
+    /**
+     * Reputation-grant summary. Opt-in — present exactly when the read requested
+     * `include=grants`. Once requested the server always returns the object,
+     * zero-filled rather than omitted, on projects with no grants and on projects
+     * without the reputation bundle alike.
+     */
+    grants?: GrantSummary;
+    metadata: Record<string, any> | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+    parentDeletedAt: string | null;
+    userDeletedAt: string | null;
+    moderationStatus: "approved" | "removed" | null;
+    moderatedAt: string | null;
+    moderatedById: string | null;
+    moderatedByType: "client" | "user" | null;
+    moderationReason: string | null;
+    /**
+     * The viewer blocked this comment's author, and the comment is returned in
+     * full. Present on thread, history, single-comment, `topComments` and
+     * reaction responses.
+     */
+    isAuthorBlocked?: boolean;
+    /**
+     * The comment exists but can't be shown to the viewer (a placeholder). The
+     * server refuses replies and reactions on it.
+     */
+    isUnavailable?: boolean;
+    /**
+     * Nested replies — present only on thread fetches with `replyDepth > 0`;
+     * absent at the depth boundary ("not fetched").
+     */
+    replies?: CursorPaginatedResponse<Comment>;
+}
+/** `include` values of a user's comment history and single-comment fetches. */
+type CommentInclude = "user" | "entity" | "space" | "parent" | "grants";
+type CommentIncludeArray = CommentInclude[];
+type CommentIncludeParam = CommentInclude | CommentIncludeArray;
+/** `include` values the thread endpoint (`GET /comments`) accepts. */
+type CommentThreadInclude = "user" | "grants";
+type CommentThreadIncludeArray = CommentThreadInclude[];
+type CommentThreadIncludeParam = CommentThreadInclude | CommentThreadIncludeArray;
+/** Comment sorts. Time order is `"createdAt"` with `sortDir`. */
+type CommentsSortBy = "createdAt" | "top" | "controversial";
+/** Sorts for the nested reply levels. */
+type CommentReplySortBy = "createdAt" | "top" | "controversial";
+
+interface FetchCommentsByUserIdBaseProps extends SpaceReputationContextParams {
+    userId: string;
+    /** Only comments on this entity. */
+    entityId?: string;
+    /** Only comments on entities from this source. */
+    sourceId?: string;
+    /**
+     * Comments by users block-edged with the viewer are hidden by default
+     * ("exclude"). "include-outbound-blocked" re-includes ONLY the viewer's own
+     * outbound-blocked authors; never inbound.
+     */
+    blockedFilter?: "exclude" | "include-outbound-blocked";
+    /** Server default "createdAt". */
+    sortBy?: CommentsSortBy;
+    /** Applies to every sort (server default "desc"). */
+    sortDir?: "asc" | "desc";
+    /** With `sortBy: "top"` only (server default "upvote"). */
+    sortByReaction?: ReactionType;
+    /** Server default 10, max 100. */
+    limit?: number;
+    /**
+     * `pagination.nextCursor` from the previous response, passed as returned;
+     * omit it (or pass `null`) for the first page.
+     */
+    cursor?: string | null;
+    include?: CommentIncludeParam;
+}
+/** `sortDir` is not accepted with `sortBy: "controversial"`. */
+type FetchCommentsByUserIdProps = WithOneWaySortDir<FetchCommentsByUserIdBaseProps>;
+/** A user's comment history (`GET /users/:userId/comments`): flat, any depth, cursor-paged. */
+declare function fetchCommentsByUserId(client: SublayHttpClient, data: FetchCommentsByUserIdProps): Promise<CursorPaginatedResponse<Comment>>;
+
+interface CreateFollowProps {
+    /** The user being followed (the target). The follower is the token holder. */
+    userId: string;
+}
+declare function createFollow(client: SublayHttpClient, data: CreateFollowProps): Promise<Follow>;
+
+interface DeleteFollowProps {
+    /** The user being unfollowed (the target). The follower is the token holder. */
+    userId: string;
+}
+declare function deleteFollow$1(client: SublayHttpClient, data: DeleteFollowProps): Promise<void>;
+
+interface FetchFollowStatusProps {
+    /**
+     * The user whose follow relationship is being checked (the target). The
+     * status is from the perspective of the token holder.
+     */
+    userId: string;
+}
+interface FollowStatusResponse {
+    isFollowing: boolean;
+    followId?: string;
+    followedAt?: string;
+}
+declare function fetchFollowStatus(client: SublayHttpClient, data: FetchFollowStatusProps): Promise<FollowStatusResponse>;
+
+interface RequestConnectionProps {
+    /**
+     * The user the connection is requested with (the target). The requester is
+     * the token holder.
+     */
+    userId: string;
+    message?: string;
+}
+declare function requestConnection(client: SublayHttpClient, data: RequestConnectionProps): Promise<ConnectionRequestResponse>;
+
+interface FetchConnectionStatusProps {
+    /**
+     * The other user in the connection (the target). The status is from the
+     * perspective of the token holder.
+     */
+    userId: string;
+}
+declare function fetchConnectionStatus(client: SublayHttpClient, data: FetchConnectionStatusProps): Promise<ConnectionStatusResponse>;
+
+interface RemoveConnectionByUserIdProps {
+    /**
+     * The other user in the connection (the target). The token holder is the
+     * user withdrawing/declining/disconnecting.
+     */
+    userId: string;
+}
+declare function removeConnectionByUserId(client: SublayHttpClient, data: RemoveConnectionByUserIdProps): Promise<RemoveConnectionByUserIdResponse>;
+
+interface CreateBlockProps {
+    /** The user being blocked (the target). The blocker is the token holder. */
+    userId: string;
+}
+interface BlockResponse {
+    id: string;
+    blockerId: string;
+    blockedId: string;
+    createdAt: string;
+}
+/**
+ * POST /users/:userId/block — block `:userId`.
+ *
+ * The blocker is derived from the token (Rule A — no `actingUserId`). Idempotent:
+ * re-blocking an already-blocked user succeeds. Self-block is rejected server-side.
+ * On a new block the server tears down existing follows/connections both ways.
+ */
+declare function createBlock(client: SublayHttpClient, data: CreateBlockProps): Promise<BlockResponse>;
+
+interface DeleteBlockProps {
+    /** The user being unblocked (the target). The blocker is the token holder. */
+    userId: string;
+}
+/**
+ * DELETE /users/:userId/block — unblock `:userId`.
+ *
+ * The blocker is derived from the token (Rule A — no `actingUserId`). Idempotent:
+ * unblocking a user who isn't blocked succeeds. Restores nothing (torn-down
+ * follows/connections are gone for good).
+ */
+declare function deleteBlock(client: SublayHttpClient, data: DeleteBlockProps): Promise<void>;
+
+interface FetchBlockStatusProps {
+    /**
+     * The user whose block status is being checked (the target). The status is the
+     * token holder's OUTBOUND state only: do *I* block `:userId`?
+     */
+    userId: string;
+}
+/**
+ * The block-status response is outbound-only by design: it reports whether the
+ * token holder blocks the target, and NEVER whether the target blocked the
+ * caller (the inbound direction is deliberately not disclosed).
+ */
+interface BlockStatusResponse {
+    blocked: boolean;
+    blockId?: string;
+    createdAt?: string;
+}
+/**
+ * GET /users/:userId/block — the token holder's outbound block status toward
+ * `:userId` (Rule A — no `actingUserId`).
+ */
+declare function fetchBlockStatus(client: SublayHttpClient, data: FetchBlockStatusProps): Promise<BlockStatusResponse>;
+
+interface FetchBlockedUsersProps {
+    page?: number;
+    limit?: number;
+}
+/** An entry in the token holder's own block list (their outbound blocks). */
+interface BlockedUserListItem {
+    id: string;
+    blockedUser: User | null;
+    createdAt: string;
+}
+/**
+ * GET /blocks — the token holder's own block list (their outbound blocks),
+ * paginated. This is the private "manage / way back to unblock" surface (Rule A
+ * — the subject is derived from the token, no `actingUserId`).
+ */
+declare function fetchBlockedUsers(client: SublayHttpClient, data?: FetchBlockedUsersProps): Promise<PaginatedResponse<BlockedUserListItem>>;
+
+declare const Users_checkUsernameAvailability: typeof checkUsernameAvailability;
+declare const Users_createBlock: typeof createBlock;
+declare const Users_createFollow: typeof createFollow;
+declare const Users_deleteBlock: typeof deleteBlock;
+declare const Users_fetchBlockStatus: typeof fetchBlockStatus;
+declare const Users_fetchBlockedUsers: typeof fetchBlockedUsers;
+declare const Users_fetchCommentsByUserId: typeof fetchCommentsByUserId;
+declare const Users_fetchConnectionStatus: typeof fetchConnectionStatus;
+declare const Users_fetchConnectionsByUserId: typeof fetchConnectionsByUserId;
+declare const Users_fetchConnectionsCountByUserId: typeof fetchConnectionsCountByUserId;
+declare const Users_fetchFollowStatus: typeof fetchFollowStatus;
+declare const Users_fetchFollowersByUserId: typeof fetchFollowersByUserId;
+declare const Users_fetchFollowersCountByUserId: typeof fetchFollowersCountByUserId;
+declare const Users_fetchFollowingByUserId: typeof fetchFollowingByUserId;
+declare const Users_fetchFollowingCountByUserId: typeof fetchFollowingCountByUserId;
+declare const Users_fetchUserByForeignId: typeof fetchUserByForeignId;
+declare const Users_fetchUserById: typeof fetchUserById;
+declare const Users_fetchUserByUsername: typeof fetchUserByUsername;
+declare const Users_fetchUserSuggestions: typeof fetchUserSuggestions;
+declare const Users_removeConnectionByUserId: typeof removeConnectionByUserId;
+declare const Users_requestConnection: typeof requestConnection;
+declare const Users_updateUser: typeof updateUser;
+declare namespace Users {
+  export { Users_checkUsernameAvailability as checkUsernameAvailability, Users_createBlock as createBlock, Users_createFollow as createFollow, Users_deleteBlock as deleteBlock, deleteFollow$1 as deleteFollow, Users_fetchBlockStatus as fetchBlockStatus, Users_fetchBlockedUsers as fetchBlockedUsers, Users_fetchCommentsByUserId as fetchCommentsByUserId, Users_fetchConnectionStatus as fetchConnectionStatus, Users_fetchConnectionsByUserId as fetchConnectionsByUserId, Users_fetchConnectionsCountByUserId as fetchConnectionsCountByUserId, Users_fetchFollowStatus as fetchFollowStatus, Users_fetchFollowersByUserId as fetchFollowersByUserId, Users_fetchFollowersCountByUserId as fetchFollowersCountByUserId, Users_fetchFollowingByUserId as fetchFollowingByUserId, Users_fetchFollowingCountByUserId as fetchFollowingCountByUserId, Users_fetchUserByForeignId as fetchUserByForeignId, Users_fetchUserById as fetchUserById, Users_fetchUserByUsername as fetchUserByUsername, Users_fetchUserSuggestions as fetchUserSuggestions, Users_removeConnectionByUserId as removeConnectionByUserId, Users_requestConnection as requestConnection, Users_updateUser as updateUser };
+}
 
 interface CreateEntityProps {
     foreignId?: string;
@@ -1367,20 +1525,20 @@ interface CreateEntityProps {
 }
 declare function createEntity(client: SublayHttpClient, data: CreateEntityProps): Promise<Entity>;
 
-interface FetchEntityProps extends SpaceReputationContextParams {
+interface FetchEntityProps extends SpaceReputationContextParams, TopCommentsParams {
     entityId: string;
     include?: string;
 }
 declare function fetchEntity(client: SublayHttpClient, data: FetchEntityProps): Promise<Entity>;
 
-interface FetchEntityByForeignIdProps {
+interface FetchEntityByForeignIdProps extends TopCommentsParams {
     foreignId: string;
     createIfNotFound?: boolean;
     include?: string;
 }
 declare function fetchEntityByForeignId(client: SublayHttpClient, data: FetchEntityByForeignIdProps): Promise<Entity>;
 
-interface FetchEntityByShortIdProps {
+interface FetchEntityByShortIdProps extends TopCommentsParams {
     shortId: string;
     include?: string;
 }
@@ -1416,16 +1574,13 @@ interface LocationFilters {
     longitude: string;
     radius: string;
 }
-interface FetchManyEntitiesProps extends SpaceReputationContextParams {
+interface FetchManyEntitiesBaseProps extends SpaceReputationContextParams, TopCommentsParams {
     sourceId?: string;
     spaceId?: string;
-    sortBy?: "createdAt" | "hot" | "top" | "controversial"
-    /** @deprecated Use "createdAt" instead. "new" is a directional alias removed
-     * in v8; the server still accepts it (identical behavior) but responds with
-     * deprecation headers. */
-     | "new" | (string & {});
+    sortBy?: "createdAt" | "hot" | "top" | "controversial" | `metadata.${string}`;
     sortDir?: "asc" | "desc";
     sortType?: "auto" | "numeric" | "text" | "boolean" | "timestamp";
+    /** Which reaction `top` ranks by (server default: "upvote"). Only valid with `sortBy: "top"` — the server rejects it otherwise. */
     sortByReaction?: "upvote" | "downvote" | "like" | "love" | "wow" | "sad" | "angry" | "funny";
     page?: number;
     limit?: number;
@@ -1446,6 +1601,8 @@ interface FetchManyEntitiesProps extends SpaceReputationContextParams {
     nsfwFilter?: "include-all" | "exclude" | "only";
     blockedFilter?: "exclude" | "include-outbound-blocked";
 }
+/** `sortDir` is not accepted with `sortBy: "hot"` or `"controversial"`. */
+type FetchManyEntitiesProps = WithOneWaySortDir<FetchManyEntitiesBaseProps>;
 declare function fetchManyEntities(client: SublayHttpClient, data: FetchManyEntitiesProps): Promise<PaginatedResponse<Entity>>;
 
 interface UpdateEntityProps {
@@ -1474,7 +1631,7 @@ interface FetchDraftsProps {
     limit?: number;
     sourceId?: string;
     spaceId?: string;
-    include?: string;
+    include?: DraftIncludeParam;
 }
 declare function fetchDrafts(client: SublayHttpClient, data: FetchDraftsProps): Promise<PaginatedResponse<Entity>>;
 
@@ -1483,11 +1640,6 @@ interface PublishDraftProps {
 }
 declare function publishDraft(client: SublayHttpClient, data: PublishDraftProps): Promise<Entity>;
 
-interface FetchTopCommentProps {
-    entityId: string;
-}
-declare function fetchTopComment(client: SublayHttpClient, data: FetchTopCommentProps): Promise<TopComment | null>;
-
 interface AddEntityReactionProps {
     entityId: string;
     reactionType: ReactionType;
@@ -1539,12 +1691,11 @@ declare const Entities_fetchEntity: typeof fetchEntity;
 declare const Entities_fetchEntityByForeignId: typeof fetchEntityByForeignId;
 declare const Entities_fetchEntityByShortId: typeof fetchEntityByShortId;
 declare const Entities_fetchManyEntities: typeof fetchManyEntities;
-declare const Entities_fetchTopComment: typeof fetchTopComment;
 declare const Entities_isEntitySaved: typeof isEntitySaved;
 declare const Entities_publishDraft: typeof publishDraft;
 declare const Entities_updateEntity: typeof updateEntity;
 declare namespace Entities {
-  export { addReaction$1 as addReaction, Entities_createEntity as createEntity, Entities_deleteEntity as deleteEntity, Entities_fetchDrafts as fetchDrafts, Entities_fetchEntity as fetchEntity, Entities_fetchEntityByForeignId as fetchEntityByForeignId, Entities_fetchEntityByShortId as fetchEntityByShortId, Entities_fetchManyEntities as fetchManyEntities, fetchReactions$1 as fetchReactions, Entities_fetchTopComment as fetchTopComment, getUserReaction$1 as getUserReaction, Entities_isEntitySaved as isEntitySaved, Entities_publishDraft as publishDraft, removeReaction$1 as removeReaction, Entities_updateEntity as updateEntity };
+  export { addReaction$1 as addReaction, Entities_createEntity as createEntity, Entities_deleteEntity as deleteEntity, Entities_fetchDrafts as fetchDrafts, Entities_fetchEntity as fetchEntity, Entities_fetchEntityByForeignId as fetchEntityByForeignId, Entities_fetchEntityByShortId as fetchEntityByShortId, Entities_fetchManyEntities as fetchManyEntities, fetchReactions$1 as fetchReactions, getUserReaction$1 as getUserReaction, Entities_isEntitySaved as isEntitySaved, Entities_publishDraft as publishDraft, removeReaction$1 as removeReaction, Entities_updateEntity as updateEntity };
 }
 
 type EventType = "online" | "physical" | "hybrid";
@@ -1840,52 +1991,6 @@ declare namespace Events {
   export { Events_addHost as addHost, Events_addInvite as addInvite, Events_cancelEvent as cancelEvent, Events_createEvent as createEvent, Events_deleteEvent as deleteEvent, Events_fetchEvent as fetchEvent, Events_fetchEventRsvps as fetchEventRsvps, Events_fetchInvitees as fetchInvitees, Events_fetchManyEvents as fetchManyEvents, Events_removeHost as removeHost, Events_removeInvite as removeInvite, Events_setRsvp as setRsvp, Events_updateEvent as updateEvent, Events_withdrawRsvp as withdrawRsvp };
 }
 
-interface GifData {
-    id: string;
-    url: string;
-    gifUrl: string;
-    gifPreviewUrl: string;
-    altText: string;
-    aspectRatio: string;
-}
-interface Comment {
-    id: string;
-    projectId: string;
-    foreignId: string | null;
-    entityId: string;
-    entity?: Entity;
-    userId: string;
-    user?: User;
-    parentId: string | null;
-    parentComment?: Comment;
-    content: string | null;
-    gif: GifData | null;
-    mentions: Mention[];
-    upvotes: string[];
-    downvotes: string[];
-    reactionCounts: ReactionCounts;
-    userReaction?: ReactionType | null;
-    repliesCount: number;
-    /**
-     * Reputation-grant summary. Opt-in — present exactly when the read requested
-     * `include=grants`. Once requested the server always returns the object,
-     * zero-filled rather than omitted, on projects with no grants and on projects
-     * without the reputation bundle alike.
-     */
-    grants?: GrantSummary;
-    metadata: Record<string, any>;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | null;
-    parentDeletedAt: string | null;
-    userDeletedAt: string | null;
-    moderationStatus: "approved" | "removed" | null;
-    moderatedAt: string | null;
-    moderatedById: string | null;
-    moderatedByType: "client" | "user" | null;
-    moderationReason: string | null;
-}
-
 interface CreateCommentProps {
     entityId: string;
     foreignId?: string;
@@ -1925,28 +2030,45 @@ interface DeleteCommentProps {
 }
 declare function deleteComment(client: SublayHttpClient, data: DeleteCommentProps): Promise<void>;
 
-interface FetchManyCommentsProps extends SpaceReputationContextParams {
-    entityId?: string;
-    userId?: string;
-    parentId?: string;
-    page?: number;
+interface FetchManyCommentsBaseProps extends SpaceReputationContextParams {
+    /** How many comments at the level being fetched (server default 10, max 100). */
     limit?: number;
-    sortBy?: "createdAt" | "top" | "controversial"
-    /** @deprecated Use "createdAt" instead. "new" is a directional alias for
-     * createdAt DESC, removed in v8; the server still accepts it (identical
-     * behavior) but responds with deprecation headers. */
-     | "new"
-    /** @deprecated Use "createdAt" with sortDir:"asc" instead. "old" is a
-     * directional alias for createdAt ASC, removed in v8; the server still
-     * accepts it (identical behavior) but responds with deprecation headers. */
-     | "old";
-    /** Sort direction for `sortBy: "createdAt"`. Defaults to "desc". */
+    /**
+     * `pagination.nextCursor` from the previous response, passed as returned;
+     * omit it (or pass `null`) for the first page.
+     */
+    cursor?: string | null;
+    /** Sort for the level being fetched (server default "createdAt"). */
+    sortBy?: CommentsSortBy;
+    /** Applies to every sort (server default "desc"). */
     sortDir?: "asc" | "desc";
-    include?: string;
-    sourceId?: string;
-    blockedFilter?: "exclude" | "include-outbound-blocked";
+    /** With `sortBy: "top"` only: rank by this reaction's raw count (server default "upvote"). */
+    sortByReaction?: ReactionType;
+    include?: CommentThreadIncludeParam;
+    /** Levels of replies to nest under each returned comment (0–5, server default 0). */
+    replyDepth?: number;
+    /** Replies per comment in the nested levels only (≥ 1, server default 3). */
+    replyLimit?: number;
+    /** Sort for the nested levels; each defaults to the level's own. */
+    replySortBy?: CommentReplySortBy;
+    replySortDir?: "asc" | "desc";
+    replySortByReaction?: ReactionType;
 }
-declare function fetchManyComments(client: SublayHttpClient, data: FetchManyCommentsProps): Promise<PaginatedResponse<Comment>>;
+/**
+ * A thread fetch (`GET /comments`): `entityId` → that entity's top-level
+ * comments; `parentId` (alone — the parent decides the entity) → a comment's
+ * direct replies. Exactly one of the two, and no `sortDir` with
+ * `sortBy: "controversial"`. A user's comment history is
+ * `users.fetchCommentsByUserId`.
+ */
+type FetchManyCommentsProps = WithOneWaySortDir<FetchManyCommentsBaseProps & {
+    entityId: string;
+    parentId?: null;
+}> | WithOneWaySortDir<FetchManyCommentsBaseProps & {
+    parentId: string;
+    entityId?: null;
+}>;
+declare function fetchManyComments(client: SublayHttpClient, data: FetchManyCommentsProps): Promise<CursorPaginatedResponse<Comment>>;
 
 interface AddCommentReactionProps {
     commentId: string;
@@ -2024,7 +2146,8 @@ declare function createSpace(client: SublayHttpClient, data: CreateSpaceProps):
 interface FetchManySpacesProps {
     page?: number;
     limit?: number;
-    sortBy?: "alphabetical" | "newest" | "members";
+    sortBy?: "createdAt" | "alphabetical" | "members";
+    sortDir?: "asc" | "desc";
     searchSlug?: string;
     searchName?: string;
     searchDescription?: string;
@@ -2054,7 +2177,8 @@ declare function fetchSpaceBySlug(client: SublayHttpClient, data: FetchSpaceBySl
 interface FetchUserSpacesProps {
     page?: number;
     limit?: number;
-    sortBy?: "alphabetical" | "newest" | "members";
+    sortBy?: "createdAt" | "alphabetical" | "members" | "joinedAt";
+    sortDir?: "asc" | "desc";
     include?: string;
     role?: string;
     all?: "true" | "false";
@@ -2113,7 +2237,8 @@ interface FetchChildSpacesProps {
     spaceId: string;
     page?: number;
     limit?: number;
-    sortBy?: "alphabetical" | "newest" | "members";
+    sortBy?: "createdAt" | "alphabetical" | "members";
+    sortDir?: "asc" | "desc";
     include?: string;
 }
 declare function fetchChildSpaces(client: SublayHttpClient, data: FetchChildSpacesProps): Promise<PaginatedResponse<Space>>;
@@ -2192,6 +2317,8 @@ declare function declineMembership(client: SublayHttpClient, data: DeclineMember
 interface BanMemberProps {
     spaceId: string;
     memberId: string;
+    /** Why the member is banned; kept in the space's ban log. */
+    reason?: string;
 }
 interface BanMemberResponse {
     message: string;
@@ -2283,9 +2410,9 @@ interface HandleEntityReportProps {
     entityId: string;
     actions: EntityReportAction[];
     summary?: string;
+    /** Why the user is banned, required when actions include "ban-user". The
+     * banned user is always the author of the reported content. */
     reason?: string;
-    /** The user to ban (target), required when actions include "ban-user". */
-    userId?: string;
 }
 interface HandleReportResponse {
     message: string;
@@ -2300,9 +2427,9 @@ interface HandleCommentReportProps {
     commentId: string;
     actions: CommentReportAction[];
     summary?: string;
+    /** Why the user is banned, required when actions include "ban-user". The
+     * banned user is always the author of the reported content. */
     reason?: string;
-    /** The user to ban (target), required when actions include "ban-user". */
-    userId?: string;
 }
 declare function handleCommentReport(client: SublayHttpClient, data: HandleCommentReportProps): Promise<HandleReportResponse>;
 
@@ -2442,8 +2569,8 @@ interface HandleSpaceChatReportProps {
     reportId: string;
     actions: SpaceChatReportAction[];
     summary?: string;
-    /** The user to ban (target), required when actions include "ban-user". */
-    userId?: string;
+    /** Why the user is banned, required when actions include "ban-user". The
+     * banned user is always the author of the reported content. */
     reason?: string;
     /** The message to remove, required when actions include "remove-message". */
     messageId?: string;
@@ -2519,15 +2646,19 @@ interface CreateNewCollectionProps {
 }
 declare function createNewCollection(client: SublayHttpClient, data: CreateNewCollectionProps): Promise<Collection>;
 
-interface FetchCollectionEntitiesProps {
+interface FetchCollectionEntitiesBaseProps extends TopCommentsParams {
     collectionId: string;
     page?: number;
     limit?: number;
-    sortBy?: "new" | "added" | "top" | "hot";
+    sortBy?: "createdAt" | "addedAt" | "top" | "hot";
+    /** Which reaction `top` ranks by (server default: "upvote"). Only valid with `sortBy: "top"` — the server rejects it otherwise. */
+    sortByReaction?: "upvote" | "downvote" | "like" | "love" | "wow" | "sad" | "angry" | "funny";
     sortDir?: "asc" | "desc";
-    /** Comma-separated list of associations to populate, e.g. "user". */
-    include?: string;
+    /** Associations to populate (no "saved": every item in a collection is saved). */
+    include?: CollectionEntityIncludeParam;
 }
+/** `sortDir` is not accepted with `sortBy: "hot"`. */
+type FetchCollectionEntitiesProps = WithOneWaySortDir<FetchCollectionEntitiesBaseProps>;
 declare function fetchCollectionEntities(client: SublayHttpClient, data: FetchCollectionEntitiesProps): Promise<PaginatedResponse<Entity>>;
 
 interface AddEntityToCollectionProps {
@@ -2982,7 +3113,9 @@ interface FetchModeratedReportsProps extends SpaceReputationContextParams {
     spaceId?: string;
     targetType?: ReportTargetType;
     status?: ReportStatus;
-    sortBy?: "new" | "old";
+    /** Time order: `createdAt` in `sortDir` (server default desc, newest first). */
+    sortBy?: "createdAt";
+    sortDir?: "asc" | "desc";
     page?: number;
     limit?: number;
 }
@@ -3535,7 +3668,7 @@ interface ListMessagesProps extends SpaceReputationContextParams {
     after?: string;
     /** Page size (default 50, max 100). */
     limit?: number;
-    sort?: "asc" | "desc";
+    sortDir?: "asc" | "desc";
     /**
      * Comma-separated associations to populate: `"files"` (message
      * attachments) and `"grants"` (the reputation-grant summary). Combine
@@ -4395,4 +4528,4 @@ declare class SublayClient {
     clearTokens(): void;
 }
 
-export { type AuthTokens, type BulkDeleteProps, type BulkDeleteResult, type ClientConfig, type CreateGrantProps, type DbFilter, type DbFilterOperator, type DeleteResult, type GrantSummary, type ListGrantsProps, type ListGrantsResponse, MUTE_DURATIONS, type MuteConversationProps, type MuteConversationResponse, type MuteDuration, type MyWorkspaceInvitation, type NotificationPreferences, PUSH_EVENT_TYPES, type PaginatedResponse, type PaginationMetadata, type PushDeviceIdentifier, type PushEventType, type PushUnbindSkipReason, type RemoveWorkspaceMemberFromSubtreeResponse, type ReputationGrant, type ReputationGrantSourceType, type ReputationGrantTargetFilter, type ReputationGrantTargetType, type SignOutResult, type SkippedWorkspace, type SpaceReputationContextParams, type SpaceReputationUserParams, SublayClient, type TableAccessor, type TableQuery, type TableRow, type UpdateNotificationPreferencesProps, type UserSearchParams, type WebPushSubscription, type Workspace, type WorkspaceAuthority, type WorkspaceAuthorityReason, type WorkspaceAuthorityReasonDetail, type WorkspaceCapability, type WorkspaceInvitation, type WorkspaceInvitationInviter, type WorkspaceInvitationStatus, type WorkspaceMember, type WorkspaceMemberStanding, type WorkspaceRosterCountsResponse, type WorkspaceRosterEntry, type WorkspaceRosterReason, type WorkspaceRosterResponse, type WorkspaceStandingUser };
+export { type AuthTokens, type BulkDeleteProps, type BulkDeleteResult, type ClientConfig, type CollectionEntityInclude, type CollectionEntityIncludeArray, type CollectionEntityIncludeParam, type Comment, type CommentEntity, type CommentInclude, type CommentIncludeArray, type CommentIncludeParam, type CommentReplySortBy, type CommentThreadInclude, type CommentThreadIncludeArray, type CommentThreadIncludeParam, type CommentsSortBy, type CreateGrantProps, type CursorPaginatedResponse, type CursorPagination, type DbFilter, type DbFilterOperator, type DeleteResult, type DraftInclude, type DraftIncludeArray, type DraftIncludeParam, type Entity, type EntityInclude, type GifData, type GrantSummary, type ListGrantsProps, type ListGrantsResponse, MUTE_DURATIONS, type MuteConversationProps, type MuteConversationResponse, type MuteDuration, type MyWorkspaceInvitation, type NotificationPreferences, PUSH_EVENT_TYPES, type PaginatedResponse, type PaginationMetadata, type PushDeviceIdentifier, type PushEventType, type PushUnbindSkipReason, type RemoveWorkspaceMemberFromSubtreeResponse, type ReputationGrant, type ReputationGrantSourceType, type ReputationGrantTargetFilter, type ReputationGrantTargetType, type SignOutResult, type SkippedWorkspace, type SpaceReputationContextParams, type SpaceReputationUserParams, SublayClient, type TableAccessor, type TableQuery, type TableRow, type TopCommentsParams, type UpdateNotificationPreferencesProps, type UserSearchParams, type WebPushSubscription, type Workspace, type WorkspaceAuthority, type WorkspaceAuthorityReason, type WorkspaceAuthorityReasonDetail, type WorkspaceCapability, type WorkspaceInvitation, type WorkspaceInvitationInviter, type WorkspaceInvitationStatus, type WorkspaceMember, type WorkspaceMemberStanding, type WorkspaceRosterCountsResponse, type WorkspaceRosterEntry, type WorkspaceRosterReason, type WorkspaceRosterResponse, type WorkspaceStandingUser };