@recursiv/sdk 0.7.51 → 0.7.52

package/README.md

@@ -140,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
@@ -148,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' })
 ```
@@ -613,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,
@@ -643,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

@@ -143,6 +143,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,8 +183,8 @@ 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';
@@ -201,7 +202,7 @@ 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';

package/dist/index.js

@@ -181,7 +181,7 @@ 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);

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');
     }

package/dist/resources/boosts.d.ts

@@ -44,10 +44,27 @@ export interface BoostBalance {
     /** The 50 most recent balance movements, newest first. */
     ledger: BoostLedgerEntry[];
 }
+/** The boost credit the key's app includes with its paid plans. */
+export interface BoostPlanCredit {
+    /** Micro-USD each paid billing period of a plan adds, by tier key (e.g. `plus`, `pro`). */
+    per_period_micros: Record<string, number>;
+    /** What your current plan on this app adds each paid period; 0 without one. */
+    current_micros: number;
+    /** When your next paid period starts and adds `current_micros`; null when none is due. */
+    next_grant_at: string | null;
+    /**
+     * Plan credit you owe: taken back after your plan dropped or ended inside a period, but already
+     * spent. Your next plan credit repays it before adding anything. 0 when nothing is owed
+     * (absent from older servers).
+     */
+    owed_micros?: number;
+}
 export interface BoostBalanceResponse extends SingleResponse<BoostBalance> {
+    /** `plan_credit` is null when the app's plans include no boost credit (absent from older servers). */
     meta: {
         min_cpm_micros: number;
         topup?: BoostTopupLimits;
+        plan_credit?: BoostPlanCredit | null;
     };
 }
 export interface BoostCampaignResponse extends SingleResponse<BoostCampaign> {
@@ -98,7 +115,10 @@ export declare class BoostsResource {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedResponse<BoostCampaign>>;
-    /** Your balance, recent ledger, the CPM floor, and the top-up limits. */
+    /**
+     * Your balance, recent ledger, the CPM floor, the top-up limits, and the boost credit your
+     * plan on this app adds each paid period (`meta.plan_credit`, a `grant` ledger row per period).
+     */
     balance(): Promise<BoostBalanceResponse>;
     /** Pause one of your active campaigns. */
     pause(campaignId: string): Promise<BoostCampaignResponse>;
@@ -112,6 +132,8 @@ export declare class BoostsResource {
      * Buy boost credit: opens a one-time Stripe Checkout for `amount_cents` (USD) on the app's
      * own Stripe account. The balance is credited once the payment succeeds. Limits are in
      * `balance().meta.topup`. Requires a project-scoped key with `billing:write`.
+     * `return_url` keeps its own query and fragment; `topup=success&session_id=<id>` or
+     * `topup=cancelled` is added to its query (to the fragment's query for a hash route).
      */
     topup(input: {
         amount_cents: number;

package/dist/resources/boosts.js

@@ -20,7 +20,10 @@ export class BoostsResource {
     mine(params) {
         return this.client.get('/boosts/mine', params);
     }
-    /** Your balance, recent ledger, the CPM floor, and the top-up limits. */
+    /**
+     * Your balance, recent ledger, the CPM floor, the top-up limits, and the boost credit your
+     * plan on this app adds each paid period (`meta.plan_credit`, a `grant` ledger row per period).
+     */
     balance() {
         return this.client.get('/boosts/balance');
     }
@@ -44,6 +47,8 @@ export class BoostsResource {
      * Buy boost credit: opens a one-time Stripe Checkout for `amount_cents` (USD) on the app's
      * own Stripe account. The balance is credited once the payment succeeds. Limits are in
      * `balance().meta.topup`. Requires a project-scoped key with `billing:write`.
+     * `return_url` keeps its own query and fragment; `topup=success&session_id=<id>` or
+     * `topup=cancelled` is added to its query (to the fragment's query for a hash route).
      */
     topup(input) {
         return this.client.post('/boosts/topup', input, { retry: false });

package/dist/resources/communities.d.ts

@@ -25,7 +25,7 @@ export declare class CommunitiesResource {
     }): Promise<PaginatedResponse<RelatedCommunity>>;
     /** List members of a community. `q` searches by name or username. */
     members(id: string, params?: CommunityPeopleParams): Promise<PaginatedResponse<CommunityMember>>;
-    /** Create a new community */
+    /** Create a new community. Omit slug for a server-generated collision-resistant slug. */
     create(input: CreateCommunityInput): Promise<SingleResponse<CreatedCommunity>>;
     /** Join a community */
     join(id: string): Promise<SingleResponse<JoinResult>>;

package/dist/resources/communities.js

@@ -33,7 +33,7 @@ export class CommunitiesResource {
     members(id, params) {
         return this.client.get(`/communities/${id}/members`, params);
     }
-    /** Create a new community */
+    /** Create a new community. Omit slug for a server-generated collision-resistant slug. */
     create(input) {
         return this.client.post('/communities', input);
     }

package/dist/resources/curator.d.ts

@@ -1,5 +1,23 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, Post, SingleResponse } from '../types.js';
+import type { DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+/** Which surface is asking: Home's For You (default) or Discover's For you. */
+export type ForYouSurface = 'home' | 'discover';
+export type ForYouParams = {
+    limit?: number;
+    offset?: number;
+    /** The previous page's `meta.next_cursor`: pages a stored ranking, so posts read meanwhile never shift the next page. */
+    cursor?: string;
+    /** Adds `meta.discovery` (layouts) and the public safety floor; limit <= 25. */
+    discovery?: boolean;
+    /** `discover` ranks for Discover: fresher, beyond the member's follows, with their category order. */
+    surface?: ForYouSurface;
+};
+export interface ForYouMeta extends PaginationMeta {
+    discovery?: DiscoveryLayout;
+    next_cursor?: string;
+    /** Whether the ranker can personalize for this member yet (3 follows or 3 upvoted authors). */
+    personalized?: boolean;
+}
 /** RSS / Atom source. Default — `type` may be omitted for back-compat. */
 export interface CuratorRssSource {
     type?: 'rss';
@@ -250,10 +268,10 @@ export declare class CuratorResource {
      * existing posts for the signed-in user (engagement + recency + social +
      * affinity, no model calls). Returns posts in the same shape as
      * `sdk.posts.list()`, so any feed UI renders it unchanged. Requires a
-     * project-scoped key (the feed is per-app).
+     * project-scoped key (the feed is per-app). Servers that predate `cursor`,
+     * `discovery` and `surface` ignore them.
      */
-    forYou(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Post>>;
+    forYou(params?: ForYouParams): Promise<PaginatedResponse<Post> & {
+        meta: ForYouMeta;
+    }>;
 }

package/dist/resources/curator.js

@@ -47,7 +47,8 @@ export class CuratorResource {
      * existing posts for the signed-in user (engagement + recency + social +
      * affinity, no model calls). Returns posts in the same shape as
      * `sdk.posts.list()`, so any feed UI renders it unchanged. Requires a
-     * project-scoped key (the feed is per-app).
+     * project-scoped key (the feed is per-app). Servers that predate `cursor`,
+     * `discovery` and `surface` ignore them.
      */
     forYou(params = {}) {
         return this.client.get('/curator/foryou', params);

package/dist/resources/discovery.d.ts

@@ -1,4 +1,5 @@
 import type { DiscoveryLayout, Post } from '../types.js';
+import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
@@ -201,7 +202,20 @@ export declare class DiscoveryFeedSession {
 export declare class DiscoveryResource {
     private posts;
     private protocols;
-    constructor(posts: PostsResource, protocols: ProtocolsResource);
+    private curator?;
+    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined);
+    /**
+     * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
+     * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts
+     * from that category (the member's top one); without, it is Minds only. Never the radar. The page-0
+     * arrangement and when to use which are the app's choice.
+     */
+    createPersonalFeed(options: {
+        networks: SocialNetwork[];
+        learning?: DiscoveryLearning;
+        recommend?: DiscoveryRecommendationSources;
+        category?: string;
+    }): DiscoveryFeedSession;
     createFeed(options: {
         networks: SocialNetwork[];
         category?: string;

package/dist/resources/discovery.js

@@ -160,6 +160,9 @@ export class DiscoveryFeedSession {
         return this.pending;
     }
     async read(stream) {
+        // `discovery` asks only for the layout judgment (and, for Minds posts, the public-only floor). The
+        // server's safety floor does not depend on it, so a reader that drops it to skip layout work (a clip
+        // pool) is screened exactly like this session.
         const params = { limit: 25, ...(this.category ? { category: this.category } : {}), discovery: true };
         if (stream.protocol === 'minds') {
             // Discover leads with what is moving now: the REST hot order (engagement
@@ -462,9 +465,34 @@ export class DiscoveryFeedSession {
 export class DiscoveryResource {
     posts;
     protocols;
-    constructor(posts, protocols) {
+    curator;
+    constructor(posts, protocols, curator) {
         this.posts = posts;
         this.protocols = protocols;
+        this.curator = curator;
+    }
+    /**
+     * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
+     * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts
+     * from that category (the member's top one); without, it is Minds only. Never the radar. The page-0
+     * arrangement and when to use which are the app's choice.
+     */
+    createPersonalFeed(options) {
+        const curator = this.curator;
+        if (!curator)
+            throw new Error('createPersonalFeed needs the curator resource');
+        const list = {
+            // The session's `sort` and `category` are Discover's hot-order knobs; the ranker ignores them.
+            list: async (params) => {
+                const response = await curator.forYou({ limit: params?.limit, offset: params?.offset, cursor: params?.cursor, discovery: true, surface: 'discover' });
+                // A server that predates the cursor says has_more: false on a partial ranked page although its
+                // continuation serves the next offset. A cursor-aware server always says `personalized`, and its
+                // has_more is the end of the feed.
+                const legacy = typeof response.meta.personalized !== 'boolean';
+                return { ...response, meta: { ...response.meta, has_more: response.meta.has_more || (legacy && response.data.length > 0) } };
+            },
+        };
+        return new DiscoveryFeedSession(list, this.protocols, options.category ? options.networks : [], options.category, options.category ? 'all' : 'minds', options.learning, options.recommend);
     }
     createFeed(options) {
         // The radar rides along by default; an older server answers 404 and the session simply shows no story module.

package/dist/resources/invite-codes-admin.d.ts

@@ -18,12 +18,25 @@ export interface InviteCodeStats {
         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/invite-codes.d.ts

@@ -90,10 +90,20 @@ export interface BulkGenerateResult {
 }
 export interface InviteStats {
     codes: {
+        total: number;
+        active: number;
+        used: number;
+        expired: number;
+        revoked: number;
+        /** @deprecated Use `total`. Retained for legacy admin clients. */
         total_codes: number;
+        /** @deprecated Use `active`. Retained for legacy admin clients. */
         active_codes: number;
+        /** @deprecated Use `used`. Retained for legacy admin clients. */
         used_codes: number;
+        /** @deprecated Use `expired`. Retained for legacy admin clients. */
         expired_codes: number;
+        /** @deprecated Use `revoked`. Retained for legacy admin clients. */
         revoked_codes: number;
     };
     waitlist: Record<string, number>;

package/dist/resources/invite-codes.js

@@ -43,26 +43,26 @@ export class InviteCodesResource {
     // ── Admin Methods ──
     /** Admin: Initialize wave configs for the network */
     initializeWaves() {
-        return this.client.post('/invite-codes/admin/initialize-waves');
+        return this.client.post('/invite-codes-admin/waves/initialize');
     }
     /** Admin: Get all wave configs */
     getWaves() {
-        return this.client.get('/invite-codes/admin/waves');
+        return this.client.get('/invite-codes-admin/waves');
     }
     /** Admin: Activate a specific wave */
     activateWave(wave) {
-        return this.client.post('/invite-codes/admin/activate-wave', { wave });
+        return this.client.post('/invite-codes-admin/waves/activate', { wave });
     }
     /** Admin: Bulk generate invite codes */
     bulkGenerate(input) {
-        return this.client.post('/invite-codes/admin/bulk-generate', input);
+        return this.client.post('/invite-codes-admin/bulk-generate', input);
     }
     /** Admin: Get invite system stats */
     getStats() {
-        return this.client.get('/invite-codes/admin/stats');
+        return this.client.get('/invite-codes-admin/stats');
     }
     /** Admin: Get waitlist entries */
     getWaitlist(params) {
-        return this.client.get('/invite-codes/admin/waitlist', params);
+        return this.client.get('/invite-codes-admin/waitlist', params);
     }
 }

package/dist/resources/posts.d.ts

@@ -1,15 +1,36 @@
 import type { HttpClient } from '../client.js';
 import type { PaginatedResponse, SingleResponse, DeleteResponse, Post, PostDetail, CreatePostInput, CreatedPost, UpdatePostInput, ListPostsParams, ListPostRepliesParams, PostRepliesPage, SearchPostsParams, ReactionType } from '../types.js';
+/** How GET /posts/categories ordered its answer: the member's own order, the app's popularity order, or the fixed order. */
+export type CategoryOrder = 'personal' | 'popular' | 'static';
+/** Why an answer is not `personal`. */
+export type CategoryOrderReason = 'low_signal' | 'deadline' | 'requested' | 'experiment_off';
+export interface CategoryOrderMeta {
+    order: CategoryOrder;
+    /** 16 hex; equal ids mean the same order. */
+    order_id: string;
+    as_of: string;
+    reason?: CategoryOrderReason;
+    /** Whether For You can personalize for this member yet; absent when the member's order was not read. */
+    personalized?: boolean;
+}
 export declare class PostsResource {
     private client;
     constructor(client: HttpClient);
     /** List posts with optional filters */
     list(params?: ListPostsParams): Promise<PaginatedResponse<Post>>;
-    /** Broad categories currently enabled for public posts in this app. */
-    categories(): Promise<SingleResponse<Array<{
+    /**
+     * Broad categories currently enabled for public posts in this app, in the order this member should see
+     * them: their own order once the app serves personal orders, otherwise the app's popularity order. The
+     * order is private to the member. `order` asks for a specific one (default `personal`).
+     */
+    categories(params?: {
+        order?: CategoryOrder;
+    }): Promise<SingleResponse<Array<{
         id: string;
         name: string;
-    }>>>;
+    }>> & {
+        meta?: CategoryOrderMeta;
+    }>;
     /** List posts the authenticated caller has upvoted. */
     liked(params?: Pick<ListPostsParams, 'limit' | 'offset' | 'cursor'>): Promise<PaginatedResponse<Post>>;
     /** Posts similar to this one (embedding neighbours), in the app's scope. */

package/dist/resources/posts.js

@@ -7,9 +7,14 @@ export class PostsResource {
     list(params) {
         return this.client.get('/posts', params);
     }
-    /** Broad categories currently enabled for public posts in this app. */
-    categories() {
-        return this.client.get('/posts/categories');
+    /**
+     * Broad categories currently enabled for public posts in this app, in the order this member should see
+     * them: their own order once the app serves personal orders, otherwise the app's popularity order. The
+     * order is private to the member. `order` asks for a specific one (default `personal`).
+     */
+    categories(params) {
+        // No params, no query: the same request older SDKs make.
+        return params ? this.client.get('/posts/categories', params) : this.client.get('/posts/categories');
     }
     /** List posts the authenticated caller has upvoted. */
     liked(params) {

package/dist/resources/protocols.d.ts

@@ -1255,7 +1255,10 @@ export declare class ProtocolsResource {
         limit?: number;
         cursor?: string;
     }): Promise<SingleResponse<SocialAuthorFeed>>;
-    /** Public, app-moderated discovery without account authority. Enrichment uses cached judgments only. */
+    /**
+     * Public, app-moderated discovery without account authority. Enrichment uses cached judgments only.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     */
     getSharedTrends(projectId: string, params: {
         protocol: string;
         limit?: number;
@@ -1264,7 +1267,7 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
     }): Promise<SingleResponse<SocialTrends>>;
-    /** Open a provider-listed topic through the same public-only app boundary. */
+    /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId: string, params: {
         protocol: string;
         topic: string;
@@ -1314,7 +1317,10 @@ export declare class ProtocolsResource {
         post: string;
         readRef?: string;
     }): Promise<SingleResponse<SocialConversation>>;
-    /** Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content. */
+    /**
+     * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     */
     getPublicTrends(params: {
         protocol: string;
         limit?: number;
@@ -1323,7 +1329,7 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrends>>;
-    /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
+    /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. Screened like `getPublicTrends`. */
     getPublicTrendFeed(params: {
         protocol: string;
         topic: string;

package/dist/resources/protocols.js

@@ -89,12 +89,15 @@ export class ProtocolsResource {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/author-feed`, { protocol: params.protocol, actor: params.actor,
             limit: params.limit, cursor: params.cursor });
     }
-    /** Public, app-moderated discovery without account authority. Enrichment uses cached judgments only. */
+    /**
+     * Public, app-moderated discovery without account authority. Enrichment uses cached judgments only.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     */
     getSharedTrends(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trends`, { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
             includePreviews: params.includePreviews, category: params.category, discovery: params.discovery });
     }
-    /** Open a provider-listed topic through the same public-only app boundary. */
+    /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trend-feed`, { protocol: params.protocol, topic: params.topic,
             limit: params.limit, cursor: params.cursor, category: params.category, discovery: params.discovery });
@@ -148,14 +151,17 @@ export class ProtocolsResource {
     getPublicConversation(params) {
         return this.client.get('/protocols/social/conversation', { protocol: params.protocol, post: params.post, readRef: params.readRef });
     }
-    /** Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content. */
+    /**
+     * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     */
     getPublicTrends(params, options) {
         return this.client.get('/protocols/social/trends', { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
             ...(params.includePreviews !== undefined ? { includePreviews: params.includePreviews } : {}),
             ...(params.category !== undefined ? { category: params.category } : {}),
             ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) }, ...readOptions(options));
     }
-    /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
+    /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. Screened like `getPublicTrends`. */
     getPublicTrendFeed(params, options) {
         return this.client.get('/protocols/social/trend-feed', { protocol: params.protocol, topic: params.topic, limit: params.limit, cursor: params.cursor,
             ...(params.category !== undefined ? { category: params.category } : {}),

package/dist/types.d.ts

@@ -226,7 +226,11 @@ export interface UpdatePostInput {
 }
 export type ReactionType = 'like' | 'heart' | 'fire' | 'laugh' | 'sad' | 'angry' | 'upvote' | 'downvote';
 export interface ListPostsParams extends PaginationParams {
-    /** Public-only feed with a bounded Jev presentation hint. Limit <=25. */
+    /**
+     * Public-only feed with a bounded Jev presentation hint. Limit <=25.
+     * The safety floor does not depend on it: a category page and every app-wide
+     * `sort: 'hot'` or `'score'` read are screened with or without a layout.
+     */
     discovery?: boolean;
     /** Public-only broad category. Requires an enabled app experiment; limit <=25. */
     category?: string;
@@ -366,7 +370,8 @@ export interface CommunityBannedMember {
 }
 export interface CreateCommunityInput {
     name: string;
-    slug: string;
+    /** Optional vanity slug. Omit it for a server-generated collision-resistant default. */
+    slug?: string;
     description?: string;
     privacy?: 'public' | 'private' | 'hidden';
 }
@@ -719,7 +724,8 @@ export interface AgentDetail extends Agent {
 }
 export interface CreateAgentInput {
     name: string;
-    username: string;
+    /** Optional public handle. Omit it for a server-generated collision-resistant default. */
+    username?: string;
     bio?: string;
     model?: string;
     system_prompt?: string;
@@ -1082,6 +1088,13 @@ export interface LoginHistoryEntry {
 }
 export interface RecursivConfig {
     apiKey?: string;
+    /**
+     * Whether to fall back to `RECURSIV_API_KEY` when `apiKey` is omitted.
+     * Defaults to true for backwards compatibility and branded pre-auth flows.
+     * Set to false for public clients that must remain keyless even in a
+     * credentialed server process.
+     */
+    inheritEnvironmentApiKey?: boolean;
     baseUrl?: string;
     timeout?: number;
     maxRetries?: number;

package/llm.md

@@ -131,7 +131,7 @@ const { data } = await r.sandbox.execute({ code: '1 + 1', language: 'typescript'
 ```typescript
 const { data: agent } = await r.agents.create({
   name: 'Home Assistant',
-  username: 'home_bot_' + Date.now(),
+  // username is optional; the server generates a collision-resistant handle
   model: 'anthropic/claude-sonnet-4.6', // see SUPPORTED_MODELS
   system_prompt: 'You help homeowners maintain their property.',
   project_id: projectId, // app-customer flow; works with per-user keys. Use organization_id only for team-owned agents.
@@ -647,7 +647,7 @@ Methods: `list`, `get`, `create`, `delete`
 
 - `r.settings` — User preferences, sessions, password changes, account deletion. `revokeOtherSessions({ keep_session_token? })` signs out every other device and keeps this key (and the proven session); `revokeAllSessions()` also revokes this key. Accounts with no password confirm `requestEmailChange({ new_email, email_code })` with a code from `requestConfirmationCode('email_change')`. With a project-bound key, `getPreferences()` includes app-scoped `content`; persist changes with `updateContent({ show_nsfw?, autoplay_video?, ai_enabled?, default_feed? })`.
 - `r.billing` — Usage tracking, checkout sessions, portal sessions, metered billing
-- `r.appSubscriptions` — Project-scoped consumer plans: `checkout` (409 `subscription_exists` when the member already pays), `status`, `createPortalSession`, `previewTierChange({ tier })`, `changeTier({ tier, proration_date? })` (in-place, prorated, never a second subscription)
+- `r.appSubscriptions` — Project-scoped consumer plans: `checkout` (409 `subscription_exists` when the member already pays), `status`, `createPortalSession({ return_url, flow?: 'cancel' })` (`flow: 'cancel'` opens Stripe's cancel confirmation; 409 `no_subscription` when there is no plan to cancel), `previewTierChange({ tier })`, `changeTier({ tier, proration_date? })` (in-place, prorated, never a second subscription)
 - `r.boosts` — Promoted posts (micro-USD): `create`, `mine`, `balance`, `pause`, `resume`, `cancel`, `recordEvent`; buy credit with `topup({ amount_cents, return_url })` then `confirmTopup(sessionId)` (credits once); admin `listPendingReview`, `review`, `grant`
 - `r.notifications` — The notification stream: `list({ category: 'social' })` (rows carry `actor`, `reaction_type` and a `post_preview` with the viewer's `user_reaction`/`reposted_by_viewer_id` and counts), `unreadCount({ category })` for badges (`const { data } = await r.notifications.unreadCount({ category: 'social' })`), `markAsRead(id)`, `archive(id)` to dismiss, `markAllAsRead(category)` or `markAllAsRead({ category, organization_id })`, plus push token `registerToken`/`unregisterToken`. A push's `data.notificationId` is the row to mark read on tap. DMs are not in the stream.
 - `r.uploads` — Legacy media upload URLs (prefer `r.storage` for new projects)
@@ -676,10 +676,10 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 - Native follows: `nativeFollowState({ accountId, protocol, nativeId })`, `prepareNativeFollow({ clientMutationId, accountId, protocol, nativeId, action: "follow" | "unfollow" })`, `submitNativeFollow(id, { approve: true, event? })`, `nativeFollowStatus(id)`. Show the acting identity and native following/requested/unfollowed state separately from the Minds feed subscription. Nostr must sign the complete review event without dropping other contacts; stale lists require a fresh review. Keep mutation IDs and reconcile ambiguous outcomes without replay. Requires current follow scopes and API `NATIVE_SOCIAL_FOLLOW_PROJECTS` plus source controls.
 - Native reposts: `nativeRepostState({ accountId, protocol, nativeId })`, `prepareNativeRepost({ clientMutationId, accountId, protocol, nativeId, action: "repost" | "unrepost" })`, `submitNativeRepost(id, { approve: true, event? })`, `nativeRepostStatus(id)`. Requires `NATIVE_SOCIAL_REPOST_PROJECTS`, account capability and explicit approval; Nostr signs the exact review (kind 6 or own kind 5). Unknown attempts only reconcile. Bluesky connections need the new repost scope; ActivityPub uses write:statuses. Native likes: `nativeLikeState({ accountId, protocol, nativeId })`, `prepareNativeLike({ clientMutationId, accountId, protocol, nativeId, action: "like" | "unlike" })`, `submitNativeLike(id, { approve: true, event? })`, and `nativeLikeStatus(id)`. Display the selected account, source and action before approval. Only Nostr supplies `event`: sign the exact public `signing.event` in the review; never transmit a private key. Preserve mutation IDs on ambiguous responses and refresh unknown results instead of resending. Read capabilities before offering actions; old reply-only connections need reconnecting for likes. Nostr results describe the connected relay, not every public relay. The app-specific `NATIVE_SOCIAL_LIKE_PROJECTS` switch and source controls must be enabled on the API.
 - Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, media?, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source, exact `wireText` and every reviewed `media` item with its alt text; connection is not publication approval. `media` takes the same `NativeMediaInput[]` as `prepareNativePost` and needs the account's `publish_media` capability. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
-- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
+- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
   - Native Nostr: `const { data: preview } = await r.protocols.prepareNativeNostr(identityId, { action: "publish", content: draft })`; review and sign the exact public event, then `submitNativeNostr(identityId, { intent: preview.intent, event, approve: true })`. Preparation/submission never auto-retry. After uncertainty, use `getNativeNostrPost(identityId, preview.postId ?? preview.eventId)` before a user-selected retry of the identical intent/event: deletion checks the original note's `postId`, publication checks `eventId`. Check `nativeNostrAccount()` enablement first; keys stay with the signer. For replies, after `nativeNostrAccount()` advertises `reply_text_note`, use `prepareNativeNostr(identityId, { action: "reply", content: draft, parentId: post.nativeId })`. Review returned parent/root/participants/relay and exact event, sign with the connected client signer, then `submitNativeNostr(identityId, { intent, event, approve: true })`. Requires users:read, posts:read and posts:write. Kind1 public notes only; reply enablement and shared UI/live proof remain pending. Do not inherit arbitrary notification tags or relay hints. Signing mutations never auto-retry; check `getNativeNostrPost(identityId, eventId)` after uncertainty before a user-selected identical-event retry.
   - Hosted Bluesky account on the app's own PDS: `const { data } = await r.protocols.createHostedIdentity({ protocol: 'atproto', handle: 'alice', email })`. Only the label is sent; `data.handle` carries the domain and `data.password` is returned this once, never stored. Never auto-retried. Either the account is finished or it is removed again. 409 `handle_unavailable` = choose another label; 503 `handle_dns_unavailable`/`handle_unresolvable`/`handle_unverified` = operator setup, retry later unchanged.
-  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows.
+  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor? })`; render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.
   - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.
   - Lists return `{ data: ProtocolQuarantinedCandidate[], meta: { limit, has_more, next_cursor } }`; use the opaque `next_cursor`, not offset pagination. The API defaults `limit` to 20 and permits at most 50. Details return `{ data: ProtocolQuarantinedCandidate }`. Every candidate has `state: 'quarantined'` and `content_format: 'plain'`; render its bounded `content` as text, respect `content_truncated`, and distinguish upstream `published_at` from local `observed_at` / `created_at`.
@@ -790,6 +790,7 @@ The REST API (`/api/v1/*`) supports the `Idempotency-Key` header on POST/PUT/PAT
 ```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
@@ -798,9 +799,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' })
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.51",
+  "version": "0.7.52",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",
@@ -79,6 +79,6 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:unit": "vitest run"
+    "test:unit": "vitest run && tsc && node ../../scripts/security/verify-sdk-anonymous-package.mjs"
   }
 }