@recursiv/sdk 0.7.73 → 0.7.77

package/README.md

@@ -93,7 +93,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 ### Social
 | Resource | Key methods |
 |----------|------------|
-| `r.posts` | `create`, `update`, `list`, `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
+| `r.posts` | `create`, `update`, `list`, `get`, `getMany(ids)` (up to 25 posts by id per request, no thread; a `Map` of each id's post or `NotFoundError`; 0.7.77), `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices; `collections`: `list`, `create`, `update`, `remove`, `add`, `removeItem`, `items`, `posts` — private named collections of saves (0.7.68, where `network.getConfig()` advertises `capabilities.bookmark_collections`) |
 | `r.feeds` | `top` (what the member is most likely to engage with, rotated by what they saw, with open-network lanes and the lead story), `stories` (the story tail), `publicTop` (a visitor's top, keyless and edge-cacheable) |
 | `r.communities` | `create`, `join`, `search`, `members` |
@@ -117,9 +117,10 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.github` | GitHub integration |
 | `r.integrations` | External service connections |
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
+| `r.moderation` | Moderation actions: `publicLog`, `mine`, `appeal`; staff `apply`, `resolveAppeal`, `list({ target_type?, target_id? })` (one target's recorded actions, newest first, at most 100; none named = the network's latest; 0.7.74) and `reverse(actionId)` (sent once: a repeat answers 404 `action_not_found`; 0.7.74); agent grants `listAgentGrants`, `grantAgent`, `revokeAgent` |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); the Viral read (fastest-moving posts across Bluesky, the Fediverse, Nostr and Minds, each against its own network's pace; 0.7.59): `getPublicViral({ network?, category?, media?: 'video', limit?: 5 | 10 | 20 | 40, cursor?, compass? })` under the member's key and keyless `getSharedViral(projectId, params)` (visitors: `compass` `all` or `hide` only; a visitor's `media: 'video'` read can carry items whose video the server withheld, so filter with the exported `viralItemHasVideo` before a video player; `item.post` narrows on `item.protocol`). `status: 'off'` resolves with no items until the app enables the read, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401 and 403, so a session failure is never read as off; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
+| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id; a story a World Today story seeded carries `volume`, the first page of the posts that story counts across Minds and the open networks, whose `cursor` goes on with `curator.storyPosts` or `curator.memberStoryPosts`), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); the Viral read (fastest-moving posts across Bluesky, the Fediverse, Nostr and Minds, each against its own network's pace; 0.7.59): `getPublicViral({ network?, category?, media?: 'video', limit?: 5 | 10 | 20 | 40, cursor?, compass? })` under the member's key and keyless `getSharedViral(projectId, params)` (visitors: `compass` `all` or `hide` only; a visitor's `media: 'video'` read can carry items whose video the server withheld, so filter with the exported `viralItemHasVideo` before a video player; `item.post` narrows on `item.protocol`). `status: 'off'` resolves with no items until the app enables the read, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401 and 403, so a session failure is never read as off; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 

package/dist/index.d.ts

@@ -158,8 +158,8 @@ export { RealtimeClient } from './realtime.js';
 export type { RealtimeConnectOptions } from './realtime.js';
 export { AuthResource } from './resources/auth.js';
 export type { AuthSession, CurrentSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, LegacyHandoffOptions, LegacyHandoffSession, } from './resources/auth.js';
-export { PostsResource } from './resources/posts.js';
-export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason } from './resources/posts.js';
+export { POSTS_BATCH_MAX, PostsResource } from './resources/posts.js';
+export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason, PostBatch, PostBatchItem } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';
@@ -208,7 +208,7 @@ export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, R
 export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgments.js';
 export type { JudgmentSubjectKind, JudgmentSource, JudgmentOverrideMethod, PostLabelsStatus, PostLabelsQuery, PostLabelsSubject, PostLabelsCategory, PostLabelsPolitics, PostJudgmentRecord, PostJudgment, PostSafetyAttribution, PostLabelsCategoryView, PostLabelsSummaryView, PostLabelsFullView, PostLabels, DisputeJudgmentInput, JudgmentDispute, ReviewJudgmentInput, JudgmentReviewUpheld, JudgmentReviewAwaitingReviewer, JudgmentReviewOverridden, JudgmentReview, JudgmentSharedWordsDetails, JudgmentSharedWordsError, } from './resources/judgments.js';
 export { ModerationResource } from './resources/moderation.js';
-export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, AgentModerationMode, AgentModerationGrant, } from './resources/moderation.js';
+export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, ModerationAction, ListModerationActionsParams, RecordedModerationTargetType, AgentModerationMode, AgentModerationGrant, } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export type { SearchAnswer, SearchGroup, SearchOmitReason, SearchParams, SearchPerson, SearchRelated, SearchResponse, SearchSection, SearchStory, SearchTopic } from './resources/search.js';

package/dist/index.js

@@ -229,7 +229,7 @@ export class Recursiv {
 export { HttpClient } from './client.js';
 export { RealtimeClient } from './realtime.js';
 export { AuthResource } from './resources/auth.js';
-export { PostsResource } from './resources/posts.js';
+export { POSTS_BATCH_MAX, PostsResource } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';

package/dist/resources/discovery.d.ts

@@ -23,10 +23,10 @@ export interface WatchVideosParams {
     /** A position in the list to start a first read at (0 to 400); a later page sends `cursor`. */
     offset?: number;
     /**
-     * A Politics choice, spelled as `posts.list` takes it. Only Hide politics (`hide`) is applied here: the videos whose
-     * browse category is politics (or whose compass judgment places them in politics) leave the page and the next ones
-     * fill it, with or without compass judgments on the server. A side or Mix is answered unfiltered, marked
-     * `unavailable`. The page says what it did in `meta.compass_filter`.
+     * A Politics choice, spelled as `posts.list` takes it. Only Hide politics (`hide`) is applied here, strictly: the
+     * videos whose browse category is politics, whose compass judgment calls them political or maybe, or whose title or
+     * words name politics leave the page and the next ones fill it, with or without compass judgments on the server. A
+     * side or Mix is answered unfiltered, marked `unavailable`. The page says what it did in `meta.compass_filter`.
      */
     compass?: string;
 }

package/dist/resources/moderation.d.ts

@@ -63,6 +63,30 @@ export interface ApplyModerationActionInput {
     actor_type?: 'human' | 'ai' | 'system';
     source_report_id?: string;
 }
+/** Where an action can be recorded: `source_item` is one open-network post withheld from promotion surfaces. */
+export type RecordedModerationTargetType = ModerationTargetType | 'source_item';
+/** One recorded action as staff read it (GET /moderation/actions): who did what to which target, and why. */
+export interface ModerationAction {
+    id: string;
+    target_type: RecordedModerationTargetType;
+    target_id: string;
+    action: ModerationActionType;
+    label: string | null;
+    reason: string | null;
+    /** The moderator or agent who acted; null for a system or classifier action. */
+    actor_id: string | null;
+    actor_type: 'human' | 'ai' | 'system';
+    source_report_id: string | null;
+    expires_at: string | null;
+    /** Null while the action is in force. */
+    reversed_at: string | null;
+    created_at: string;
+}
+/** Both fields, for one target's history; neither, for the network's latest actions. */
+export interface ListModerationActionsParams {
+    target_type?: RecordedModerationTargetType;
+    target_id?: string;
+}
 /** What a granted agent may do on the report queue: shadow reads it; act also resolves and dismisses. */
 export type AgentModerationMode = 'shadow' | 'act';
 /** A network admin's grant letting one AI agent work the report queue. */
@@ -88,6 +112,23 @@ export declare class ModerationResource {
         success: true;
         id: string;
     }>>;
+    /**
+     * Admin (0.7.74): recorded actions, newest first (at most 100), inside the caller's
+     * network and a bound key's app. Name a target (both fields) for its history,
+     * e.g. to reverse a ban still in force; name none for the latest actions.
+     */
+    list(params?: ListModerationActionsParams): Promise<SingleResponse<ModerationAction[]>>;
+    /**
+     * Admin (0.7.74): reverse an action; the target's state is derived again from what is
+     * still in force (an account is unbanned when its last ban goes) and the
+     * public log shows the reversal. Sent once, never retried: a repeat of a
+     * reversal that landed answers 404 `action_not_found` (`NotFoundError`), as
+     * does an action already reversed. A reviewed label override answers 409
+     * `use_judgment_review`.
+     */
+    reverse(actionId: string): Promise<SingleResponse<{
+        success: true;
+    }>>;
     /**
      * List decisions affecting the caller or content they own. This remains
      * reachable through a valid key while the account is suspended or banned.

package/dist/resources/moderation.js

@@ -15,6 +15,28 @@ export class ModerationResource {
     apply(input) {
         return this.client.post('/moderation/actions', input);
     }
+    /**
+     * Admin (0.7.74): recorded actions, newest first (at most 100), inside the caller's
+     * network and a bound key's app. Name a target (both fields) for its history,
+     * e.g. to reverse a ban still in force; name none for the latest actions.
+     */
+    list(params = {}) {
+        return this.client.get('/moderation/actions', {
+            target_type: params.target_type,
+            target_id: params.target_id,
+        });
+    }
+    /**
+     * Admin (0.7.74): reverse an action; the target's state is derived again from what is
+     * still in force (an account is unbanned when its last ban goes) and the
+     * public log shows the reversal. Sent once, never retried: a repeat of a
+     * reversal that landed answers 404 `action_not_found` (`NotFoundError`), as
+     * does an action already reversed. A reviewed label override answers 409
+     * `use_judgment_review`.
+     */
+    reverse(actionId) {
+        return this.client.post(`/moderation/actions/${encodeURIComponent(actionId)}/reverse`, undefined, { retry: false });
+    }
     /**
      * List decisions affecting the caller or content they own. This remains
      * reachable through a valid key while the account is suspended or banned.

package/dist/resources/posts.d.ts

@@ -1,4 +1,5 @@
 import type { HttpClient } from '../client.js';
+import { RecursivError } from '../errors.js';
 import type { PaginatedResponse, SingleResponse, DeleteResponse, Post, PostDetail, CreatePostInput, CreatedPost, UpdatePostInput, ListPostsParams, ListPostRepliesParams, PostRepliesPage, SearchPostsParams, SearchPostsResponse, ReactionType } from '../types.js';
 import type { BookmarkedPost, BookmarksPage, SavedBookmark, UnsavedBookmark } from './bookmarks.js';
 /** How GET /posts/categories ordered its answer: the member's own order, the app's popularity order, or the fixed order. */
@@ -14,6 +15,21 @@ export interface CategoryOrderMeta {
     /** Whether For You can personalize for this member yet; absent when the member's order was not read. */
     personalized?: boolean;
 }
+/** The most ids one GET /posts/batch request carries: `posts.getMany` sends one request per this many (0.7.77). */
+export declare const POSTS_BATCH_MAX = 25;
+/** A post `posts.getMany` read: the post as `posts.get` serves it to the caller, without its thread (no `replies`). */
+export type PostBatchItem = Omit<PostDetail, 'replies' | 'replies_next_cursor'>;
+/**
+ * What `posts.getMany` found for each id it read: the post, or the error that id's read answered. A `NotFoundError`
+ * (status 404) is a post that is gone, was never there, or is not for this caller, as `posts.get` answers it.
+ */
+export type PostBatch = Map<string, {
+    data: PostBatchItem;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: RecursivError;
+}>;
 export declare class PostsResource {
     private client;
     constructor(client: HttpClient);
@@ -54,6 +70,15 @@ export declare class PostsResource {
     }): Promise<PaginatedResponse<Post>>;
     /** Get a single post with its newest replies; `replies_next_cursor` is set when the thread continues. */
     get(id: string): Promise<SingleResponse<PostDetail>>;
+    /**
+     * Several posts by id, one request per POSTS_BATCH_MAX ids (GET /posts/batch; 0.7.77), each id answered on its own:
+     * the post as `get` serves it to the caller, `viewer` and the caller's own vote and repost included, without its
+     * thread (the server reads no replies and no chain for it, so a batch of six answers about as fast as one post), or
+     * the error that read answered (`NotFoundError` for one that is gone or not for this caller). Each id is asked once
+     * (blank ones are dropped) and the Map is keyed by the ids as given. A request that fails as a whole throws, as an
+     * API without this route does (404): read those ids one by one with `get`.
+     */
+    getMany(ids: readonly string[]): Promise<PostBatch>;
     /** One page of a post's replies, newest first. Start from `replies_next_cursor` on `get`, then follow `meta.next_cursor`. */
     replies(id: string, params?: ListPostRepliesParams): Promise<PostRepliesPage>;
     /** Create a new post */

package/dist/resources/posts.js

@@ -1,3 +1,13 @@
+import { errorBodyFromResponse, NotFoundError, RecursivError } from '../errors.js';
+/** The most ids one GET /posts/batch request carries: `posts.getMany` sends one request per this many (0.7.77). */
+export const POSTS_BATCH_MAX = 25;
+/** One entry's error as the error `posts.get` throws for it. */
+function postBatchError(error) {
+    const status = error && typeof error === 'object' && typeof error.status === 'number'
+        ? error.status : 404;
+    const body = errorBodyFromResponse(status, undefined, { error });
+    return status === 404 ? new NotFoundError(body) : new RecursivError(status, body);
+}
 export class PostsResource {
     client;
     constructor(client) {
@@ -48,6 +58,35 @@ export class PostsResource {
     get(id) {
         return this.client.get(`/posts/${id}`);
     }
+    /**
+     * Several posts by id, one request per POSTS_BATCH_MAX ids (GET /posts/batch; 0.7.77), each id answered on its own:
+     * the post as `get` serves it to the caller, `viewer` and the caller's own vote and repost included, without its
+     * thread (the server reads no replies and no chain for it, so a batch of six answers about as fast as one post), or
+     * the error that read answered (`NotFoundError` for one that is gone or not for this caller). Each id is asked once
+     * (blank ones are dropped) and the Map is keyed by the ids as given. A request that fails as a whole throws, as an
+     * API without this route does (404): read those ids one by one with `get`.
+     */
+    async getMany(ids) {
+        const unique = [...new Set(ids.filter((id) => typeof id === 'string' && id.trim()))];
+        const found = new Map();
+        for (let start = 0; start < unique.length; start += POSTS_BATCH_MAX) {
+            const chunk = unique.slice(start, start + POSTS_BATCH_MAX);
+            const answer = await this.client.get('/posts/batch', { ids: chunk.join(',') });
+            // A uuid's case is not part of it: the server answers each id once, by its first spelling.
+            const entries = new Map((Array.isArray(answer?.data) ? answer.data : [])
+                .filter((entry) => entry && typeof entry.id === 'string')
+                .map((entry) => [entry.id.trim().toLowerCase(), entry]));
+            for (const id of chunk) {
+                const entry = entries.get(id.trim().toLowerCase());
+                if (!entry) {
+                    throw new RecursivError(502, { type: 'api_error', code: 'invalid_response',
+                        message: 'GET /posts/batch did not answer every id it was asked; read them one by one with posts.get' });
+                }
+                found.set(id, entry.data && !entry.error ? { data: entry.data } : { error: postBatchError(entry.error) });
+            }
+        }
+        return found;
+    }
     /** One page of a post's replies, newest first. Start from `replies_next_cursor` on `get`, then follow `meta.next_cursor`. */
     replies(id, params) {
         return this.client.get(`/posts/${encodeURIComponent(id)}/replies`, params ? { limit: params.limit, cursor: params.cursor } : undefined);

package/dist/resources/protocols.d.ts

@@ -1,5 +1,6 @@
 import type { HttpClient } from '../client.js';
 import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse, StoryOutlets } from '../types.js';
+import type { CuratorStoryPostsPage } from './curator.js';
 /** Canonical protocol operation names returned by the adapter registry. */
 export declare const PROTOCOL_CAPABILITY_OPERATIONS: readonly ["discover", "stream", "backfill", "search", "resolveIdentity", "fetchProfile", "fetchThread", "publish", "reply", "react", "repost", "follow", "delete", "health", "checkpoint"];
 export declare const PROTOCOL_CAPABILITY_STATUSES: readonly ["supported", "planned", "unsupported"];
@@ -1509,6 +1510,14 @@ export interface SocialRadarStory {
      * seeded, and `id` is its radar id, the address to link to. A server that cannot resolve edition story ids answers 400.
      */
     editionStory?: string;
+    /**
+     * The posts the World Today story that seeded this story counts across Minds, Bluesky, the Fediverse and Nostr: the
+     * first page of the reader's pool, exactly as `curator.storyPosts` (signed out) or `curator.memberStoryPosts` (signed
+     * in) serves it for `volume.story_key`, whose `cursor` continues there (or walk it with `curator.storyPostPages`).
+     * `volume.discussion` is the count the pages list toward. Absent while the server does not serve World Story Volume
+     * for the app, and for a story no World Today story seeded or whose pool holds no post for this reader.
+     */
+    volume?: CuratorStoryPostsPage;
 }
 /**
  * The Viral read (`getPublicViral`, `getSharedViral`): what is moving fastest on Bluesky, the Fediverse, Nostr and

package/llm.md

@@ -630,6 +630,8 @@ const { data: results } = await r.posts.search({ query: 'shipped', community_id:
 
 Methods: `list`, `get`, `create`, `update`, `delete`, `search`, `replies(id, { limit, cursor })` (after `replies_next_cursor` on `get`), `react`, `unreact`, `liked`, `bookmarked`, `bookmark`, `unbookmark`
 
+Several posts by id (0.7.77): `const found = await r.posts.getMany(ids)` reads up to `POSTS_BATCH_MAX` (25) per request (`GET /posts/batch`) and returns a `Map` keyed by id: `found.get(id)?.data` is the post as `get` serves it to the member (`viewer`, `user_reaction`, `reposted_by_viewer_id`), without its thread (no `replies`; no thread is read, so a story page's six posts come back in about the time of one), and `found.get(id)?.error` is a `NotFoundError` for one that is gone or not for this member. Each id is asked once. The call throws when the request fails as a whole, as on an API without the route (404): read those ids one by one with `get`.
+
 Feed definitions (types only; no route serves one yet): `FeedDefinition` is `{ v: 1, sources, ranking: { mode, range? }, filters?, exclude? }`, with 1-`FEED_SOURCES_MAX` (50) sources read as one union (`FEED_SOURCE_KINDS`; `FEED_SOURCE_KEY[kind]` names each kind's one field, e.g. `{ kind: 'tag', slug: 'rust' }`, `{ kind: 'account', ref: 'did:plc:…' }`). `filters.politics` stores only `'hide'`; viewer settings, blocks, mutes and compass Mix/Sides never go in a definition. Built-in feeds: `builtinCategoryFeedRef('science')` → `'builtin:category:science'`, plus `'builtin:all'` and `'builtin:for_you'`.
 
 `search` ranks relevance x recency x engagement (recency falls as a power of age: this month outranks years ago) through the promotion safety floor; `sort: 'new'` lists newest first; `media: 'video'` (0.7.69) keeps only posts with a video that plays (relevance only), in the page shape Watch reads, so a player can play a query. Page with `meta.next_cursor` as `cursor`: later relevance pages are slices of the ranking the first page kept for ten minutes (nothing skipped or repeated while it lives; after that, the page continues past the last post's score boundary), newest-first pages continue by (created_at, id). A cursor is bound to its search and sort: another search's, or the other sort's, is 400 `invalid_cursor`. The first relevance page carries `latest` (up to three of the newest matches not on the page, one per author, for a Latest strip); the last page carries `fall_over.lanes` (`new`, `open_network`, `tag`): draw a way on, not a wall.
@@ -820,6 +822,7 @@ const { data: quote } = await r.appSubscriptions.previewTierChange({ tier: 'pro'
 await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorationDate })
 ```
 - `r.admin` — Admin operations (user management, stats, network settings); content reports: `listReports({ status? })`, `resolveReport(id)`, `dismissReport(id)` (project-bound keys see only their app's reports)
+- `r.moderation` — Moderation actions. Staff (admin key), 0.7.74: `const { data: actions } = await r.moderation.list({ target_type: 'user', target_id: userId })` reads one target's recorded actions (`ModerationAction`: `id`, `target_type` incl. `source_item`, `action`, `label`, `reason`, `actor_id`, `actor_type`, `source_report_id`, `expires_at`, `reversed_at`, `created_at`), newest first, at most 100, inside the caller's network and a project-bound key's app; `list()` with no target reads the network's latest. Unban = reverse each ban still in force: `for (const a of actions.filter(a => a.action === 'ban' && !a.reversed_at)) await r.moderation.reverse(a.id)`; the target's state is derived again from what is still in force. `reverse` is sent once, never retried: 404 `action_not_found` (`NotFoundError`) means already reversed or not in the caller's scope; 409 `use_judgment_review` means a reviewed label override (change it with `r.judgments.review`). An older SDK has neither method. Also `apply`, `publicLog`, `mine`, `appeal`, `resolveAppeal`, and agent grants `listAgentGrants`, `grantAgent(agentId, 'shadow' | 'act')`, `revokeAgent`.
 - `r.judgments` (0.7.71) — Jev's labels of one post. `get({ kind: 'post' | 'network_post', id })`: switch on `data.view` — `'full'` for the post's author and staff (`judgments` with answers, `safety` verdict, `viral.withheld`; staff also `reviewer_ids`, `review_note`), `'summary'` for other members (`category`, `politics` band in words with its `judgment_id`; never a probability or cell). `data.status === 'unavailable'` (returned, not thrown): hide label actions. `getPublic(projectId, { kind, id })` on an anonymous client: `view: 'category'` only. `dispute(judgmentId, { question_key: 'placement', proposed: 'cm' | … | 'not_political', note? })` (safety: `question_key: 'safety'`, author only): the author's dispute is an appeal; a repeat answers `existing: true`. Staff: `review(judgmentId, { outcome: 'uphold' } | { outcome: 'override', proposed, note?, apply_to_shared? })`, sent once (never retried): a compass override answers 202 `{ status: 'awaiting_reviewer', agreeing, needed }` until a second reviewer (or an agreeing Jev re-judge) proposes the same; a safety override to `'none'` that would free other posts throws 409 `shared_words` (`isJudgmentSharedWordsError(e)`, `e.details.shared_posts`) until resent with `apply_to_shared: true`. Budgets (60 reads/hour, 25 of one author's posts, 20 disputes/day) throw `RateLimitError` with `scope: 'action'` at once. Example: `const { data } = await r.judgments.get({ kind: 'post', id }); if (data.status === 'ok' && data.view === 'summary' && data.politics) await r.judgments.dispute(data.politics.judgment_id, { question_key: 'placement', proposed: 'not_political' })`
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.73",
+  "version": "0.7.77",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",