@recursiv/sdk 0.7.51 → 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/`.
 
@@ -140,6 +141,7 @@ deployment, throw the normal SDK errors; do not present them as an empty queue.
 ```typescript
 const r = new Recursiv({
   apiKey: 'sk_live_...',                   // or set RECURSIV_API_KEY env var
+  inheritEnvironmentApiKey: true,          // default; false guarantees keyless operation
   baseUrl: 'https://api.recursiv.io/api/v1',  // default
   timeout: 30000,                          // request timeout in ms
   maxRetries: 2,                           // auto-retry on 429/5xx
@@ -148,9 +150,12 @@ const r = new Recursiv({
 // Zero-arg works when RECURSIV_API_KEY is set
 const r = new Recursiv()
 
-// Anonymous sandbox (no API key needed)
+// Anonymous sandbox (no API key required; inherits RECURSIV_API_KEY when set)
 const r = new Recursiv({ anonymous: true })
 
+// Guaranteed keyless public client, even inside a credentialed server process
+const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false })
+
 // Self-hosted
 const r = new Recursiv({ baseUrl: 'https://my-instance.com/api/v1' })
 ```
@@ -613,7 +618,10 @@ state and obtain a fresh review before a new write.
 Visitors can read a public conversation in an explicitly configured app without signing in:
 
 ```ts
-const visitor = new Recursiv({ anonymous: true });
+const visitor = new Recursiv({
+  anonymous: true,
+  inheritEnvironmentApiKey: false,
+});
 const { data: networks } = await visitor.protocols.sharedNetworks(projectId);
 const { data: conversation } = await visitor.protocols.getSharedConversation(projectId, {
   protocol: 'nostr', post: publicEventId,
@@ -641,7 +649,37 @@ 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
+`sdk.curator.forYou({ surface: 'discover', discovery: true, cursor })`, which ranks
+fresher and past the member's follows, pages a stored ranking by `meta.next_cursor`,
+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`,
+`experiment_off`), and `meta.order_id` changes only when the order does. The order
+is private to the member; show it as returned rather than sorting it again.
 
 Optional `DiscoveryLearning` consumes real visible impressions and explicit
 engagement/hide outcomes. Persist its count-only snapshot per viewer; never share

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

@@ -11,7 +11,9 @@ export class HttpClient {
     clientName;
     constructor(config) {
         const apiKey = config?.apiKey ||
-            (typeof process !== 'undefined' ? process.env?.RECURSIV_API_KEY : undefined);
+            (config?.inheritEnvironmentApiKey !== false && typeof process !== 'undefined'
+                ? process.env?.RECURSIV_API_KEY
+                : undefined);
         this.anonymous = config?.anonymous ?? false;
         if (!apiKey && !this.anonymous && !config?.allowNoKey) {
             throw new RecursivError(0, {
@@ -186,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) {
@@ -210,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>);
@@ -143,6 +149,7 @@ 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 { PostsResource } from './resources/posts.js';
+export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';
@@ -182,13 +189,17 @@ export { CuratorResource } from './resources/curator.js';
 export { VideoResource } from './resources/video.js';
 export type { VideoUploadCreds, CreateVideoUploadResult, VideoStatusInfo, VideoPlaybackToken, VideoEntitlement, } from './resources/video.js';
 export { AppSubscriptionsResource } from './resources/app-subscriptions.js';
-export type { AppSubscriptionCheckoutResult, AppSubscriptionPortalResult, AppSubscriptionStatusResult, AppSubscriptionTierChangePreview, AppSubscriptionTierChangeResult, } from './resources/app-subscriptions.js';
-export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, } from './resources/curator.js';
+export type { AppSubscriptionBoostCredit, AppSubscriptionCheckoutResult, AppSubscriptionPortalResult, AppSubscriptionStatusResult, AppSubscriptionTierChangePreview, AppSubscriptionTierChangeResult, } from './resources/app-subscriptions.js';
+export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
 export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
 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';
@@ -201,10 +212,10 @@ export type { UploadMediaInput, UploadUrlInput, UploadUrlResult } from './resour
 export { WalletResource } from './resources/wallet.js';
 export type { LinkedTokenWallet, PayoutState, TokenBalance, TokenLedgerEntry } from './resources/wallet.js';
 export { BoostsResource } from './resources/boosts.js';
-export type { BoostBalance, BoostBalanceResponse, BoostCampaign, BoostCampaignResponse, BoostEventResult, BoostLedgerEntry, BoostLedgerKind, BoostRejectionReason, BoostReviewStatus, BoostStatus, BoostTopupCheckout, BoostTopupConfirmation, BoostTopupLimits, } 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.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/admin.d.ts

@@ -158,12 +158,25 @@ export interface InviteSystemStats {
         used: number;
         expired: number;
         revoked: number;
+        /** @deprecated Use `total`. */
+        total_codes: number;
+        /** @deprecated Use `active`. */
+        active_codes: number;
+        /** @deprecated Use `used`. */
+        used_codes: number;
+        /** @deprecated Use `expired`. */
+        expired_codes: number;
+        /** @deprecated Use `revoked`. */
+        revoked_codes: number;
     };
     waitlist: Record<string, number>;
     current_wave: {
         id: string;
         wave: number;
         name: string;
+        max_codes: number;
+        invites_per_user: number;
+        reward_tokens: number;
         is_active: boolean;
     } | null;
 }

package/dist/resources/agents.d.ts

@@ -65,7 +65,7 @@ export interface SalesLead {
  * Validation happens server-side too; this list lets apps validate or
  * surface choices client-side without round-tripping the API.
  */
-export declare const SUPPORTED_MODELS: readonly ["anthropic/claude-fable-5", "anthropic/claude-opus-4.6", "anthropic/claude-opus-4.8", "anthropic/claude-sonnet-4.6", "anthropic/claude-sonnet-5", "deepseek/deepseek-v3.2", "deepseek/deepseek-v4-pro", "google/gemini-3-flash-preview", "google/gemini-3.1-pro-preview", "google/gemini-3.5-flash", "minimax/minimax-m2.5", "minimax/minimax-m3", "moonshotai/kimi-k3", "openai/gpt-4o-mini", "openai/gpt-5.5", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "x-ai/grok-4.3"];
+export declare const SUPPORTED_MODELS: readonly ["anthropic/claude-fable-5", "anthropic/claude-fable-5.1", "anthropic/claude-opus-4.6", "anthropic/claude-opus-4.8", "anthropic/claude-opus-5", "anthropic/claude-opus-5.5", "anthropic/claude-sonnet-4.6", "anthropic/claude-sonnet-5", "deepseek/deepseek-v3.2", "deepseek/deepseek-v4-pro", "google/gemini-3-flash-preview", "google/gemini-3.1-pro-preview", "google/gemini-3.5-flash", "google/gemini-3.8-flash", "minimax/minimax-m2.5", "minimax/minimax-m3", "moonshotai/kimi-k3", "openai/gpt-4o-mini", "openai/gpt-5.5", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "openai/gpt-6-astra", "openai/gpt-6-sol", "x-ai/grok-4.3"];
 export type SupportedModel = (typeof SUPPORTED_MODELS)[number];
 export interface EnsurePersonalAgentOverrides {
     /** Override the agent's display name. Defaults to 'Agent'. */
@@ -74,6 +74,17 @@ export interface EnsurePersonalAgentOverrides {
     model?: string;
     /** Override the system prompt. Apps like Minds can set their own voice. */
     system_prompt?: string;
+    /**
+     * Whether the agent may post publicly (reply to @mentions). The platform
+     * default for a new personal agent is 'chat_post'; pass 'chat_only' to keep
+     * it to private chat.
+     */
+    social_mode?: 'chat_only' | 'chat_post';
+    /**
+     * How the agent uses tools. The platform default for a new personal agent is
+     * 'autonomous'; 'permission' asks the owner before a tool acts.
+     */
+    tool_mode?: 'chat_only' | 'permission' | 'autonomous';
 }
 export interface EnsurePersonalAgentInput {
     /**
@@ -105,7 +116,7 @@ export declare class AgentsResource {
     }): Promise<PaginatedResponse<Agent>>;
     /** Get an agent by ID */
     get(id: string): Promise<SingleResponse<AgentDetail>>;
-    /** Create a new AI agent */
+    /** Create a new AI agent. Omit username for a server-generated collision-resistant handle. */
     create(input: CreateAgentInput): Promise<SingleResponse<CreatedAgent>>;
     /** Update an agent's configuration */
     update(id: string, input: UpdateAgentInput): Promise<SingleResponse<UpdatedAgent>>;

package/dist/resources/agents.js

@@ -12,8 +12,11 @@ import { parseSSE } from '../lib/sse.js';
 export const SUPPORTED_MODELS = [
     // <<< GENERATED: openrouter-sync — do not edit by hand (npm run models:sync)
     'anthropic/claude-fable-5',
+    'anthropic/claude-fable-5.1',
     'anthropic/claude-opus-4.6',
     'anthropic/claude-opus-4.8',
+    'anthropic/claude-opus-5',
+    'anthropic/claude-opus-5.5',
     'anthropic/claude-sonnet-4.6',
     'anthropic/claude-sonnet-5',
     'deepseek/deepseek-v3.2',
@@ -21,6 +24,7 @@ export const SUPPORTED_MODELS = [
     'google/gemini-3-flash-preview',
     'google/gemini-3.1-pro-preview',
     'google/gemini-3.5-flash',
+    'google/gemini-3.8-flash',
     'minimax/minimax-m2.5',
     'minimax/minimax-m3',
     'moonshotai/kimi-k3',
@@ -28,6 +32,8 @@ export const SUPPORTED_MODELS = [
     'openai/gpt-5.5',
     'openai/gpt-5.6-sol',
     'openai/gpt-5.6-terra',
+    'openai/gpt-6-astra',
+    'openai/gpt-6-sol',
     'x-ai/grok-4.3',
     // >>> GENERATED
 ];
@@ -51,7 +57,7 @@ export class AgentsResource {
     get(id) {
         return this.client.get(`/agents/${id}`);
     }
-    /** Create a new AI agent */
+    /** Create a new AI agent. Omit username for a server-generated collision-resistant handle. */
     create(input) {
         return this.client.post('/agents', input);
     }

package/dist/resources/app-subscriptions.d.ts

@@ -6,6 +6,30 @@ export interface AppSubscriptionCheckoutResult {
 export interface AppSubscriptionPortalResult {
     /** Stripe Billing Portal URL for the current app user. */
     url: string;
+    /**
+     * The page the portal opens on: `cancel` for the plan's cancel confirmation, null for the
+     * portal home. A plan already set to end opens the home, where the member can renew it.
+     * Absent from older servers.
+     */
+    flow?: 'cancel' | null;
+}
+/** The boost credit a paid plan on this app adds to the member's boost balance. */
+export interface AppSubscriptionBoostCredit {
+    /** Micro-USD (1 USD = 1,000,000) each paid billing period of a plan adds, by tier key (e.g. `plus`, `pro`). */
+    perPeriodMicros: Record<string, number>;
+    /** What the member's current plan adds each paid period; 0 without a paid plan here. */
+    currentMicros: number;
+    /**
+     * When the next paid period starts and adds `currentMicros`. Null without a plan that adds
+     * credit, or while a payment is overdue. A plan set to end at the period's end still shows it.
+     */
+    nextGrantAt: string | null;
+    /**
+     * Plan credit the member owes: taken back after their plan dropped or ended inside a period, but
+     * already spent. The next plan credit repays it before adding anything. 0 when nothing is owed
+     * (absent from older servers).
+     */
+    owedMicros?: number;
 }
 export interface AppSubscriptionStatusResult {
     tier: string;
@@ -15,6 +39,11 @@ export interface AppSubscriptionStatusResult {
     currentPeriodEnd: string | null;
     /** Where the entitlement comes from: a Stripe subscription here, or the legacy import. */
     source?: 'stripe' | 'legacy';
+    /**
+     * The boost credit each paid period of a plan adds (once per period, from the payment that
+     * starts it). Null when this app's plans include none; absent from older servers.
+     */
+    boostCredit?: AppSubscriptionBoostCredit | null;
 }
 export interface AppSubscriptionTierChangePreview {
     /** The plan the preview prices. */
@@ -47,6 +76,13 @@ export declare class AppSubscriptionsResource {
      * Start a Stripe Checkout for the current user to subscribe to a plan tier ('plus' | 'pro').
      * Answers 409 `subscription_exists` when the member already has a subscription:
      * use `changeTier` for them instead, so they are never billed twice.
+     *
+     * Only one checkout can be paid at a time. Repeating the same request (same tier and
+     * `return_url`) returns the checkout already open; any other request expires the
+     * member's earlier open checkouts for this app. Answers 503 `checkout_busy` when
+     * Stripe is too slow to finish safely: retry. `return_url` keeps its own query and fragment;
+     * `sub=success&tier=<tier>` or `sub=cancelled` is added to its query (to the
+     * fragment's query for a hash route such as `#/billing`).
      */
     checkout(input: {
         tier: string;
@@ -79,13 +115,23 @@ export declare class AppSubscriptionsResource {
     }): Promise<{
         data: AppSubscriptionTierChangeResult;
     }>;
-    /** Open the current app user's Stripe Billing Portal for this project. */
+    /**
+     * Open the current app user's Stripe Billing Portal for this project.
+     *
+     * `flow: 'cancel'` opens it straight on the cancel confirmation for the member's plan, and
+     * returns to `return_url` once they confirm. Answers 409 `no_subscription` when there is no
+     * plan to cancel, and 409 `legacy_membership` for a carried-over member with nothing to manage.
+     */
     createPortalSession(input: {
         return_url: string;
+        flow?: 'cancel';
     }): Promise<{
         data: AppSubscriptionPortalResult;
     }>;
-    /** Read the current user's app-subscription status for this project-scoped key. */
+    /**
+     * Read the current user's app-subscription status for this project-scoped key, with the
+     * boost credit the app's plans include (`boostCredit`).
+     */
     status(): Promise<{
         data: AppSubscriptionStatusResult;
     }>;

package/dist/resources/app-subscriptions.js

@@ -11,6 +11,13 @@ export class AppSubscriptionsResource {
      * Start a Stripe Checkout for the current user to subscribe to a plan tier ('plus' | 'pro').
      * Answers 409 `subscription_exists` when the member already has a subscription:
      * use `changeTier` for them instead, so they are never billed twice.
+     *
+     * Only one checkout can be paid at a time. Repeating the same request (same tier and
+     * `return_url`) returns the checkout already open; any other request expires the
+     * member's earlier open checkouts for this app. Answers 503 `checkout_busy` when
+     * Stripe is too slow to finish safely: retry. `return_url` keeps its own query and fragment;
+     * `sub=success&tier=<tier>` or `sub=cancelled` is added to its query (to the
+     * fragment's query for a hash route such as `#/billing`).
      */
     checkout(input) {
         return this.client.post('/app-subscriptions/checkout', input);
@@ -35,11 +42,20 @@ export class AppSubscriptionsResource {
     changeTier(input) {
         return this.client.post('/app-subscriptions/change-tier', input, { retry: false });
     }
-    /** Open the current app user's Stripe Billing Portal for this project. */
+    /**
+     * Open the current app user's Stripe Billing Portal for this project.
+     *
+     * `flow: 'cancel'` opens it straight on the cancel confirmation for the member's plan, and
+     * returns to `return_url` once they confirm. Answers 409 `no_subscription` when there is no
+     * plan to cancel, and 409 `legacy_membership` for a carried-over member with nothing to manage.
+     */
     createPortalSession(input) {
         return this.client.post('/app-subscriptions/portal', input);
     }
-    /** Read the current user's app-subscription status for this project-scoped key. */
+    /**
+     * Read the current user's app-subscription status for this project-scoped key, with the
+     * boost credit the app's plans include (`boostCredit`).
+     */
     status() {
         return this.client.get('/app-subscriptions/status');
     }