@recursiv/sdk 0.7.50 → 0.7.52

package/README.md

@@ -74,7 +74,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 ### AI Agents
 | Resource | Key methods |
 |----------|------------|
-| `r.agents` | `create`, `update`, `chat`, `chatStream`, `grantProjectAccess`, `conversations` |
+| `r.agents` | `create`, `update`, `chat`, `chatStream`, `retryChatStream`, `grantProjectAccess`, `conversations` |
 | `r.e2ee` | `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge` (flag-gated E2EE v2 transport) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
@@ -84,34 +84,37 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 ### Identity & Auth
 | Resource | Key methods |
 |----------|------------|
-| `r.auth` | `signUp`, `signIn`, `getSession`, `signOut`, `createApiKey` (session reads/sign-out use explicit Bearer auth with a native/server Cookie fallback) |
+| `r.auth` | `signUp`, `signIn`, `signInWithUsername`, `getSession`, `signOut`, `createApiKey`, `forgetPassword`, `resetPassword`; two-factor: `enableTwoFactor`, `verifyTwoFactor`, `disableTwoFactor`, `regenerateTwoFactorBackupCodes`, `requestTwoFactorEmailCode`, `completeTwoFactorSignIn`; OAuth consent: `exchangeSessionForCookie`, `getOAuthClientInfo` (session calls use explicit Bearer auth with a native/server Cookie fallback) |
 | `@recursiv/sdk/next` | `createRecursivAuth` — cookie-session server auth for Next.js App Router (see below) |
 | `r.users` | `me`, `get` |
 | `r.organizations` | `create`, `members`, `addMember`, `invite` |
-| `r.profiles` | `me`, `get`, `search`, `follow`, `unfollow` |
+| `r.profiles` | `me`, `get`, `search`, `mentions`, `follow`, `unfollow`, `followers`/`following` (rows carry `is_following`, `follows_you`), `followingIds`, `block`, `unblock`, `blocked`, `mute`, `unmute`, `muted` |
 
 ### Social
 | Resource | Key methods |
 |----------|------------|
-| `r.posts` | `create`, `update`, `list`, `liked`, `search`, `react` |
-| `r.communities` | `create`, `join`, `members` |
-| `r.chat` | `send`, `dm`, `createGroup`, `messages` |
+| `r.posts` | `create`, `update`, `list`, `liked`, `search`, `replies`, `react` |
+| `r.communities` | `create`, `join`, `search`, `members` |
+| `r.chat` | `send`, `dm`, `createGroup`, `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation` |
 | `r.tags` | `create`, `list` |
 | `r.uploads` | `uploadMedia` — upload post/chat bytes end to end |
+| `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `getStatus`, `getPlaybackToken` |
 
 ### Platform
 | Resource | Purpose |
 |----------|---------|
-| `r.settings` | User preferences (including app-scoped content choices), sessions, password management |
+| `r.settings` | User preferences (including app-scoped content choices), sessions (`revokeOtherSessions` keeps this device), password management, email change (`requestConfirmationCode` for accounts with no password) |
 | `r.billing` | Usage tracking, subscriptions, checkout |
-| `r.appSubscriptions` | Consumer app plans: `checkout`, `status`, `createPortalSession` |
-| `r.notifications` | Push notification tokens |
+| `r.appSubscriptions` | Consumer app plans: `checkout`, `status`, `createPortalSession`, `previewTierChange`, `changeTier` |
+| `r.boosts` | Promoted posts: `create`, `mine`, `balance`, `pause`, `resume`, `cancel`, `recordEvent`, `topup`, `confirmTopup`; admin `listPendingReview`, `review`, `grant` |
+| `r.wallet` | Wallet, MINDS tokens (`getTokenBalance`, `getTokenLedger`), USD payouts (`getPayouts`, `startPayoutOnboarding`, `payoutLoginLink`) |
+| `r.notifications` | Notification stream (`list`, `unreadCount`, `markAsRead`, `archive`, `markAllAsRead`) and push tokens |
 | `r.github` | GitHub integration |
 | `r.integrations` | External service connections |
 | `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), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `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`; 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), 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/`.
 
@@ -137,6 +140,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
@@ -145,9 +149,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' })
 ```
@@ -472,6 +479,25 @@ participant selection is unfinished. `textTruncated` labels an abbreviated sourc
 preview. Preparation and submission never automatically retry; check the event ID
 after an uncertain result before choosing a retry of the identical signed event.
 
+### A Bluesky account on the app's own PDS
+
+`createHostedIdentity` asks the app's own PDS to issue a Bluesky account for the
+signed-in member. Only the label is sent; the app picks the domain.
+
+```ts
+const { data: identity } = await r.protocols.createHostedIdentity({
+  protocol: 'atproto', handle: 'alice', email: 'alice@example.com',
+})
+// identity.handle is e.g. 'alice.pds.minds.com'. identity.password exists only in
+// this response: show it to the member once and store it nowhere.
+```
+
+The server either finishes the account or removes it again, so a failure never
+leaves one half made. The call is never retried automatically. `handle_unavailable`
+(409) means choose another label; the 503 codes `handle_dns_unavailable`,
+`handle_unresolvable` and `handle_unverified` are operator setup and succeed
+unchanged once it is done.
+
 ### Delegated Bluesky and ActivityPub accounts
 
 These methods require the same signed-in human app key throughout. The API must
@@ -497,6 +523,18 @@ native token is sent through these SDK methods. Start and callback are single-us
 requests and are never automatically retried. If a callback result is uncertain,
 refresh the account list before starting again.
 
+In a native app, use the operator-configured native callback instead of the web
+one when `nativeSocialAccounts()` lists the protocol in `nativeRedirects`:
+
+```ts
+const { data: start } = await r.protocols.startNativeSocialConnection({
+  protocol: 'bluesky', identifier: 'alice.bsky.social', redirect: 'native',
+})
+const result = await WebBrowser.openAuthSessionAsync(start.authorizationUrl, start.callbackUrl)
+// In the native callback route, read state, code, iss (or error) from result.url:
+await r.protocols.finishNativeSocialConnection({ protocol: 'bluesky', state, code, iss })
+```
+
 Connection does not approve publication. The account's `capabilities` lists only
 implemented actions, currently empty for these adapters. Local disconnect takes
 effect even when `providerRevocation` is `unconfirmed`; the user can also revoke
@@ -579,7 +617,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,
@@ -594,6 +635,8 @@ blocks/mutes as well. All reply and account endpoints still require authenticati
 
 Standalone public publication uses `protocols.prepareNativePost({ clientMutationId, text, accountIds, media? })`, then explicitly approved `submitNativePost`. Keep the same mutation ID after uncertain preparation; previously attempted deliveries are reconciled without resending. `nativePostStatus` and paginated `nativePostHistory` expose private app/user-owned outcomes. Review current own posts with `prepareNativePostRemoval`, then approve exact removal IDs through `removeNativePost`. Check connected-account `publish_text` capabilities; only explicitly enabled apps may publish. Text is sent unchanged, public only, with each provider’s actual limits. Optional `media` is a `NativeMediaInput[]` of at most four already-uploaded Minds images (`{ url, alt?, width?, height?, mimeType? }`, JPEG/PNG/WebP/GIF, Minds-hosted HTTPS URLs only, a Mastodon GIF must be the only attachment). It additionally requires the account's `publish_media` capability; accounts connected before image permissions existed must reconnect. Pass the member's own `alt` — an omitted one is sent as an empty description, never an invented one — and read `receipt.media` (`{ count, alt_missing }`) after sending. These methods still do not accept a reply parent or caller-supplied authority.
 
+To delete a post everywhere, link its network copies when you cross-post: pass `crossPostOf: post.id` (the member's own post in this app, from `sdk.posts`) to `prepareNativePost` and to `prepareNativeNostr(id, { action: 'publish', content, crossPostOf })`. Later, `nativePostHistory({ crossPostOf: post.id })` lists exactly that post's copies, each with `crossPostOf` set: delegated items are removed with `prepareNativePostRemoval`/`removeNativePost`, and `type: 'nostr'` items (original notes, which this SDK's history lists; the REST route returns them only with `include=nostr` or `crossPostOf`, so older apps keep the delegated-only shape) with the Nostr signing flow (`prepareNativeNostr(identityId, { action: 'delete', postId: eventId })`). Another member's post, or one from another app, answers `not_found`; copies prepared without `crossPostOf` stay unlinked.
+
 For Bluesky accounts advertising `quote`, prepare the same publication with `quote: { protocol: 'bluesky', nativeId: sourceAtUri }`. The server resolves the exact source CID using each connected account, checks quote permission and Minds safety, and rechecks before writing. Review each delivery’s `quote` alongside the account and comment before submitting. Changed or unavailable sources cannot publish; uncertain deliveries reconcile the original record key. ActivityPub/Nostr quotes are not provided by this method. Public post reads include at most one filtered `quote` with `state: 'available'` and `post`, or `state: 'unavailable'` without source content. Available quotes may include `embeddedReferences`: exact standalone source-reference lines in the unchanged outer `text`. Omit them only when the quoted original is actually visible; retain them for unavailable or locally hidden quotes. Nostr references are decoded and matched by the server, without following relay hints.
 
 Topic browsing can request `getPublicTrends({ protocol: "bluesky", includePreviews: true })`. Optional `SocialTrend.preview` is a real image-bearing post from that topic, never a generated illustration. The server samples at most eight posts for each of ten topics, with three concurrent reads and a shared 2.5-second deadline; missing images leave usable text topics. App moderation and user source controls filter previews on every request. Bluesky CDN image attachments, quote-with-media images, and unlabeled link-preview thumbnails are supported; omitted content retains the source link.
@@ -607,6 +650,20 @@ 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.
 
+`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.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
 a session or learning state across accounts. It starts conservatively and does

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, {

package/dist/index.d.ts

@@ -51,6 +51,7 @@ import { SwarmsResource } from './resources/swarms.js';
 import { TemplatesResource } from './resources/templates.js';
 import { VideoResource } from './resources/video.js';
 import { AppSubscriptionsResource } from './resources/app-subscriptions.js';
+import { BoostsResource } from './resources/boosts.js';
 import { MediaResource } from './resources/media.js';
 import { WebhooksResource } from './resources/webhooks.js';
 import { JobsResource } from './resources/jobs.js';
@@ -119,6 +120,7 @@ export declare class Recursiv {
     readonly discovery: DiscoveryResource;
     readonly video: VideoResource;
     readonly appSubscriptions: AppSubscriptionsResource;
+    readonly boosts: BoostsResource;
     readonly reports: ReportsResource;
     readonly moderation: ModerationResource;
     readonly linkPreview: LinkPreviewResource;
@@ -137,9 +139,11 @@ export declare class Recursiv {
 }
 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, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult } 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';
@@ -155,7 +159,7 @@ export { SandboxResource } from './resources/sandbox.js';
 export { ProfilesResource } from './resources/profiles.js';
 export { OrganizationsResource } from './resources/organizations.js';
 export { NotificationsResource } from './resources/notifications.js';
-export type { Notification, ListNotificationsParams, NotificationListResponse } from './resources/notifications.js';
+export type { Notification, NotificationActor, NotificationCategory, NotificationPostPreview, NotificationScopeParams, NotificationUnreadCount, ListNotificationsParams, NotificationListResponse, } from './resources/notifications.js';
 export { SettingsResource } from './resources/settings.js';
 export { BillingResource } from './resources/billing.js';
 export { FreeTierResource } from './resources/free-tier.js';
@@ -177,10 +181,10 @@ export { WebhooksResource } from './resources/webhooks.js';
 export { JobsResource } from './resources/jobs.js';
 export { CuratorResource } from './resources/curator.js';
 export { VideoResource } from './resources/video.js';
-export type { VideoUploadCreds, CreateVideoUploadResult, VideoStatusInfo, VideoPlaybackToken, } 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, } 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';
@@ -196,9 +200,12 @@ export { OrganizationSecurityResource } from './resources/organization-security.
 export { UploadsResource } from './resources/uploads.js';
 export type { UploadMediaInput, UploadUrlInput, UploadUrlResult } from './resources/uploads.js';
 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, 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, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, 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, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, 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, 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

@@ -52,6 +52,7 @@ import { SwarmsResource } from './resources/swarms.js';
 import { TemplatesResource } from './resources/templates.js';
 import { VideoResource } from './resources/video.js';
 import { AppSubscriptionsResource } from './resources/app-subscriptions.js';
+import { BoostsResource } from './resources/boosts.js';
 import { MediaResource } from './resources/media.js';
 import { WebhooksResource } from './resources/webhooks.js';
 import { JobsResource } from './resources/jobs.js';
@@ -120,6 +121,7 @@ export class Recursiv {
     discovery;
     video;
     appSubscriptions;
+    boosts;
     reports;
     moderation;
     linkPreview;
@@ -179,9 +181,10 @@ 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);
         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);
@@ -246,6 +249,7 @@ export { ProjectSettingsResource } from './resources/project-settings.js';
 export { OrganizationSecurityResource } from './resources/organization-security.js';
 export { UploadsResource } from './resources/uploads.js';
 export { WalletResource } from './resources/wallet.js';
+export { BoostsResource } 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 { InboxResource } from './resources/inbox.js';

package/dist/realtime.d.ts

@@ -53,32 +53,102 @@ export interface RealtimeConnectOptions {
      * Use this when the API key must stay server-side (cookie-auth web apps):
      * expose a same-origin route that mints the token with the server-held key
      * and pass its fetcher here. Default: fetch with this client's own key
-     * (REST `/realtime/ws-token`, tRPC fallback).
+     * (REST `/realtime/ws-token`).
+     *
+     * Throw an error whose `status` is 401 or 403 when the credential itself is
+     * refused; the client then stops reconnecting until `connect()` is called
+     * again. Returning `undefined` (or throwing anything else) counts as a
+     * transient failure and is retried with backoff.
      */
     getToken?: () => Promise<string | undefined>;
+    /** First reconnect delay in ms. Default 2000. */
+    reconnectionDelay?: number;
+    /** Longest reconnect delay in ms. Default 30000. */
+    reconnectionDelayMax?: number;
+    /** Jitter applied to each reconnect delay, as a fraction of it (0 to 1). Default 0.5. */
+    randomizationFactor?: number;
 }
+/**
+ * WebSocket client for chat and presence.
+ *
+ * One socket at a time, and it survives the ways a socket dies:
+ * - a transport drop (network blip, sleep, backgrounding, API restart) is
+ *   retried by socket.io with jittered backoff;
+ * - the server ending the connection because its token expired, or refusing
+ *   a reconnect handshake (spent or expired token, rate limit), is retried
+ *   here with the same backoff, since socket.io does not retry either;
+ * - every attempt authenticates with its own token (the server accepts each
+ *   token once), and a failed token fetch sends none rather than a spent one;
+ * - listeners registered with `on()`/`onMessage()`… and rooms joined with
+ *   `joinConversation()` are re-applied to every connection, including a
+ *   socket rebuilt by a later `connect()`.
+ *
+ * Reconnecting stops only on `disconnect()` or when the token source refuses
+ * the credential (401/403).
+ */
 export declare class RealtimeClient {
     private socket;
     private client;
     private connectionPromise;
     private tokenProvider;
+    private backoff;
+    /** Every subscription, attached to each socket this client builds. */
+    private readonly listeners;
+    /** Conversation rooms to join on every connect. */
+    private readonly rooms;
+    /** connect() callers waiting on a socket that is reconnecting. */
+    private waiters;
+    private recoveryTimer;
+    private recoveryAttempts;
+    private credentialRefused;
+    /** Bumped by disconnect(), so a connect() still in flight does not revive a socket. */
+    private generation;
+    /**
+     * The socket whose first handshake a connect() is awaiting. Closing a socket
+     * that never connected makes socket.io emit nothing, so discardSocket()
+     * settles that connect() through this.
+     */
+    private pendingOpen;
     constructor(client: HttpClient);
     private fetchTokenWithClientKey;
+    /** A token for one reconnect attempt. Never throws: no token means the attempt is refused and retried. */
+    private mintToken;
     /**
      * Connects to the WebSocket server using a temporary WebSocket token.
+     * Resolves with the connected socket.
      *
-     * Reconnect-safe by design:
-     * - the connection promise is cleared after settling, so a later call
-     *   builds a fresh socket instead of returning a dead one;
-     * - `connect_error` only tears down the INITIAL attempt — after the first
-     *   successful connect, socket.io's auto-reconnection owns recovery and
-     *   transient errors never disable it;
-     * - auth uses socket.io's function form, so every (re)connection attempt
-     *   fetches a fresh token via `options.getToken` or the client's key.
+     * Safe to call as often as you like: a connected socket is returned as is,
+     * a socket that is reconnecting is waited on (the promise rejects if that
+     * attempt fails, while the client keeps retrying), and only a socket that
+     * has stopped for good is replaced.
      */
     connect(options?: RealtimeConnectOptions): Promise<Socket>;
+    private applyBackoff;
+    private openSocket;
+    /** Room rejoin, waiter settlement and recovery from the disconnects socket.io leaves alone. */
+    private watchLifecycle;
+    private scheduleRecovery;
+    /** Exponential backoff with jitter, bounded by reconnectionDelayMax. */
+    private recoveryDelay;
+    private waitForConnect;
+    private discardSocket;
+    /**
+     * Close the connection and stop reconnecting. Joined rooms are forgotten;
+     * listeners stay registered and attach to the next connection.
+     */
     disconnect(): void;
     getSocket(): Socket | null;
+    /**
+     * Listen for any server event, including the lifecycle events `connect`
+     * (initial and every reconnect: refetch what you may have missed) and
+     * `disconnect`. The listener stays attached across reconnects and socket
+     * replacement. Returns an unsubscribe function.
+     *
+     * Server events include `notification`, `feed_update`,
+     * `conversation_created`, `chat_message`, `chat_typing` and `agent_thinking`.
+     */
+    on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+    /** Join a conversation room now, and again after every reconnect, until you leave it. */
     joinConversation(conversationId: string): void;
     leaveConversation(conversationId: string): void;
     sendTyping(conversationId: string): void;