@recursiv/sdk 0.7.49 → 0.7.51

package/dist/resources/wallet.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { SingleResponse } from '../types.js';
+import type { PaginatedResponse, SingleResponse } from '../types.js';
 interface WalletInfo {
     configured: boolean;
     address: string | null;
@@ -37,6 +37,39 @@ export interface PayoutState {
     payouts_enabled: boolean;
     country: string | null;
 }
+/** A wallet the user linked and (optionally) verified. */
+export interface LinkedTokenWallet {
+    chain: string;
+    address: string;
+    verified_at: string | null;
+}
+/** The user's MINDS token balance from the off-chain ledger. */
+export interface TokenBalance {
+    /** Signed wei as a decimal string: it exceeds Number.MAX_SAFE_INTEGER, never parse it as a number. */
+    offchain_wei: string;
+    /** The same balance in MINDS, rounded to 6 decimal places. Display only. */
+    offchain_minds: number;
+    /** How many off-chain ledger entries make up the balance. */
+    entries: number;
+    linked_wallets: LinkedTokenWallet[];
+    base_wallet_address: string | null;
+}
+/** One token ledger movement. */
+export interface TokenLedgerEntry {
+    id: string;
+    category: string | null;
+    /** Signed wei as a decimal string. */
+    amount_wei: string;
+    amount_minds: number;
+    asset: string;
+    settlement: string;
+    tx_hash: string | null;
+    counterparty_user_id: string | null;
+    subject_type: string | null;
+    subject_id: string | null;
+    status: string;
+    occurred_at: string;
+}
 export declare class WalletResource {
     private client;
     constructor(client: HttpClient);
@@ -44,6 +77,13 @@ export declare class WalletResource {
     getMyWallet(): Promise<SingleResponse<WalletInfo>>;
     /** Get wallet balance for the current user */
     getBalance(): Promise<SingleResponse<WalletBalance>>;
+    /** The current user's MINDS token balance (off-chain ledger) and linked wallets. */
+    getTokenBalance(): Promise<SingleResponse<TokenBalance>>;
+    /** The current user's token ledger, newest first (limit up to 200, default 50). */
+    getTokenLedger(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<TokenLedgerEntry>>;
     /** USD payout eligibility for the current app user (Stripe Connect). */
     getPayouts(): Promise<SingleResponse<PayoutState>>;
     /** Start or resume payout onboarding. Open the returned URL in a browser. */

package/dist/resources/wallet.js

@@ -11,6 +11,14 @@ export class WalletResource {
     getBalance() {
         return this.client.get('/wallet/balance');
     }
+    /** The current user's MINDS token balance (off-chain ledger) and linked wallets. */
+    getTokenBalance() {
+        return this.client.get('/wallet/token-balance');
+    }
+    /** The current user's token ledger, newest first (limit up to 200, default 50). */
+    getTokenLedger(params) {
+        return this.client.get('/wallet/token-ledger', params);
+    }
     /** USD payout eligibility for the current app user (Stripe Connect). */
     getPayouts() {
         return this.client.get('/wallet/payouts');

package/dist/types.d.ts

@@ -92,7 +92,14 @@ export interface User extends UserSummary {
     posts_count: number;
     created_at: string;
 }
-export interface FollowUser {
+/** The caller's follow relationship with a listed account (both directions). */
+export interface ViewerRelationship {
+    /** The caller follows this account. */
+    is_following: boolean;
+    /** This account follows the caller. */
+    follows_you: boolean;
+}
+export interface FollowUser extends ViewerRelationship {
     id: string;
     name: string;
     username: string;
@@ -155,7 +162,10 @@ export interface RepostedPost {
     created_at: string;
 }
 export interface PostDetail extends Post {
+    /** The newest replies (at most 50). */
     replies: PostReply[];
+    /** Present when the thread has more replies; pass it to `posts.replies(id, { cursor })` for the next, older page. */
+    replies_next_cursor?: string | null;
 }
 export interface PostReply {
     id: string;
@@ -164,8 +174,27 @@ export interface PostReply {
     author: UserSummary;
     tags: Tag[];
     reactions_count: number;
+    score?: number;
+    user_reaction?: string | null;
+    /** This reply's own reply count, so its sub-thread can be opened. */
+    reply_count?: number;
     created_at: string;
 }
+export interface ListPostRepliesParams {
+    /** 1-100, default 50. */
+    limit?: number;
+    /** `replies_next_cursor` from `posts.get`, or `meta.next_cursor` from the previous page. */
+    cursor?: string;
+}
+/** One page of a post's replies, newest first. */
+export interface PostRepliesPage {
+    data: PostReply[];
+    meta: {
+        limit: number;
+        has_more: boolean;
+        next_cursor: string | null;
+    };
+}
 export interface CreatePostInput {
     content: string;
     content_format?: 'plain' | 'markdown';
@@ -214,6 +243,10 @@ export interface ListPostsParams extends PaginationParams {
 export interface SearchPostsParams extends PaginationParams {
     q: string;
     tag_ids?: string;
+    /** `relevance` (default) or `new` (newest first). */
+    sort?: 'relevance' | 'new';
+    since?: string;
+    until?: string;
 }
 export type QueryParams = Record<string, unknown>;
 export interface CommunityCreator {
@@ -232,6 +265,10 @@ export interface Community {
     privacy: 'public' | 'private' | 'hidden';
     created_by: CommunityCreator;
     member_count: number;
+    /** Denormalized post count. */
+    post_count?: number;
+    /** Whether the caller is an accepted member. Returned by `list` and `search`. */
+    is_member?: boolean;
     created_at: string;
 }
 /** Filters accepted by the communities directory. */
@@ -240,11 +277,71 @@ export interface ListCommunitiesParams extends PaginationParams {
     member?: boolean;
     /** Restrict personal keys to one organization. Project-bound keys are already scoped. */
     organization_id?: string;
-    /** Server-side directory ordering. */
+    /** Server-side directory ordering. With `q`, name matches come first and this breaks ties. */
     sort?: 'members' | 'active' | 'newest';
+    /**
+     * Case-insensitive text search over name and description, up to 200
+     * characters. With `member: true` it searches only the caller's own groups.
+     */
+    q?: string;
 }
+/** The caller's own membership row in a group, if any. */
+export type CommunityMembershipStatus = 'accepted' | 'pending' | 'invited' | 'banned';
 export interface CommunityDetail extends Community {
     post_count: number;
+    /** The caller's role when they are an accepted member (the creator is always `owner`). */
+    viewer_role?: 'owner' | 'admin' | 'moderator' | 'member' | null;
+    /** The caller's own membership state, whether or not it is accepted. */
+    membership_status?: CommunityMembershipStatus | null;
+    /** People waiting to join. Present only for moderators and up. */
+    pending_request_count?: number;
+    /** Always absent or false on a full detail; see `CommunityCard`. */
+    limited?: false;
+}
+/**
+ * A private group seen from outside: `communities.get` returns this to a
+ * signed-in person who is not an accepted member (including a pending
+ * requester or a banned account), so an app can offer "Request to join" or
+ * show "Requested". The description, creator, roster, post count and posts
+ * stay with members. Hidden groups still answer 404, and so does an app's
+ * private group to a caller outside that app (an app key sees its own app).
+ */
+export interface CommunityCard {
+    id: string;
+    name: string;
+    slug: string;
+    image: string | null;
+    banner: string | null;
+    privacy: 'private';
+    member_count: number;
+    is_member: false;
+    viewer_role: null;
+    membership_status: CommunityMembershipStatus | null;
+    limited: true;
+    description?: undefined;
+    created_by?: undefined;
+    post_count?: undefined;
+    created_at?: undefined;
+}
+/** A row from `communities.related`: a public group, ranked by shared members. */
+export interface RelatedCommunity {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    image: string | null;
+    banner: string | null;
+    privacy: 'public';
+    /** Whether the caller is an accepted member of this related group. */
+    is_member: boolean;
+    member_count: number;
+    post_count: number;
+    /** How many members this group shares with the one asked about. */
+    overlap: number;
+}
+/** Paging plus `q`: a case-insensitive name or username search, up to 200 characters. */
+export interface CommunityPeopleParams extends PaginationParams {
+    q?: string;
 }
 export interface CommunityMember {
     id: string;
@@ -328,8 +425,25 @@ export interface Conversation {
     last_message: LastMessage | null;
     /** Omitted by API versions deployed before message requests. */
     request_status?: ChatRequestStatus;
+    /** The member who started it; null when it cannot be told (older threads). */
+    created_by?: string | null;
+    /** Whether `chat.deleteConversation()` is allowed for the caller. */
+    can_delete?: boolean;
+    /** Whether `chat.leave()` is allowed for the caller. */
+    can_leave?: boolean;
     created_at: string;
 }
+export interface ConversationRequestResult {
+    id: string;
+    request_status: ChatRequestStatus;
+    /** False when the conversation was already in that state. */
+    changed: boolean;
+}
+export interface LeaveConversationResult {
+    left: true;
+    /** True when the caller was the last person in it, so the room was removed. */
+    conversation_deleted: boolean;
+}
 export interface ConversationDetail {
     /** Missing on older APIs: treat as unknown, never as plaintext permission. */
     encryption?: ConversationEncryptionPolicy;
@@ -340,6 +454,12 @@ export interface ConversationDetail {
     members: ConversationMemberDetail[];
     /** Omitted by API versions deployed before message requests. */
     request_status?: ChatRequestStatus;
+    /** The member who started it; null when it cannot be told (older threads). */
+    created_by?: string | null;
+    /** Whether `chat.deleteConversation()` is allowed for the caller. */
+    can_delete?: boolean;
+    /** Whether `chat.leave()` is allowed for the caller. */
+    can_leave?: boolean;
     created_at: string;
 }
 export interface MessageReaction {
@@ -656,6 +776,12 @@ export interface AgentChatInput {
     conversation_id?: string;
     new_conversation?: boolean;
 }
+/** Answer an existing message of yours again, without sending it a second time. */
+export interface AgentChatRetryInput {
+    conversation_id: string;
+    /** Your message whose reply failed (or that you want answered again). Must be the latest one. */
+    retry_message_id: string;
+}
 export interface AgentChatResult {
     message_id: string;
     conversation_id: string;
@@ -727,6 +853,24 @@ export interface Profile {
     is_ai: boolean;
     created_at: string;
 }
+/** A row of a followers/following list: the profile plus the caller's relationship with it. */
+export interface FollowListProfile extends Profile, ViewerRelationship {
+}
+/** An account the caller blocked. */
+export interface BlockedProfile extends Profile {
+    blocked_at: string;
+}
+/** An account the caller muted. */
+export interface MutedProfile extends Profile {
+    muted_at: string;
+}
+/** Paging and name/username filter for the caller's blocked and muted lists. */
+export type ModerationListParams = {
+    limit?: number;
+    offset?: number;
+    /** Case-insensitive match on name or username. */
+    search?: string;
+};
 export interface ProfileDetail extends Profile {
     followers_count: number;
     following_count: number;
@@ -736,6 +880,12 @@ export interface ProfileMe extends Profile {
     email_verified: boolean;
     role: string;
     two_factor_enabled: boolean | null;
+    /**
+     * Whether the account can confirm changes with a password. False for
+     * OTP-only accounts: they confirm email and two-factor changes with a code
+     * from `settings.requestConfirmationCode`. Absent on servers older than this field.
+     */
+    has_password?: boolean;
     followers_count: number;
     following_count: number;
     updated_at: string;
@@ -749,6 +899,20 @@ export interface UpdateProfileInput {
 export interface SearchProfilesParams extends PaginationParams {
     q: string;
 }
+export interface SearchMentionsParams {
+    /** What the member typed after `@` (a leading `@` is ignored). */
+    q: string;
+    /** Default 8, max 25. */
+    limit?: number;
+    [key: string]: unknown;
+}
+/** An account a composer's @-picker may offer: a person or an agent. */
+export interface MentionCandidate extends Profile {
+    /** True for an agent (a platform or app agent, not a person's own AI). */
+    is_agent: boolean;
+    /** True when the caller follows this account; followed accounts rank first. */
+    is_following: boolean;
+}
 export interface LeaderboardEntry {
     id: string;
     name: string;
@@ -759,6 +923,8 @@ export interface LeaderboardEntry {
     post_count: number;
     reaction_count: number;
     engagement: number;
+    /** Whether the caller follows this account. */
+    is_following?: boolean;
     created_at: string;
 }
 export interface Organization {
@@ -868,7 +1034,39 @@ export interface ChangePasswordInput {
 }
 export interface RequestEmailChangeInput {
     new_email: string;
-    password: string;
+    /** Required for an account with a password. */
+    password?: string;
+    /**
+     * Required for an account with no password (`has_password: false`): the
+     * code from `settings.requestConfirmationCode('email_change')`, which is
+     * sent to the CURRENT address.
+     */
+    email_code?: string;
+}
+/** What a confirmation code is for. A code for one purpose never confirms another. */
+export type ConfirmationCodePurpose = 'email_change' | 'two_factor';
+export interface ConfirmationCodeSent {
+    success: true;
+    purpose: ConfirmationCodePurpose;
+    /** ISO timestamp. Codes live ten minutes. */
+    expires_at: string;
+}
+export interface RevokeOtherSessionsInput {
+    /**
+     * The Better Auth session token this device holds, if any. Proving it keeps
+     * that session alive; without it every session is revoked. The calling API
+     * key is always kept.
+     */
+    keep_session_token?: string;
+}
+export interface RevokeOtherSessionsResult {
+    success: true;
+    /** Better Auth sessions revoked. */
+    revoked: number;
+    /** Other API keys revoked (within this key's app when the key is app-bound). */
+    api_keys_revoked: number;
+    /** Whether keep_session_token named a session of this account, which was kept. */
+    kept_session: boolean;
 }
 export interface DeletionStatus {
     requested: boolean;

package/llm.md

@@ -162,7 +162,7 @@ await r.agents.grantProjectAccess(agent.id, {
 })
 ```
 
-Methods: `list`, `get`, `create`, `update`, `delete`, `chat`, `chatStream`, `chatStreamText`, `conversations`, `listDiscoverable`, `leaderboard`, `grantProjectAccess`, `revokeProjectAccess`, `resetRequestCount`, `getByClaimToken`, `claim`, `orchestratorStatus`
+Methods: `list`, `get`, `create`, `update`, `delete`, `chat`, `chatStream`, `chatStreamText`, `retryChatStream`, `retryChatStreamText` ("Try again": `{ conversation_id, retry_message_id }` re-answers your latest message without sending it twice), `conversations`, `listDiscoverable`, `leaderboard`, `grantProjectAccess`, `revokeProjectAccess`, `resetRequestCount`, `getByClaimToken`, `claim`, `orchestratorStatus`
 
 ### r.brain — AI assistant messaging
 
@@ -371,6 +371,24 @@ Bearer auth, with a Cookie fallback for native/server runtimes.
 
 Methods: `signUp`, `signIn`, `getSession`, `signOut`, `createApiKey`, `signInAndCreateKey`, `signUpAndCreateKey`, `verifyOtpAndCreateKey`
 
+Also: `signInWithUsername` / `signInWithUsernameAndCreateKey` (handle + password, resolved on the app's network; pass `{ projectId }` as app context), `forgetPassword(input, appContext?)`, `resetPassword({ newPassword, token }, appContext?)`. Password sign-in on a two-factor account throws `AuthenticationError` with code `two_factor_required`; its `details` is `{ twoFactorToken, methods }`. Finish with `completeTwoFactorSignIn({ twoFactorToken, code, method? })` (`method: 'backup_code'` for a backup code), or `completeTwoFactorSignInAndCreateKey(input, keyInput)` after a `*AndCreateKey` sign-in. Ten wrong codes lock the account's two-factor sign-in for fifteen minutes (`ACCOUNT_TEMPORARILY_LOCKED`, `RateLimitError` with `retryAfter`).
+
+```typescript
+// Sign-in on a two-factor account: catch two_factor_required, then send the code with the challenge.
+try { await r.auth.signInWithUsername({ username, password }, { projectId }) } catch (e) {
+  if (e.code === 'two_factor_required') await r.auth.completeTwoFactorSignIn({ twoFactorToken: e.details.twoFactorToken, code })
+}
+// Two-factor: session-token calls. verify/disable rotate the session; store the returned sessionToken.
+const { totpURI, backupCodes, sessionToken } = await r.auth.enableTwoFactor({ password }, session.token)
+const { sessionToken: live } = await r.auth.verifyTwoFactor({ code: '123456' }, sessionToken) // turns 2FA on
+// No password (profiles.me().has_password === false)? Confirm with an emailed code instead.
+// Enrolling such an account answers PASSWORD_REQUIRED_FOR_TWO_FACTOR unless the server enables it.
+await r.auth.requestTwoFactorEmailCode(live, { projectId }) // app context brands the email; then pass { emailCode } where you would pass { password }
+await r.auth.disableTwoFactor({ emailCode: '482913' }, live)
+```
+
+Two-factor methods: `enableTwoFactor`, `verifyTwoFactor`, `disableTwoFactor`, `regenerateTwoFactorBackupCodes`, `requestTwoFactorEmailCode`, `completeTwoFactorSignIn`, `completeTwoFactorSignInAndCreateKey`. OAuth consent screens: `exchangeSessionForCookie(token)` (browser, sets the API-origin cookie so `/api/auth/mcp/authorize` continues without a second sign-in), `getOAuthClientInfo({ clientId, redirectUri?, scope? })` (public client name, redirect hosts, `redirect_uri_registered`, granted scopes).
+
 **Mobile/React Native auth** (recommended — one call instead of three):
 ```typescript
 const anonSdk = new Recursiv({ anonymous: true, baseUrl });
@@ -457,9 +475,11 @@ Methods: `list`, `get`, `getBySlug`, `create`, `update`, `delete`, `members`, `a
 const { data: profile } = await r.profiles.me()
 await r.profiles.follow('user_xxx')
 const { data: results } = await r.profiles.search({ query: 'jane' })
+const { data: rows } = await r.profiles.followers('user_xxx') // each row: is_following, follows_you
+await r.profiles.mute('user_xxx') // server hides their posts and reposts of them from your feeds
 ```
 
-Methods: `list`, `me`, `get`, `getByUsername`, `search`, `update`, `follow`, `unfollow`, `followers`, `following`, `isFollowing`, `leaderboard`
+Methods: `list`, `me`, `get`, `getByUsername`, `search`, `mentions` (people + agents for an @-picker, follows first), `update`, `follow`, `unfollow`, `followers`, `following`, `followingIds` (your follow set as ids, cursor-paged), `isFollowing`, `related`, `leaderboard`, `block`, `unblock`, `blocked`, `mute`, `unmute`, `muted`
 
 ---
 
@@ -474,7 +494,9 @@ const { data: group } = await r.chat.createGroup({ name: 'Team', member_ids: ['u
 const { data: msgs } = await r.chat.messages(dm.id, { limit: 50 })
 ```
 
-Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+
+Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
@@ -518,9 +540,14 @@ const unsub = r.realtime.onMessage((msg) => {
 })
 // Cleanup listener
 unsub()
+
+// Any server event, plus `connect` (fires on every reconnect: refetch what you missed) and `disconnect`
+const off = r.realtime.on('notification', (n) => refreshBadge(n))
 ```
 
-Events: `onMessage`, `onMessageEdit`, `onMessageDelete`, `onTyping`, `onAgentThinking`
+Events: `onMessage`, `onMessageEdit`, `onMessageDelete`, `onTyping`, `onAgentThinking`, `on(event, fn)`
+
+Reconnects on its own (transport drops, token expiry, refused handshakes) with jittered backoff and a fresh single-use token per attempt; listeners and joined rooms carry over, so no app-side reconnect shim is needed. It stops only on `disconnect()` or a 401/403 from the token source. `connect()` is safe to call repeatedly.
 
 #### React / React Native specific hook
 
@@ -553,16 +580,19 @@ await r.posts.react(post.id, { type: 'fire' })
 const { data: results } = await r.posts.search({ query: 'shipped', community_id: 'comm_xxx' })
 ```
 
-Methods: `list`, `get`, `create`, `update`, `delete`, `search`, `react`, `unreact`
+Methods: `list`, `get`, `create`, `update`, `delete`, `search` (`sort: 'new'` for newest first), `replies(id, { limit, cursor })` (after `replies_next_cursor` on `get`), `react`, `unreact`
 
 ### r.communities
 
 ```typescript
 const { data: c } = await r.communities.create({ name: 'Denver Devs', slug: 'denver-devs', privacy: 'public' })
 await r.communities.join(c.id)
+const { data: found } = await r.communities.search('denver', { limit: 10 })   // name matches first
+const { data: mine } = await r.communities.search('book', { member: true })   // only my groups
+const { data: people } = await r.communities.members(c.id, { q: 'ada' })      // name or username
 ```
 
-Methods: `list`, `get`, `members`, `create`, `join`, `leave`
+Methods: `list` (`q`, `member`, `sort`), `search`, `get`, `related`, `members` (`q`), `create`, `join`, `leave`, `requests` (`q`), moderation (`approveMember`, `banMember`, …), `createInvite`
 
 ### r.uploads — Post and chat media
 
@@ -585,6 +615,10 @@ const publicUrl = await r.uploads.uploadMedia({
 failure path; catch once at the UI boundary and tell the user. Do not repeat
 the presign/PUT sequence in application code.
 
+Video: check `const { data } = await r.video.entitlement()` before offering the
+picker (`data.allowed`, `data.reason` 'tier' | 'quota', `data.remainingSeconds`),
+then `r.video.createUpload()`, which runs the same check.
+
 ### r.chat — Messaging
 
 ```typescript
@@ -594,7 +628,9 @@ const { data: group } = await r.chat.createGroup({ name: 'Team', member_ids: ['u
 const { data: msgs } = await r.chat.messages(dm.id, { limit: 50 })
 ```
 
-Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+
+Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 
 ### r.tags
 
@@ -609,10 +645,11 @@ Methods: `list`, `get`, `create`, `delete`
 
 ## Platform Resources
 
-- `r.settings` — User preferences, sessions, password changes, account deletion. With a project-bound key, `getPreferences()` includes app-scoped `content`; persist changes with `updateContent({ show_nsfw?, autoplay_video?, ai_enabled?, default_feed? })`.
+- `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`, `status`, `createPortalSession`
-- `r.notifications` — Push notification token registration/unregistration
+- `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.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)
 - `r.github` — GitHub integration (getRepository, getTree, getFileContent, getCommits, createFromTemplate)
 - `r.deployments` — Deployment management (prefer `r.projects.deploy()` for new projects)
@@ -620,7 +657,7 @@ Methods: `list`, `get`, `create`, `delete`
 - `r.email` — Email campaigns, batch sending, and transactional email (`r.email.send({ to, subject, html })`)
 - `r.webhooks` — Register inbound webhook endpoints: `register()`, `list()`, `delete()`. Webhook events execute handler code in project sandbox.
 - `r.jobs` — Scheduled cron jobs: `create({ name, cron, handler_code })`, `list()`, `update()`, `delete()`. Handlers execute in project sandbox on schedule.
-- `r.wallet` — Credits/wallet management
+- `r.wallet` — Wallet, MINDS tokens (`getTokenBalance`, `getTokenLedger`; wei stays a string), USD payouts (`getPayouts`, `startPayoutOnboarding`, `payoutLoginLink`)
 - `r.freeTier` — Free tier limits and status
 
 ```typescript
@@ -629,6 +666,9 @@ if (subscription.active) {
   const { data: portal } = await r.appSubscriptions.createPortalSession({ return_url: 'https://app.example.com/billing' })
   console.log(portal.url)
 }
+// Switch plan in place: preview, then change with the same proration date
+const { data: quote } = await r.appSubscriptions.previewTierChange({ tier: 'pro' })
+await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorationDate })
 ```
 - `r.admin` — Admin operations (user management, stats, network settings); content reports: `listReports({ status? })`, `resolveReport(id)`, `dismissReport(id)` (project-bound keys see only their app's reports)
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
@@ -638,6 +678,7 @@ if (subscription.active) {
 - 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`.
   - 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.
   - 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.
@@ -790,12 +831,15 @@ await r.agents.create({ name: 'Bot', model: 'anthropic/claude-sonnet-4' }) // fa
 await r.agents.create({ name: 'Bot', username: 'bot_1', model: 'anthropic/claude-sonnet-4',
   system_prompt: '...', organization_id: orgId })
 
-// ❌ WRONG: not handling private communities
-await r.communities.get('comm_xxx') // 404 if private and not a member
+// ❌ WRONG: assuming get() always returns the full group
+const { data } = await r.communities.get('comm_xxx')
+data.created_by.name // undefined on a private group you are not in
 
-// ✅ RIGHT
-try { await r.communities.get('comm_xxx') }
-catch (e) { if (e.status === 404) { /* private or doesn't exist */ } }
+// ✅ RIGHT: a private group you're not in is a card (limited: true); hidden or missing is 404
+try {
+  const { data } = await r.communities.get('comm_xxx')
+  if (data.limited) { /* show name + "Request to join" / membership_status 'pending' */ }
+} catch (e) { if (e.status === 404) { /* hidden or doesn't exist */ } }
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.49",
+  "version": "0.7.51",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",