@recursiv/sdk 0.7.52 → 0.7.53

package/README.md

@@ -93,7 +93,8 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 ### Social
 | Resource | Key methods |
 |----------|------------|
-| `r.posts` | `create`, `update`, `list`, `liked`, `search`, `replies`, `react` |
+| `r.posts` | `create`, `update`, `list`, `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 |
 | `r.communities` | `create`, `join`, `search`, `members` |
 | `r.chat` | `send`, `dm`, `createGroup`, `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation` |
 | `r.tags` | `create`, `list` |
@@ -114,7 +115,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
 | `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), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })`; 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 has left the radar comes with its archived copy and the live story it continues as), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })`; 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/`.
 
@@ -648,7 +649,12 @@ per signed-in viewer and filter. Pass the app-advertised network catalog, then c
 `next()` as the reader approaches the end. Each page contains safe json-render
 module specs and native or protocol post objects. Preserve their existing source
 authority and interactive controls. `retryFailed()` explicitly retries unavailable
-sources; create a new session to refresh exhausted source windows.
+sources; create a new session to refresh exhausted source windows. A topics network
+(Bluesky) is read one topic page at a time; in a category the catalog's previews are not
+judged to be in it, so a read walks into the topics at once, and walks past a topic the
+provider no longer lists (`trend_unavailable`) or one with nothing in the category, up
+to five topic pages a read, so a page reaches a topic that carries posts. Any other
+failure marks the source failed until `retryFailed()`.
 
 `sdk.discovery.createPersonalFeed({ networks, category?, learning?, recommend? })`
 builds the same kind of session for a member's For you tab: its Minds slot reads
@@ -658,6 +664,17 @@ and says whether the member is personalized yet (`meta.personalized`). With a
 `category` (the member's first), the session also reads open-network posts from it;
 without, it is Minds only. It never carries the radar.
 
+`sdk.discovery.recommendations({ kind, category?, limit?, session?, exclude? })` is
+the app's one recommender for suggestion rails: `kind` is `member`, `group`, `tag`,
+`network_account` or `story`, and `category` is `all` or a browse category id. It
+suggests only active or warm entities that pass the server's gates (no link feeds,
+bursts, mirrored `name@host` feeds, single-poster groups or unsafe names), leaves out
+what the viewer follows, joined, blocked or muted, and says why a list is empty in
+`meta.reason`. Call `sdk.discovery.recordImpressions({ kind, keys, event })` with
+`shown` when suggestions are on screen and `engaged` on a tap, follow or join: three
+showings without a tap rest a suggestion for fourteen days, and engaging clears it.
+Keep one `session` token per app session so a rail does not reshuffle on every render.
+
 `sdk.posts.categories()` answers the app's categories in the order this member
 should see them. `meta.order` is `personal`, `popular` or `static`; `meta.reason`
 says why an answer is not personal (`low_signal`, `deadline`, `requested`,

package/dist/client.d.ts

@@ -36,8 +36,12 @@ export declare class HttpClient {
     post<T>(path: string, body?: unknown, options?: {
         retry?: boolean;
     }): Promise<T>;
-    put<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: {
+        retry?: boolean;
+    }): Promise<T>;
     patch<T>(path: string, body?: unknown): Promise<T>;
-    delete<T>(path: string): Promise<T>;
+    delete<T>(path: string, options?: {
+        retry?: boolean;
+    }): Promise<T>;
     fetchRaw(path: string, options: RequestInit): Promise<Response>;
 }

package/dist/client.js

@@ -188,16 +188,17 @@ export class HttpClient {
         const response = await (options?.retry === false ? this.fetchWithTimeout(url, request) : this.fetchWithRetry(url, request));
         return this.handleResponse(response);
     }
-    async put(path, body) {
+    async put(path, body, options) {
         const url = this.buildUrl(path);
-        const response = await this.fetchWithRetry(url, {
+        const request = {
             method: 'PUT',
             headers: {
                 ...this.getAuthHeaders(),
                 'Content-Type': 'application/json',
             },
             body: body ? JSON.stringify(body) : undefined,
-        });
+        };
+        const response = await (options?.retry === false ? this.fetchWithTimeout(url, request) : this.fetchWithRetry(url, request));
         return this.handleResponse(response);
     }
     async patch(path, body) {
@@ -212,12 +213,10 @@ export class HttpClient {
         });
         return this.handleResponse(response);
     }
-    async delete(path) {
+    async delete(path, options) {
         const url = this.buildUrl(path);
-        const response = await this.fetchWithRetry(url, {
-            method: 'DELETE',
-            headers: this.getAuthHeaders(),
-        });
+        const request = { method: 'DELETE', headers: this.getAuthHeaders() };
+        const response = await (options?.retry === false ? this.fetchWithTimeout(url, request) : this.fetchWithRetry(url, request));
         return this.handleResponse(response);
     }
     async fetchRaw(path, options) {

package/dist/index.d.ts

@@ -59,6 +59,8 @@ import { CuratorResource } from './resources/curator.js';
 import { ReportsResource } from './resources/reports.js';
 import { ModerationResource } from './resources/moderation.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
+import { SearchResource } from './resources/search.js';
+import { BookmarksResource } from './resources/bookmarks.js';
 import { AccountsResource } from './resources/accounts.js';
 import { RealtimeClient } from './realtime.js';
 import type { RecursivConfig } from './types.js';
@@ -124,6 +126,10 @@ export declare class Recursiv {
     readonly reports: ReportsResource;
     readonly moderation: ModerationResource;
     readonly linkPreview: LinkPreviewResource;
+    /** Blended search: posts, open network, people, groups, topics, stories, related and trending in one answer. */
+    readonly search: SearchResource;
+    /** Synced bookmarks: the member's saved posts, open-network posts and articles in this app, across devices. */
+    readonly bookmarks: BookmarksResource;
     readonly accounts: AccountsResource;
     readonly realtime: RealtimeClient;
     constructor(config?: Partial<RecursivConfig>);
@@ -190,6 +196,10 @@ export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, R
 export { ModerationResource } from './resources/moderation.js';
 export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, } 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';
+export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export type { BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, SavedBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';
 export type { LinkPreview, LinkPreviewResponse, } from './resources/link-preview.js';
@@ -205,7 +215,7 @@ export { BoostsResource } from './resources/boosts.js';
 export type { BoostBalance, BoostBalanceResponse, BoostCampaign, BoostCampaignResponse, BoostEventResult, BoostLedgerEntry, BoostLedgerKind, BoostPlanCredit, BoostRejectionReason, BoostReviewStatus, BoostStatus, BoostTopupCheckout, BoostTopupConfirmation, BoostTopupLimits, } from './resources/boosts.js';
 export { ProtocolsResource } from './resources/protocols.js';
 export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, } from './resources/protocols.js';
-export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarPosts, SocialRadarStory, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostHistory, NativeDelegatedPostHistoryItem, NativeNostrPostHistoryItem, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowAccount, NativeFollowStates, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlDisplay, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, CreateHostedIdentityInput, CreatedHostedProtocolIdentity, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
+export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostHistory, NativeDelegatedPostHistoryItem, NativeNostrPostHistoryItem, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowAccount, NativeFollowStates, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlDisplay, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, CreateHostedIdentityInput, CreatedHostedProtocolIdentity, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
 export { InboxResource } from './resources/inbox.js';
 export { NetworkResource } from './resources/network.js';
 export { SimulatorResource } from './resources/simulator.js';

package/dist/index.js

@@ -60,6 +60,8 @@ import { CuratorResource } from './resources/curator.js';
 import { ReportsResource } from './resources/reports.js';
 import { ModerationResource } from './resources/moderation.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
+import { SearchResource } from './resources/search.js';
+import { BookmarksResource } from './resources/bookmarks.js';
 import { AccountsResource } from './resources/accounts.js';
 import { RealtimeClient } from './realtime.js';
 export class Recursiv {
@@ -125,6 +127,10 @@ export class Recursiv {
     reports;
     moderation;
     linkPreview;
+    /** Blended search: posts, open network, people, groups, topics, stories, related and trending in one answer. */
+    search;
+    /** Synced bookmarks: the member's saved posts, open-network posts and articles in this app, across devices. */
+    bookmarks;
     accounts;
     realtime;
     constructor(config) {
@@ -181,13 +187,15 @@ export class Recursiv {
         this.webhooks = new WebhooksResource(client);
         this.jobs = new JobsResource(client);
         this.curator = new CuratorResource(client);
-        this.discovery = new DiscoveryResource(this.posts, this.protocols, this.curator);
+        this.discovery = new DiscoveryResource(this.posts, this.protocols, this.curator, client);
         this.video = new VideoResource(client);
         this.appSubscriptions = new AppSubscriptionsResource(client);
         this.boosts = new BoostsResource(client);
         this.reports = new ReportsResource(client);
         this.moderation = new ModerationResource(client);
         this.linkPreview = new LinkPreviewResource(client);
+        this.search = new SearchResource(client);
+        this.bookmarks = new BookmarksResource(client);
         this.accounts = new AccountsResource(client);
         this.realtime = new RealtimeClient(client);
         this.#http = client;
@@ -243,6 +251,8 @@ export { AppSubscriptionsResource } from './resources/app-subscriptions.js';
 export { ReportsResource } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
+export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
+export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';

package/dist/resources/bookmarks.d.ts

@@ -0,0 +1,172 @@
+import type { HttpClient } from '../client.js';
+import type { PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+/**
+ * What a bookmark is stored under: `post:<post id>`, `social:<sha256>` (the hash the member's source
+ * controls use for that open-network post) or `article:<sha256 of the url>`. Every save, list and keys
+ * call returns it; pass it back to `unsave`.
+ */
+export type BookmarkKey = string;
+export type BookmarkKind = 'post' | 'social' | 'article';
+export type BookmarkProtocol = 'bluesky' | 'activitypub' | 'nostr';
+/** Something to save: a Minds post, an open-network post (with the snapshot to show it by) or an article. */
+export type BookmarkInput = {
+    kind: 'post';
+    post_id: string;
+} | {
+    kind: 'social';
+    protocol: BookmarkProtocol;
+    /** The network's immutable post id: an at:// URI, an ActivityPub object URL, or a Nostr event id. */
+    native_id: string;
+    /** ActivityPub only: the Mastodon-compatible status id that reopens the conversation. Dropped elsewhere. */
+    read_ref?: string;
+    author: {
+        display_name: string;
+        handle: string;
+        /** The author's immutable id (DID, actor URL, pubkey), so the member's blocks and mutes apply. Derived on Bluesky. */
+        native_id?: string;
+    };
+    /** At most 500 characters. */
+    snippet: string;
+} | {
+    kind: 'article';
+    /** An http(s) URL without credentials, at most 2048 characters. */
+    url: string;
+    title: string;
+    outlet: string;
+    /** A World Today story or edition id. */
+    story?: string;
+    /** An https image URL. */
+    image?: string;
+};
+/** A device's saved item for `merge`: an input plus when the device saved it (held to the last five years, never the future). */
+export type BookmarkMergeItem = BookmarkInput & {
+    saved_at?: string;
+};
+export interface SavedBookmark {
+    key: BookmarkKey;
+    kind: BookmarkKind;
+    saved: true;
+    /** False when it was already saved: nothing changed, not even `saved_at`. */
+    created: boolean;
+    saved_at: string | null;
+    /** Posts only: the post stored. A bare repost is saved as its original, so use this id for its saved state. */
+    post_id?: string;
+}
+export interface UnsavedBookmark {
+    key: BookmarkKey;
+    saved: false;
+    /** False when it was not saved; unsaving is idempotent. */
+    removed: boolean;
+}
+/** A saved open-network post or article, as the snapshot taken when it was saved. */
+export type BookmarkItem = {
+    key: BookmarkKey;
+    kind: 'social';
+    saved_at: string;
+    social: {
+        protocol: BookmarkProtocol;
+        native_id: string;
+        read_ref: string | null;
+        author: {
+            display_name: string;
+            handle: string;
+            native_id: string | null;
+        };
+        snippet: string;
+    };
+} | {
+    key: BookmarkKey;
+    kind: 'article';
+    saved_at: string;
+    article: {
+        url: string;
+        title: string;
+        outlet: string;
+        story: string | null;
+        image: string | null;
+    };
+};
+/** One saved key and the identity it stands for, for an app's synchronous saved-state cache. */
+export interface BookmarkKeyRow {
+    key: BookmarkKey;
+    kind: BookmarkKind;
+    saved_at: string;
+    post_id?: string;
+    protocol?: BookmarkProtocol;
+    native_id?: string;
+    url?: string;
+}
+export interface BookmarkMergeResult {
+    saved: number;
+    already: number;
+    skipped: number;
+    over_limit: number;
+    /** What the member has saved in this app now. */
+    total: number;
+    /** The most one member keeps per app. */
+    limit: number;
+    /** One per item, in input order. */
+    results: Array<{
+        key: BookmarkKey | null;
+        status: 'saved' | 'already' | 'skipped' | 'over_limit';
+        reason?: 'invalid' | 'unavailable';
+    }>;
+}
+/** A saved Minds post, hydrated like a feed post, with when the member saved it. */
+export type BookmarkedPost = Post & {
+    bookmarked_at: string | null;
+};
+export interface BookmarksPage<T> extends PaginatedResponse<T> {
+    /** Page on `next_cursor` until it is null: a page can come back short while it skips posts the member can no longer read. */
+    meta: PaginationMeta & {
+        next_cursor: string | null;
+    };
+}
+/** Most items one `merge` call takes. */
+export declare const BOOKMARK_MERGE_MAX_ITEMS = 200;
+/**
+ * `retry: false` answers after one attempt. Use it for the first call that finds out whether synced
+ * bookmarks exist: a 503 `bookmarks_unavailable` is otherwise retried with backoff like any 5xx.
+ */
+export interface BookmarkRequestOptions {
+    retry?: boolean;
+}
+/**
+ * Synced bookmarks: the signed-in member's saved Minds posts, open-network posts and articles in this app,
+ * across every device they sign in on. Private to the member; needs the member's own app key.
+ *
+ * Until the server has synced bookmarks every call rejects with a 503 whose code is `bookmarks_unavailable`:
+ * keep bookmarks on the device then. Keys that are not a member's own app key get 403 `project_binding_required`.
+ */
+export declare class BookmarksResource {
+    private client;
+    constructor(client: HttpClient);
+    /** Save one item. Idempotent: saving what is saved changes nothing. 409 `bookmark_limit` past the member's limit. */
+    save(item: BookmarkInput, options?: BookmarkRequestOptions): Promise<SingleResponse<SavedBookmark>>;
+    /** Unsave by the key a save, list or keys call returned, or by `{ postId }`. Idempotent. */
+    unsave(target: BookmarkKey | {
+        postId: string;
+    }, options?: BookmarkRequestOptions): Promise<SingleResponse<UnsavedBookmark>>;
+    /** Saved Minds posts, newest saved first, hydrated like the feed. Page on `meta.next_cursor`. */
+    posts(params?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkedPost>>;
+    /** Saved open-network posts and articles, newest saved first. Page on `meta.next_cursor`. */
+    list(params?: {
+        kind?: 'social' | 'article';
+        limit?: number;
+        cursor?: string;
+    }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkItem>>;
+    /** Every saved key (hidden posts included), newest saved first, up to 500 a page. For a saved-state cache. */
+    keys(params?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkKeyRow>>;
+    /**
+     * Upload a device's saves, e.g. when its member signs in: at most 200 items a call. Idempotent (a second
+     * merge of the same items is a no-op); invalid items and posts the member cannot read are `skipped`, and
+     * items past the member's limit come back `over_limit` (the newest are kept).
+     */
+    merge(items: BookmarkMergeItem[], options?: BookmarkRequestOptions): Promise<SingleResponse<BookmarkMergeResult>>;
+}

package/dist/resources/bookmarks.js

@@ -0,0 +1,44 @@
+/** Most items one `merge` call takes. */
+export const BOOKMARK_MERGE_MAX_ITEMS = 200;
+/**
+ * Synced bookmarks: the signed-in member's saved Minds posts, open-network posts and articles in this app,
+ * across every device they sign in on. Private to the member; needs the member's own app key.
+ *
+ * Until the server has synced bookmarks every call rejects with a 503 whose code is `bookmarks_unavailable`:
+ * keep bookmarks on the device then. Keys that are not a member's own app key get 403 `project_binding_required`.
+ */
+export class BookmarksResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Save one item. Idempotent: saving what is saved changes nothing. 409 `bookmark_limit` past the member's limit. */
+    save(item, options) {
+        return this.client.put('/bookmarks', item, options);
+    }
+    /** Unsave by the key a save, list or keys call returned, or by `{ postId }`. Idempotent. */
+    unsave(target, options) {
+        const key = typeof target === 'string' ? target : `post:${target.postId}`;
+        return this.client.delete(`/bookmarks/${encodeURIComponent(key)}`, options);
+    }
+    /** Saved Minds posts, newest saved first, hydrated like the feed. Page on `meta.next_cursor`. */
+    posts(params, options) {
+        return this.client.get('/posts', { bookmarked: true, ...params }, options);
+    }
+    /** Saved open-network posts and articles, newest saved first. Page on `meta.next_cursor`. */
+    list(params, options) {
+        return this.client.get('/bookmarks', params, options);
+    }
+    /** Every saved key (hidden posts included), newest saved first, up to 500 a page. For a saved-state cache. */
+    keys(params, options) {
+        return this.client.get('/bookmarks/keys', params, options);
+    }
+    /**
+     * Upload a device's saves, e.g. when its member signs in: at most 200 items a call. Idempotent (a second
+     * merge of the same items is a no-op); invalid items and posts the member cannot read are `skipped`, and
+     * items past the member's limit come back `over_limit` (the newest are kept).
+     */
+    merge(items, options) {
+        return this.client.post('/bookmarks/merge', { items }, options);
+    }
+}

package/dist/resources/communities.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { Community, CommunityBannedMember, CommunityCard, CommunityDetail, CommunityMember, CommunityPeopleParams, CreateCommunityInput, CreatedCommunity, JoinResult, LeaveResult, ListCommunitiesParams, PaginatedResponse, PaginationParams, RelatedCommunity, SingleResponse } from '../types.js';
+import type { AnswerJoinRequestsInput, ApprovedJoinRequests, Community, CommunityBannedMember, CommunityCard, CommunityDetail, CommunityMember, CommunityPeopleParams, CreateCommunityInput, CreatedCommunity, DeclinedJoinRequests, JoinResult, LeaveResult, ListCommunitiesParams, PaginatedResponse, PaginationParams, RelatedCommunity, SingleResponse } from '../types.js';
 export declare class CommunitiesResource {
     private client;
     constructor(client: HttpClient);
@@ -52,6 +52,16 @@ export declare class CommunitiesResource {
     declineMember(id: string, userId: string): Promise<SingleResponse<{
         declined: boolean;
     }>>;
+    /**
+     * Let many pending members in at once. Admin or higher. Pass `{ user_ids }`
+     * (at most 100) or `{ all: true }` for the oldest 100 waiting; call again
+     * while `remaining` is above 0. Named people with no pending request (already
+     * in, already answered, banned, never asked) come back in `skipped`. A ban is
+     * never answered.
+     */
+    approveMembers(id: string, input: AnswerJoinRequestsInput): Promise<SingleResponse<ApprovedJoinRequests>>;
+    /** Turn many pending members away at once, as `approveMembers` lets them in. Admin or higher. */
+    declineMembers(id: string, input: AnswerJoinRequestsInput): Promise<SingleResponse<DeclinedJoinRequests>>;
     /** Remove a member. Moderator or higher, and only members below your role. */
     removeMember(id: string, userId: string): Promise<SingleResponse<{
         removed: boolean;

package/dist/resources/communities.js

@@ -70,6 +70,20 @@ export class CommunitiesResource {
     declineMember(id, userId) {
         return this.client.post(`/communities/${id}/members/${userId}/decline`);
     }
+    /**
+     * Let many pending members in at once. Admin or higher. Pass `{ user_ids }`
+     * (at most 100) or `{ all: true }` for the oldest 100 waiting; call again
+     * while `remaining` is above 0. Named people with no pending request (already
+     * in, already answered, banned, never asked) come back in `skipped`. A ban is
+     * never answered.
+     */
+    approveMembers(id, input) {
+        return this.client.post(`/communities/${encodeURIComponent(id)}/requests/approve`, input);
+    }
+    /** Turn many pending members away at once, as `approveMembers` lets them in. Admin or higher. */
+    declineMembers(id, input) {
+        return this.client.post(`/communities/${encodeURIComponent(id)}/requests/decline`, input);
+    }
     /** Remove a member. Moderator or higher, and only members below your role. */
     removeMember(id, userId) {
         return this.client.delete(`/communities/${id}/members/${userId}`);

package/dist/resources/discovery.d.ts

@@ -1,9 +1,71 @@
+import type { HttpClient } from '../client.js';
 import type { DiscoveryLayout, Post } from '../types.js';
 import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
 export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
+/** What GET /discover/recommendations suggests: members, groups, tags, open-network accounts or World Today stories. */
+export type EntityKind = 'member' | 'group' | 'tag' | 'network_account' | 'story';
+/**
+ * One suggestion. `key` is the entity's id (a uuid), or `<protocol>:<native id>` for an open-network account.
+ * The public display fields depend on the kind: members carry id, username, name, image, bio and
+ * follower_count; groups id, name, slug, image, description and member_count; tags id, name and slug;
+ * open-network accounts protocol, actor, handle, display_name and avatar_url (never a link out); stories id,
+ * headline, kicker, story_kind and edition_date.
+ */
+export interface EntityRecommendation {
+    kind: EntityKind;
+    key: string;
+    /** active: posted in the last 7 days or 4+ times in 30 (for groups, 3+ distinct posters in 30 days); warm: activity in 90 days. */
+    tier: 'active' | 'warm';
+    score: number;
+    /** The entity's share of the requested category, or null for category=all. */
+    share: number | null;
+    last_active_at: string | null;
+    posts_30d: number;
+    /** Distinct posters in 30 days (groups and tags), otherwise null. */
+    authors_30d: number | null;
+    /** Up to three browse categories, largest share first. */
+    categories: Array<{
+        category: string;
+        share: number;
+    }>;
+    [display: string]: unknown;
+}
+export interface EntityRecommendationsParams {
+    kind: EntityKind;
+    /** 'all' (default) or a browse category id. */
+    category?: string;
+    /** 1..50, default 10. */
+    limit?: number;
+    /** A per-session token ([A-Za-z0-9_-], up to 64): the same token keeps the order stable; a new one rotates near-ties. */
+    session?: string;
+    /** Up to 50 keys of the kind to leave out, e.g. open-network accounts the member follows through a connected account. */
+    exclude?: string[];
+}
+export interface EntityRecommendationsResponse {
+    data: EntityRecommendation[];
+    meta: {
+        kind: EntityKind;
+        category: string;
+        as_of: string | null;
+        /** Why the list is empty: serving is off, the key's app is not the one signals are built for, no snapshot yet, the viewer's follows could not be checked, or the key has no app. */
+        reason?: 'disabled' | 'other_app' | 'no_snapshot' | 'viewer_facts_unavailable' | 'no_app';
+        /** Suggestions left out because they are resting for this viewer, and because the viewer follows, joined, blocked or muted them. */
+        resting: number;
+        excluded: number;
+        /** True when the member's own category order lifted suggestions in their first categories. */
+        personalized: boolean;
+    };
+}
+export interface EntityImpressionsInput {
+    kind: EntityKind;
+    /** 1..50 keys of the kind. */
+    keys: string[];
+    /** 'shown' when a suggestion was on screen; 'engaged' on a tap, follow or join. Three showings without a tap rest a suggestion for fourteen days; engaging clears it. */
+    event: 'shown' | 'engaged';
+}
 export interface DiscoveryGroupCandidate {
     id: string;
     name: string;
@@ -162,7 +224,7 @@ export interface DiscoveryFeedPage {
 export declare const GALLERY_MAX_ITEMS = 12;
 /** Per-viewer feed session. Create a new session when user, app, category or
  * source changes. All reads retain existing server authorization/moderation.
- * At most four requests per page; providers fail independently. */
+ * At most four sources per page (a topics network's read walks up to TOPIC_WALK topic pages); providers fail independently. */
 export declare class DiscoveryFeedSession {
     private posts;
     private protocols;
@@ -187,6 +249,15 @@ export declare class DiscoveryFeedSession {
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
+    /**
+     * One read of a topics network: the next topic page that carries posts. A topic the provider no
+     * longer lists (Bluesky rotates its trends between the catalog read and the walk through it) is
+     * that topic's end, not the network's failure; a topic page with nothing in the category is
+     * walked past too, and its continuation kept, so the page reaches a topic that carries posts
+     * instead of spending a round on each empty one. Bounded by TOPIC_WALK reads and TOPIC_WALK_MS;
+     * a walk that stops short has moved the stream on, and the next read continues from there.
+     */
+    private walkTopics;
     private readPage;
     /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
     private radarCluster;
@@ -203,7 +274,24 @@ export declare class DiscoveryResource {
     private posts;
     private protocols;
     private curator?;
-    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined);
+    private http?;
+    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined, http?: Pick<HttpClient, "get" | "post"> | undefined);
+    /**
+     * Suggestions for the signed-in viewer from the app's one recommender: active or warm members, groups
+     * with several posters, tags used by several people, open-network accounts or stories, overall or in one
+     * browse category. What the viewer follows, joined, blocked or muted is left out, and so is anything
+     * resting for them. Call `recordImpressions` when suggestions are actually on screen and when one is tapped.
+     */
+    recommendations(params: EntityRecommendationsParams, options?: {
+        retry?: boolean;
+    }): Promise<EntityRecommendationsResponse>;
+    /** Records that suggestions were shown (at most once per half hour counts) or engaged with. */
+    recordImpressions(input: EntityImpressionsInput): Promise<{
+        data: {
+            recorded: number;
+            reason?: 'disabled' | 'other_app' | 'unavailable' | 'no_app';
+        };
+    }>;
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
      * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts