@recursiv/sdk 0.7.82 → 0.7.89

package/dist/assistant-surfaces.js

@@ -0,0 +1,113 @@
+/**
+ * Server-driven kill switches for the assistant's surfaces (George plan step G7a).
+ *
+ * A flag compiled into a phone app cannot be switched off once that build ships, so every place an app shows the
+ * assistant asks the server first. The switches are the app's project setting `assistant.surfaces`, and they arrive
+ * inside responses the app already fetches: `users.me()` (the boot read) and `network.getConfig()` both carry
+ * `data.assistant.surfaces`. An app's owner or admin changes them with
+ * `projectBrain.updateSettings(projectId, { assistant: { surfaces: { post_button: true } } })`.
+ *
+ * Fail closed: show a surface only when {@link assistantSurfaceOn} says so, which is only for an explicit `true`. A
+ * response from an older server (no `assistant`), a read that failed, a malformed value and an id this SDK does not
+ * know are all off.
+ *
+ * The server keeps the same list (packages/server/src/features/assistant/surfaces.ts); a contract test holds them equal.
+ */
+/**
+ * Every assistant surface an app may show, one switch each. All default off. Step numbers are the George plan's §8.
+ * New ids are appended; an id is never renamed.
+ */
+export const ASSISTANT_SURFACE_IDS = [
+    // The G glyph on a post (feed, post page, network or bridged post, clip, article, story), with its long-press item
+    // and screen-reader action. G3.
+    'post_button',
+    // The answer sheet: the answer streamed in place (bottom sheet on phones, right rail on desktop), its chips and
+    // follow-ups. G11 (G3's interim sheet rides it too).
+    'answer_sheet',
+    // "Ask about these results" on a question-shaped search, and the Cmd-K ask. G4; answers G23a.
+    'search_row',
+    // The glyph in the top bar that opens the assistant tab. G4.
+    'top_bar',
+    // The assistant's one row in the Chat inbox. G4.
+    'inbox_row',
+    // Mentioning the assistant in a reply (the `ai:george` chip), raw `@askgeorge` routing, and the push that an answer
+    // is ready. G22.
+    'mentions',
+    // Asking about picked messages in an ordinary (not encrypted) DM or group chat, and mentioning the assistant in a
+    // small closed group chat. G20.
+    'chats',
+    // Asking the Sealed assistant about one message in an encrypted chat, on the phone only. G21.
+    'e2ee_asks',
+    // "Catch me up" in a group's (community's) header. G24.
+    'groups_catch_up',
+    // "Translate" under a post in another language. G23a (on-device G25).
+    'translate',
+    // The compose chip: check tone, shorten, fix spelling, translate, draft a reply. G23a.
+    'compose',
+    // "About this account": the facts card on a profile, with no model call. G23a.
+    'profile_facts',
+    // "Why am I seeing this" on a feed post, and asking the assistant to explain it. G28.
+    'why_seeing',
+    // The opt-in daily brief and routines. G30.
+    'daily_brief',
+    // Context notes the assistant drafts and people rate. G31.
+    'notes',
+    // The assistant tab itself: thread list, new chat, the chat screen. G13.
+    'george_tab',
+    // Sealed chats inside the assistant tab, on the phone. G15b.
+    'sealed_in_tab',
+    // "Summarise replies" on a thread with 10 or more replies. G11.
+    'thread_summary',
+    // Ask and Quote on selected text (web selection popover G11; phone apps G32).
+    'selection',
+    // "What's going on" on a topic bar or Today story. G23a.
+    'topic_catch_up',
+    // "Describe" on a picture in the media viewer. G23b, only after the upload checks are live.
+    'describe_image',
+    // "Suggest alt text" for your own picture in compose. G23b, only after the upload checks are live.
+    'alt_text',
+    // "Tell the assistant what you want more or less of" in feed settings. G29.
+    'feed_steering',
+    // Sharing an answer as your own post. G27, not before 2026-11-04.
+    'share_answer',
+];
+const SURFACE_IDS = new Set(ASSISTANT_SURFACE_IDS);
+/** True for a surface id this SDK knows. */
+export function isAssistantSurfaceId(value) {
+    return typeof value === 'string' && SURFACE_IDS.has(value);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The surfaces map inside `settings`, which may be a response's `data` (carrying `assistant.surfaces`) or its
+ * `assistant` block (carrying `surfaces`). Null when there is none to read.
+ */
+function surfacesIn(settings) {
+    if (!isPlainObject(settings))
+        return null;
+    if (Object.hasOwn(settings, 'assistant')) {
+        const assistant = settings.assistant;
+        return isPlainObject(assistant) && isPlainObject(assistant.surfaces) ? assistant.surfaces : null;
+    }
+    return isPlainObject(settings.surfaces) ? settings.surfaces : null;
+}
+/**
+ * Whether the app may show surface `id`: true only when `settings` holds an explicit `true` for it. `settings` is a
+ * response's `data` (`(await sdk.users.me()).data`, `(await sdk.network.getConfig()).data`) or its `assistant` block.
+ * Anything else is off: no settings (a read that failed, an older server), a malformed value, a non-boolean, an id
+ * this SDK does not know.
+ */
+export function assistantSurfaceOn(settings, id) {
+    if (!isAssistantSurfaceId(id))
+        return false;
+    const surfaces = surfacesIn(settings);
+    return !!surfaces && Object.hasOwn(surfaces, id) && surfaces[id] === true;
+}
+/** Every known surface with its switch, read from `settings` by the same rule as {@link assistantSurfaceOn}. */
+export function assistantSurfaces(settings) {
+    const out = {};
+    for (const id of ASSISTANT_SURFACE_IDS)
+        out[id] = assistantSurfaceOn(settings, id);
+    return out;
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './resources/discovery-learning.js';
 import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
 export * from './feed-definition.js';
+export * from './social-protocol-ids.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
@@ -67,6 +68,7 @@ import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { SignalsResource } from './resources/signals.js';
 import { SealedResource } from './resources/sealed.js';
+import { PrivacyResource } from './resources/privacy.js';
 import { RealtimeClient } from './realtime.js';
 import type { RecursivConfig } from './types.js';
 export declare class Recursiv {
@@ -144,6 +146,8 @@ export declare class Recursiv {
     readonly signals: SignalsResource;
     /** Sealed mode's config and transport: targets, models, allowance, the attestation relay and the sealed send (no crypto; flag-gated). */
     readonly sealed: SealedResource;
+    /** Which platform privacy facts the deployed API's build enforces (pair with `@recursiv/sdk/privacy`). */
+    readonly privacy: PrivacyResource;
     readonly realtime: RealtimeClient;
     constructor(config?: Partial<RecursivConfig>);
     /**
@@ -168,7 +172,7 @@ export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource, CHAT_ATTACHMENT_REF_PREFIX, chatAttachmentKeysIn, chatAttachmentRefsIn } from './resources/chat.js';
 export type { ChatAttachmentRef, ChatAttachmentUploadInput, ChatAttachmentUploadUrl, ChatAttachmentUploadUrlInput, SignedChatAttachment, } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
-export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
+export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eePeerChange, E2eePeerErrorCode, E2eePeerNotJoinedDetails, E2eePeerRealtimeEvent, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS, AGENT_DIRECTORY_SORTS, AGENT_DIRECTORY_MAX_LIMIT } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';
@@ -218,15 +222,15 @@ export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export type { PublicSearchPage, PublicSearchTab, SearchAnswer, SearchGroup, SearchLadder, SearchOmitReason, SearchParams, SearchPerson, SearchPost, SearchRelated, SearchResponse, SearchSection, SearchStage, SearchStory, SearchTopic, SearchVia, } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, BookmarksResource } from './resources/bookmarks.js';
 export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
-export type { FeedStoriesParams, FeedStoriesResponse, FeedStory, FeedTopExplain, FeedTopItem, FeedTopMeta, FeedTopNetwork, FeedTopNetworkCard, FeedTopNetworkEntry, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';
+export type { FeedStoriesParams, FeedStoriesResponse, FeedStory, FeedTopExplain, FeedTopItem, FeedTopMeta, FeedTopNetwork, FeedTopNetworkCard, FeedTopNetworkEntry, FeedTopNetworkMap, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';
 export type { BookmarkCollection, BookmarkCollectionInput, BookmarkCollectionKind, BookmarkCollectionPatch, BookmarkCollectionsList, BookmarkCollectionTarget, BookmarkCollectionVisibility, BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKeysPage, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, FiledBookmark, RemovedBookmarkCollection, SavedBookmark, UnfiledBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
 export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
 export type { SignalBatchResult, SignalEventInput, SignalEventType, SignalNotRecordedReason, SignalRecordResult, SignalSendOptions, } from './resources/signals.js';
 export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
-export type { SealedAllowance, SealedAttestationInput, SealedConfig, SealedModel, SealedSendInput, SealedTarget, SealedTargetKind, SealedTransportErrorCode, } from './resources/sealed.js';
+export type { SealedAllowance, SealedAttestationInput, SealedConfig, SealedModel, SealedPlan, SealedPurpose, SealedQuotaDetails, SealedSendInput, SealedTarget, SealedTargetKind, SealedTransportErrorCode, } from './resources/sealed.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';
-export type { LinkPreview, LinkPreviewResponse, } from './resources/link-preview.js';
+export type { LinkPreview, LinkPreviewResponse, LinkPreviewSource, } from './resources/link-preview.js';
 export type { AgentCapabilityConsentRequirement, AgentCapabilityDataSensitivity, AgentCapabilityDomain, AgentCapabilityExportBoundary, AgentCapabilityRetentionClass, AgentCapabilitySubdomain, AgentCapabilitySubject, AgentCapabilityTrustTier, AgentToolAudience, AgentToolScope, BrowserUseRunTaskInput, ProjectBrainSettings, ProjectToolBundleClassification, ProjectToolBundleKey, ProjectToolPermission, ProjectToolPermissionOverrides, UpdateProjectSettingsInput, } from './resources/project-brain.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';
@@ -238,8 +242,8 @@ export type { LinkedTokenWallet, PayoutState, TokenBalance, TokenLedgerEntry } f
 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, viralItemHasVideo, } from './resources/protocols.js';
-export type { SocialProfile, SocialBridge, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, ViralBaseline, ViralItem, ViralItemFields, ViralItemSpread, ViralItemVelocity, ViralLabel, ViralMindsCard, ViralMindsItem, ViralNetwork, ViralOpenProtocol, ViralProtocol, ViralProvider, ViralReadMeta, ViralReadParams, ViralReadResponse, ViralReadStatus, ViralRef, ViralSocialItem, 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, NativePostQuote, 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, ProtocolIngestionActivityReason, ProtocolIngestionCircuitHealth, ProtocolIngestionDeadLetterGroup, ProtocolIngestionHealthPosition, ProtocolIngestionHealthReport, ProtocolIngestionHealthRuntime, ProtocolIngestionHealthSection, ProtocolIngestionLaneActivity, ProtocolIngestionLaneCurrentJob, ProtocolIngestionLaneDeadLetters, ProtocolIngestionLaneHealth, ProtocolIngestionLaneJobs, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
+export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, SOCIAL_FOLLOWING_SOURCE_STATUSES, viralItemHasVideo, } from './resources/protocols.js';
+export type { SocialProfile, SocialBridge, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarSourceKind, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, ViralBaseline, ViralItem, ViralItemFields, ViralItemSpread, ViralItemVelocity, ViralLabel, ViralMindsCard, ViralMindsItem, ViralNetwork, ViralOpenProtocol, ViralProtocol, ViralProvider, ViralReadMeta, ViralReadParams, ViralReadResponse, ViralReadStatus, ViralRef, ViralSocialItem, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SocialFollowingSourceStatus, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeNetwork, NativeNetworkState, NativeNetworkPresence, NativeNetworkActivation, NativeNetworkOff, SetNativeNetworkInput, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostQuote, 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, ProtocolIngestionActivityReason, ProtocolIngestionCircuitHealth, ProtocolIngestionDeadLetterGroup, ProtocolIngestionHealthPosition, ProtocolIngestionHealthReport, ProtocolIngestionHealthRuntime, ProtocolIngestionHealthSection, ProtocolIngestionLaneActivity, ProtocolIngestionLaneCurrentJob, ProtocolIngestionLaneDeadLetters, ProtocolIngestionLaneHealth, ProtocolIngestionLaneJobs, 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';
@@ -270,3 +274,8 @@ export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';
 export type * from './types.js';
 export type { PrepareHostedServiceInput, HostedServiceScope, HostedServiceOperation, HostedServiceReservation, HostedServiceObservation } from './resources/deployments.js';
+export { ASSISTANT_SURFACE_IDS, assistantSurfaceOn, assistantSurfaces, isAssistantSurfaceId, } from './assistant-surfaces.js';
+export type { AssistantSettings, AssistantSettingsUpdate, AssistantSurfaceId, AssistantSurfaces, } from './assistant-surfaces.js';
+export type { CurrentUser } from './resources/users.js';
+export { PrivacyResource } from './resources/privacy.js';
+export type { LiveFactOptions, PrivacyCapabilities } from './privacy/index.js';

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './resources/discovery-learning.js';
 import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
 export * from './feed-definition.js';
+export * from './social-protocol-ids.js';
 import { HttpClient } from './client.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
@@ -68,6 +69,7 @@ import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { SignalsResource } from './resources/signals.js';
 import { SealedResource } from './resources/sealed.js';
+import { PrivacyResource } from './resources/privacy.js';
 import { RealtimeClient } from './realtime.js';
 export class Recursiv {
     /** Shared transport, kept so the client name can be set after construction. */
@@ -145,6 +147,8 @@ export class Recursiv {
     signals;
     /** Sealed mode's config and transport: targets, models, allowance, the attestation relay and the sealed send (no crypto; flag-gated). */
     sealed;
+    /** Which platform privacy facts the deployed API's build enforces (pair with `@recursiv/sdk/privacy`). */
+    privacy;
     realtime;
     constructor(config) {
         const client = new HttpClient(config);
@@ -214,6 +218,7 @@ export class Recursiv {
         this.accounts = new AccountsResource(client);
         this.signals = new SignalsResource(client);
         this.sealed = new SealedResource(client);
+        this.privacy = new PrivacyResource(client);
         this.realtime = new RealtimeClient(client);
         this.#http = client;
     }
@@ -283,7 +288,7 @@ 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, viralItemHasVideo, } from './resources/protocols.js';
+export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, SOCIAL_FOLLOWING_SOURCE_STATUSES, viralItemHasVideo, } from './resources/protocols.js';
 export { InboxResource } from './resources/inbox.js';
 export { NetworkResource } from './resources/network.js';
 export { SimulatorResource } from './resources/simulator.js';
@@ -302,3 +307,5 @@ export { MediaResource } from './resources/media.js';
 export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, EmailNotSentError, } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';
+export { ASSISTANT_SURFACE_IDS, assistantSurfaceOn, assistantSurfaces, isAssistantSurfaceId, } from './assistant-surfaces.js';
+export { PrivacyResource } from './resources/privacy.js';

package/dist/privacy/facts.generated.d.ts

@@ -0,0 +1,79 @@
+export declare const PRIVACY_REGISTRY_VERSION: 0;
+export declare const PRIVACY_FACTS: readonly [{
+    readonly id: "agents.tool_mode.chat_only";
+    readonly status: "planned";
+    readonly enforcement: "server";
+    readonly capability: "web_tools";
+    readonly step: "S5";
+    readonly says: "An agent in chat_only tool mode is given no tools, so it opens no web page.";
+}, {
+    readonly id: "agents.turn_stamp";
+    readonly status: "enforced";
+    readonly enforcement: "server";
+    readonly capability: null;
+    readonly step: "S7";
+    readonly says: "Every reply a model writes in an agent chat through the platform's agent turn records, in metadata.ai, the model, its maker and the route, a model swapped in and whether for usage limits or after a failure, and the tools it called.";
+}, {
+    readonly id: "agents.personal_context_sections";
+    readonly status: "planned";
+    readonly enforcement: "server";
+    readonly capability: "activity";
+    readonly step: "S26";
+    readonly says: "A personal agent's turn carries no follows, upvotes, groups or views of the member unless the member turned that part of their activity on.";
+}, {
+    readonly id: "sealed.attest_before_send";
+    readonly status: "enforced";
+    readonly enforcement: "device";
+    readonly capability: "chat_tier";
+    readonly step: "S28";
+    readonly says: "The phone seals a Sealed request only to the key of a router it checked against a fresh challenge of its own: the router's report, signed by its AMD hardware, must answer that challenge with debug mode off and firmware at or above a floor, and its software must be a release Tinfoil signed and listed in a public log. If any check fails there is no key to seal to, so nothing is sealed or sent. How long a checked router is used before it is checked again is up to the app.";
+}, {
+    readonly id: "sealed.attest_second_signer";
+    readonly status: "planned";
+    readonly enforcement: "device";
+    readonly capability: "chat_tier";
+    readonly step: "S28";
+    readonly says: "The phone also requires Recursiv's own signature over the router's release, so a release Tinfoil signed alone is refused.";
+}, {
+    readonly id: "sealed.no_standard_fallback";
+    readonly status: "enforced";
+    readonly enforcement: "client";
+    readonly capability: "chat_tier";
+    readonly step: "S28";
+    readonly says: "The SDK sends a Sealed request only to the Sealed route, marked Sealed, and only once: a refusal, an error or an answer that is not sealed goes back to the app, and the SDK never sends the request again, to Sealed or to any other route.";
+}, {
+    readonly id: "sealed.gateway_opaque";
+    readonly status: "enforced";
+    readonly enforcement: "server";
+    readonly capability: "chat_tier";
+    readonly step: "S28";
+    readonly says: "The Sealed gateway passes each Sealed request and answer on as bytes it does not read: it never parses, stores or logs a request or answer body. It refuses a request that carries no EHBP encapsulated key, the mark of a sealed body, and a success answer that carries no well-formed EHBP response nonce, the mark of a sealed answer; it cannot tell from the bytes themselves whether a body is sealed.";
+}, {
+    readonly id: "sealed.dest_tinfoil_only";
+    readonly status: "enforced";
+    readonly enforcement: "server";
+    readonly capability: "chat_tier";
+    readonly step: "S28";
+    readonly says: "The Sealed gateway sends Sealed requests, and asks for attestation documents, only to the router origins its configuration lists, named exactly, and it lists only https origins of Tinfoil router hosts (inference.tinfoil.sh or router-N.tinfoil.sh). It refuses any other server a client names and follows no redirect.";
+}, {
+    readonly id: "sealed.no_server_history";
+    readonly status: "enforced";
+    readonly enforcement: "server";
+    readonly capability: "sealed_history";
+    readonly step: "S29";
+    readonly says: "The platform keeps no Sealed chat history: no Sealed route writes a conversation or message row, and the gateway stores no request or answer body.";
+}, {
+    readonly id: "sealed.backup_excluded";
+    readonly status: "planned";
+    readonly enforcement: "device";
+    readonly capability: "sealed_history";
+    readonly step: "S29";
+    readonly says: "Sealed chats saved on a phone are left out of the phone's backups.";
+}, {
+    readonly id: "sealed.no_push";
+    readonly status: "enforced";
+    readonly enforcement: "server";
+    readonly capability: "chat_tier";
+    readonly step: "S29";
+    readonly says: "No Sealed route sends a push notification or writes a notification: a Sealed answer goes back only on the request that asked for it.";
+}];

package/dist/privacy/facts.generated.js

@@ -0,0 +1,93 @@
+// Generated by scripts/privacy-claims.mjs from docs/privacy-claims.json. Do not edit: CI refuses a hand edit.
+// Change the registry, then run: node scripts/privacy-claims.mjs --write
+export const PRIVACY_REGISTRY_VERSION = 0;
+export const PRIVACY_FACTS = [
+    {
+        id: "agents.tool_mode.chat_only",
+        status: "planned",
+        enforcement: "server",
+        capability: "web_tools",
+        step: "S5",
+        says: "An agent in chat_only tool mode is given no tools, so it opens no web page.",
+    },
+    {
+        id: "agents.turn_stamp",
+        status: "enforced",
+        enforcement: "server",
+        capability: null,
+        step: "S7",
+        says: "Every reply a model writes in an agent chat through the platform's agent turn records, in metadata.ai, the model, its maker and the route, a model swapped in and whether for usage limits or after a failure, and the tools it called.",
+    },
+    {
+        id: "agents.personal_context_sections",
+        status: "planned",
+        enforcement: "server",
+        capability: "activity",
+        step: "S26",
+        says: "A personal agent's turn carries no follows, upvotes, groups or views of the member unless the member turned that part of their activity on.",
+    },
+    {
+        id: "sealed.attest_before_send",
+        status: "enforced",
+        enforcement: "device",
+        capability: "chat_tier",
+        step: "S28",
+        says: "The phone seals a Sealed request only to the key of a router it checked against a fresh challenge of its own: the router's report, signed by its AMD hardware, must answer that challenge with debug mode off and firmware at or above a floor, and its software must be a release Tinfoil signed and listed in a public log. If any check fails there is no key to seal to, so nothing is sealed or sent. How long a checked router is used before it is checked again is up to the app.",
+    },
+    {
+        id: "sealed.attest_second_signer",
+        status: "planned",
+        enforcement: "device",
+        capability: "chat_tier",
+        step: "S28",
+        says: "The phone also requires Recursiv's own signature over the router's release, so a release Tinfoil signed alone is refused.",
+    },
+    {
+        id: "sealed.no_standard_fallback",
+        status: "enforced",
+        enforcement: "client",
+        capability: "chat_tier",
+        step: "S28",
+        says: "The SDK sends a Sealed request only to the Sealed route, marked Sealed, and only once: a refusal, an error or an answer that is not sealed goes back to the app, and the SDK never sends the request again, to Sealed or to any other route.",
+    },
+    {
+        id: "sealed.gateway_opaque",
+        status: "enforced",
+        enforcement: "server",
+        capability: "chat_tier",
+        step: "S28",
+        says: "The Sealed gateway passes each Sealed request and answer on as bytes it does not read: it never parses, stores or logs a request or answer body. It refuses a request that carries no EHBP encapsulated key, the mark of a sealed body, and a success answer that carries no well-formed EHBP response nonce, the mark of a sealed answer; it cannot tell from the bytes themselves whether a body is sealed.",
+    },
+    {
+        id: "sealed.dest_tinfoil_only",
+        status: "enforced",
+        enforcement: "server",
+        capability: "chat_tier",
+        step: "S28",
+        says: "The Sealed gateway sends Sealed requests, and asks for attestation documents, only to the router origins its configuration lists, named exactly, and it lists only https origins of Tinfoil router hosts (inference.tinfoil.sh or router-N.tinfoil.sh). It refuses any other server a client names and follows no redirect.",
+    },
+    {
+        id: "sealed.no_server_history",
+        status: "enforced",
+        enforcement: "server",
+        capability: "sealed_history",
+        step: "S29",
+        says: "The platform keeps no Sealed chat history: no Sealed route writes a conversation or message row, and the gateway stores no request or answer body.",
+    },
+    {
+        id: "sealed.backup_excluded",
+        status: "planned",
+        enforcement: "device",
+        capability: "sealed_history",
+        step: "S29",
+        says: "Sealed chats saved on a phone are left out of the phone's backups.",
+    },
+    {
+        id: "sealed.no_push",
+        status: "enforced",
+        enforcement: "server",
+        capability: "chat_tier",
+        step: "S29",
+        says: "No Sealed route sends a push notification or writes a notification: a Sealed answer goes back only on the request that asked for it.",
+    },
+];

package/dist/privacy/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `@recursiv/sdk/privacy`: the platform privacy facts, generated from the claims registry (docs/privacy-claims.json
+ * in recursivlabs/recursiv). Each fact says one thing the platform does with member data and whether this SDK release
+ * marks it enforced, which it does only once every test that proves it is real and runs in CI.
+ *
+ * An app shows a privacy sentence only when the facts it rests on are live: enforced here AND listed by the API it
+ * talks to (`sdk.privacy.capabilities()`), so neither a newer SDK nor a newer API can make a claim on its own. A fact
+ * held on the phone (`enforcement: 'device'`) needs a third check, the app's own: neither this SDK nor the API can see
+ * which native module the phone runs, so the app names the device facts its installed module carries (`deviceFacts`).
+ *
+ * The types live here, not in the SDK's shared types, so this entry point stands alone.
+ */
+import { PRIVACY_FACTS, PRIVACY_REGISTRY_VERSION } from './facts.generated.js';
+export { PRIVACY_FACTS, PRIVACY_REGISTRY_VERSION };
+export type PrivacyFact = (typeof PRIVACY_FACTS)[number];
+export type PrivacyFactId = PrivacyFact['id'];
+/** `planned`: the platform does not yet prove it. `enforced`: every test that proves it is real and runs in CI. */
+export type PrivacyFactStatus = 'planned' | 'enforced';
+/** Where a fact holds: on the server, on the phone (the native module), in the SDK, or in both server and client. */
+export type PrivacyFactEnforcement = 'server' | 'device' | 'client' | 'server_and_client';
+/** GET /privacy/capabilities: the facts the deployed API's build marks enforced, and the commit it runs. */
+export interface PrivacyCapabilities {
+    /** The commit the API was built from, or `unknown`. */
+    api_commit: string;
+    /** Fact ids, sorted. An id this SDK release does not know is never live here. */
+    facts: string[];
+}
+/** The fact with this id, or undefined for an id this SDK release does not know. */
+export declare function privacyFact(id: string): PrivacyFact | undefined;
+/** Whether this SDK release marks the fact enforced. An unknown id is not. */
+export declare function isFactEnforced(id: string): boolean;
+export interface LiveFactOptions {
+    /**
+     * The device facts (`enforcement: 'device'`) the app's installed native module carries, as the app knows from the
+     * module revision it ships (for Sealed, @recursiv/e2ee-react-native). A device fact is live only when it is named
+     * here too. Left out, no device fact is live. A fact says what the module does, not what the app does with it: for
+     * `sealed.attest_before_send` the app chooses how long a checked router is reused, so copy that says the router is
+     * checked before every send needs the app to check before every send.
+     */
+    deviceFacts?: Iterable<string>;
+}
+/**
+ * Enforced in this SDK release AND listed by the deployed API, and for a device fact also named in `deviceFacts`.
+ * Missing capabilities mean nothing is live.
+ */
+export declare function isFactLive(id: string, capabilities: PrivacyCapabilities | null | undefined, options?: LiveFactOptions): boolean;
+/** Every fact that is live for this API (and, for device facts, this app's native module), in registry order. */
+export declare function liveFacts(capabilities: PrivacyCapabilities | null | undefined, options?: LiveFactOptions): PrivacyFactId[];

package/dist/privacy/index.js

@@ -0,0 +1,42 @@
+/**
+ * `@recursiv/sdk/privacy`: the platform privacy facts, generated from the claims registry (docs/privacy-claims.json
+ * in recursivlabs/recursiv). Each fact says one thing the platform does with member data and whether this SDK release
+ * marks it enforced, which it does only once every test that proves it is real and runs in CI.
+ *
+ * An app shows a privacy sentence only when the facts it rests on are live: enforced here AND listed by the API it
+ * talks to (`sdk.privacy.capabilities()`), so neither a newer SDK nor a newer API can make a claim on its own. A fact
+ * held on the phone (`enforcement: 'device'`) needs a third check, the app's own: neither this SDK nor the API can see
+ * which native module the phone runs, so the app names the device facts its installed module carries (`deviceFacts`).
+ *
+ * The types live here, not in the SDK's shared types, so this entry point stands alone.
+ */
+import { PRIVACY_FACTS, PRIVACY_REGISTRY_VERSION } from './facts.generated.js';
+export { PRIVACY_FACTS, PRIVACY_REGISTRY_VERSION };
+const BY_ID = new Map(PRIVACY_FACTS.map((fact) => [fact.id, fact]));
+/** The fact with this id, or undefined for an id this SDK release does not know. */
+export function privacyFact(id) {
+    return BY_ID.get(id);
+}
+/** Whether this SDK release marks the fact enforced. An unknown id is not. */
+export function isFactEnforced(id) {
+    return BY_ID.get(id)?.status === 'enforced';
+}
+/**
+ * Enforced in this SDK release AND listed by the deployed API, and for a device fact also named in `deviceFacts`.
+ * Missing capabilities mean nothing is live.
+ */
+export function isFactLive(id, capabilities, options = {}) {
+    const fact = BY_ID.get(id);
+    if (!fact || fact.status !== 'enforced')
+        return false;
+    if (!Array.isArray(capabilities?.facts) || !capabilities.facts.includes(id))
+        return false;
+    if (fact.enforcement === 'device')
+        return new Set(options.deviceFacts ?? []).has(id);
+    return true;
+}
+/** Every fact that is live for this API (and, for device facts, this app's native module), in registry order. */
+export function liveFacts(capabilities, options = {}) {
+    const deviceFacts = [...(options.deviceFacts ?? [])];
+    return PRIVACY_FACTS.filter((fact) => isFactLive(fact.id, capabilities, { deviceFacts })).map((fact) => fact.id);
+}

package/dist/realtime.d.ts

@@ -1,6 +1,6 @@
 import type { Socket } from 'socket.io-client';
 import { HttpClient } from './client.js';
-import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
+import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eePeerRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
 import type { ChatConversationEvent, ChatMembersEvent } from './types.js';
 export interface ChatMessageEvent {
     id: string;
@@ -150,8 +150,8 @@ export declare class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
-     * `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link`,
+     * `e2ee:devices` and `e2ee:peer`.
      */
     on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
     /** Join a conversation room now, and again after every reconnect, until you leave it. */
@@ -199,4 +199,11 @@ export declare class RealtimeClient {
      * `{ deviceId, reason: 'revoked' }`.
      */
     onE2eeDevices(callback: (event: E2eeDevicesRealtimeEvent) => void): () => void;
+    /**
+     * Someone this account shares an encrypted conversation with reset encrypted
+     * chat: `{ userId, reason: 'root_changed', conversationId }`, once per shared
+     * conversation. Look at their devices again (`r.e2ee.devices({ user_id })`);
+     * catch up with `r.e2ee.peerChanges()` after time in the background.
+     */
+    onE2eePeer(callback: (event: E2eePeerRealtimeEvent) => void): () => void;
 }

package/dist/realtime.js

@@ -369,8 +369,8 @@ export class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
-     * `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link`,
+     * `e2ee:devices` and `e2ee:peer`.
      */
     on(event, listener) {
         // Every call is its own subscription, even for a function that is already
@@ -473,4 +473,13 @@ export class RealtimeClient {
     onE2eeDevices(callback) {
         return this.on('e2ee:devices', callback);
     }
+    /**
+     * Someone this account shares an encrypted conversation with reset encrypted
+     * chat: `{ userId, reason: 'root_changed', conversationId }`, once per shared
+     * conversation. Look at their devices again (`r.e2ee.devices({ user_id })`);
+     * catch up with `r.e2ee.peerChanges()` after time in the background.
+     */
+    onE2eePeer(callback) {
+        return this.on('e2ee:peer', callback);
+    }
 }

package/dist/resources/agents.d.ts

@@ -234,7 +234,10 @@ export declare class AgentsResource {
     }>;
     /** Delete an agent */
     delete(id: string): Promise<DeleteResponse>;
-    /** Send a message to an agent (async — agent responds asynchronously) */
+    /**
+     * Send a message to an agent (async — agent responds asynchronously).
+     * `turn: { safe: true }` makes it a safe turn in the caller's Asks thread (see `AgentChatTurn`).
+     */
     chat(id: string, input: AgentChatInput): Promise<SingleResponse<AgentChatResult>>;
     /** List an agent's conversations */
     conversations(id: string, params?: PaginationParams): Promise<PaginatedResponse<AgentConversation>>;
@@ -398,6 +401,8 @@ export declare class AgentsResource {
      *
      * Requires `ReadableStream` support (Node.js, modern browsers).
      * For React Native, use `chatStreamText()` instead.
+     * `turn: { safe: true }` streams a safe turn in the caller's Asks thread (see `AgentChatTurn`); a refusal throws a
+     * `RecursivError` whose code is a `SafeTurnRefusalCode`, before anything streams.
      */
     chatStream(id: string, input: AgentChatInput): AsyncGenerator<StreamChunk>;
     /**

package/dist/resources/agents.js

@@ -1,4 +1,4 @@
-import { RecursivError } from '../errors.js';
+import { RateLimitError, rateLimitDetailsFromResponse, RecursivError } from '../errors.js';
 import { parseSSE } from '../lib/sse.js';
 // ── Agent directory (GET /agents/discover) ──
 /** The orders the agent directory serves (server: features/agents/agentDirectory.ts). */
@@ -83,7 +83,10 @@ export class AgentsResource {
     delete(id) {
         return this.client.delete(`/agents/${id}`);
     }
-    /** Send a message to an agent (async — agent responds asynchronously) */
+    /**
+     * Send a message to an agent (async — agent responds asynchronously).
+     * `turn: { safe: true }` makes it a safe turn in the caller's Asks thread (see `AgentChatTurn`).
+     */
     chat(id, input) {
         return this.client.post(`/agents/${id}/chat`, input);
     }
@@ -224,6 +227,8 @@ export class AgentsResource {
      *
      * Requires `ReadableStream` support (Node.js, modern browsers).
      * For React Native, use `chatStreamText()` instead.
+     * `turn: { safe: true }` streams a safe turn in the caller's Asks thread (see `AgentChatTurn`); a refusal throws a
+     * `RecursivError` whose code is a `SafeTurnRefusalCode`, before anything streams.
      */
     async *chatStream(id, input) {
         yield* this.streamChunks(id, input);
@@ -286,6 +291,11 @@ export class AgentsResource {
                     code: 'stream_error',
                 });
             }
+            // A 429 is a RateLimitError, as on every other request: with its scope and reset (a safe turn's daily cap is
+            // `scope: 'action'`, see SafeTurnRefusalCode).
+            if (response.status === 429 && errorBody?.error && typeof errorBody.error === 'object') {
+                throw new RateLimitError(errorBody.error, rateLimitDetailsFromResponse(response.headers, errorBody.error));
+            }
             throw new RecursivError(response.status, errorBody.error);
         }
         return response;