@recursiv/sdk 0.7.52 → 0.7.54

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,46 @@ 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.
+
+A category feed never ends at an empty page. `sdk.posts.list({ category, sort: 'hot' })`
+(or `score`, or the default chronological order) pages the window of the category's
+newest judged posts, then continues by keyset through the whole indexed
+history: every page's `meta.next` is `{ offset }`, `{ cursor }` or `null`, and when a
+stage ends `meta.fallover` lists where to go, in order: `category_older` (the keyset
+cursor `next` also carries), `category_network` (the same category on the open
+networks), the member's next categories (`via` names the order they came from), `for_you`
+and `all`. A `DiscoveryFeedSession` follows the cursor itself and reports the Minds
+feed's `fallover` on its pages. `sdk.discovery.category({ category, session? })` answers a
+category's surface in one call: `stories`, `network` and `clips` (each shared per app and
+category, refreshed after 30 s, kept up to 300 s and warmed as the warmer reaches the category, then filtered for the viewer on every call: the cached safety verdicts of story members, network posts and clips again, the term list, the viewer's blocks and mutes over clips, and the member's own hidden sources over network posts and story members) and the
+viewer's `people` and `groups`; a section that timed out, failed or is off is empty with a
+`reason` for that request only (a failure is never cached, so asking again retries it), and one this
+key may not read is empty with `refused` (`stories` and `network` need the member's own app
+key with `users:read`; `people` and `groups` need `users:read`). In a category, a Bluesky
+topic the provider no longer lists, or whose feed holds nothing in the category, is served
+the network's indexed posts in it (`sourceIndex.reason` of `gone` or `empty`). While the
+provider has more of the topic the page's cursor is the provider's own, so the topic's
+deeper pages are still read; once it has none, or the topic is gone, the cursor is an
+`idx:tf:` one that continues in the index. When the index cannot answer (busy, or its safety
+cache unreadable), the page is what the provider answered: the empty page with its own
+cursor, or the gone topic's 404; only an `idx:tf:` page answers 503 `unavailable`, and that
+ends the index continuation, not the network. The app contract: a `trend_unavailable` 404,
+an empty topic page or a failed `idx:tf:` page never disables a network for the session;
+move to the next topic, keep every provider continuation, start the `idx:tf:` stream once
+per network and session (every such topic answers the same index stream; after a failed
+page it may start again), and pass cursors back unchanged. `DiscoveryFeedSession` does
+this for you.
+
 `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>);
@@ -141,7 +147,7 @@ export { HttpClient } from './client.js';
 export { RealtimeClient } from './realtime.js';
 export type { RealtimeConnectOptions } from './realtime.js';
 export { AuthResource } from './resources/auth.js';
-export type { AuthSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, } from './resources/auth.js';
+export type { AuthSession, CurrentSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, } from './resources/auth.js';
 export { PostsResource } from './resources/posts.js';
 export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
@@ -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/auth.d.ts

@@ -8,6 +8,20 @@ export interface AuthSession {
         image: string | null;
     };
 }
+/**
+ * What `getSession` answers: the account, and which of its sessions the token
+ * is. `session.id` is the id `settings.listSessions()` lists that session
+ * under. A client that authenticates with an API key gets `is_current: false`
+ * on every listed row (a key belongs to no session), so it matches this id to
+ * mark its own device.
+ */
+export interface CurrentSession extends AuthSession {
+    /** Null only when the server's answer names no session row. */
+    session: {
+        id: string;
+        expiresAt: string | null;
+    } | null;
+}
 export interface SignUpInput {
     email: string;
     password: string;
@@ -275,10 +289,10 @@ export declare class AuthResource {
         success: true;
     }>;
     /**
-     * Get current session info using a session token.
-     * Returns null if the session is invalid or expired.
+     * Get current session info using a session token: the account, and the
+     * session's id and expiry. Returns null if the session is invalid or expired.
      */
-    getSession(sessionToken: string): Promise<AuthSession | null>;
+    getSession(sessionToken: string): Promise<CurrentSession | null>;
     /**
      * Sign out (invalidate session).
      */

package/dist/resources/auth.js

@@ -596,8 +596,8 @@ export class AuthResource {
         return { success: true };
     }
     /**
-     * Get current session info using a session token.
-     * Returns null if the session is invalid or expired.
+     * Get current session info using a session token: the account, and the
+     * session's id and expiry. Returns null if the session is invalid or expired.
      */
     async getSession(sessionToken) {
         const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/get-session`, {
@@ -612,6 +612,8 @@ export class AuthResource {
         const data = await res.json();
         if (!data?.user)
             return null;
+        const sessionId = data.session?.id;
+        const expiresAt = data.session?.expiresAt;
         return {
             token: sessionToken,
             user: {
@@ -620,6 +622,9 @@ export class AuthResource {
                 email: data.user.email,
                 image: data.user.image ?? null,
             },
+            session: typeof sessionId === 'string' && sessionId
+                ? { id: sessionId, expiresAt: typeof expiresAt === 'string' ? expiresAt : null }
+                : null,
         };
     }
     /**

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/curator.d.ts

@@ -7,7 +7,7 @@ export type ForYouParams = {
     offset?: number;
     /** The previous page's `meta.next_cursor`: pages a stored ranking, so posts read meanwhile never shift the next page. */
     cursor?: string;
-    /** Adds `meta.discovery` (layouts) and the public safety floor; limit <= 25. */
+    /** Adds `meta.discovery` (layouts); limit <= 25. Every page carries the promotion safety floor, with or without it. */
     discovery?: boolean;
     /** `discover` ranks for Discover: fresher, beyond the member's follows, with their category order. */
     surface?: ForYouSurface;