@recursiv/sdk 0.7.51 → 0.7.53

package/dist/resources/discovery.js

@@ -8,6 +8,20 @@ const RADAR_MAX_MEMBERS = 12;
 const RADAR_MAX_MINDS_READS = 4;
 /** A discovery page holds its own deadline: a retried 5xx from one provider only makes the whole page wait. */
 const NO_RETRY = { retry: false };
+/**
+ * The provider no longer lists the topic (`trend_unavailable`): that topic's end, never a network
+ * failure. Matched on the server's code, which every SDK error carries: any other 404 on the route
+ * (`unsupported_protocol`, a missing route) is the network failing, and still fails the source.
+ */
+const isGone = (error) => typeof error === 'object' && error !== null && error.code === 'trend_unavailable';
+/**
+ * Topic pages one read of a topics network walks past when each is gone or carries nothing in the
+ * category, so a page reaches a topic that carries posts. Live (2026-09-26, Bluesky, news) 21 of 25
+ * topics answered no posts in the category; one topic a read left the network out of most pages.
+ */
+const TOPIC_WALK = 5;
+/** The walk starts no topic read after this long: well inside the page deadline, so it commits its progress rather than timing the network out. */
+const TOPIC_WALK_MS = 8000;
 const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
 const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 512;
 function recommendationItem(kind, candidate) {
@@ -116,7 +130,7 @@ function windowLayout(layout, index) {
 }
 /** Per-viewer feed session. Create a new session when user, app, category or
  * source changes. All reads retain existing server authorization/moderation.
- * At most four requests per page; providers fail independently. */
+ * At most four sources per page (a topics network's read walks up to TOPIC_WALK topic pages); providers fail independently. */
 export class DiscoveryFeedSession {
     posts;
     protocols;
@@ -160,6 +174,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
@@ -178,23 +195,9 @@ export class DiscoveryFeedSession {
             if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(post => post.protocol !== stream.protocol || post.author.protocol !== stream.protocol))
                 throw new Error('Invalid discovery source response');
         };
-        if (stream.topics) {
-            const topic = stream.topics[0];
-            if (!topic) {
-                stream.done = true;
-                return { items: [], layout: ordinary, partial: false };
-            }
-            const { data } = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY);
-            validatePosts(data);
-            if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
-                throw new Error('Invalid discovery topic');
-            const next = data.cursor;
-            stream.topics.shift();
-            if (next && next !== topic.cursor && !topic.used.includes(next))
-                stream.topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
-            stream.done = !stream.topics.length;
-            return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
-        }
+        const started = Date.now();
+        if (stream.topics)
+            return this.walkTopics(stream, params, validatePosts, false, started);
         const { data } = await this.protocols.getPublicTrends({ ...params, protocol: stream.protocol, cursor: stream.cursor, includePreviews: true }, NO_RETRY);
         if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(item => item.protocol !== stream.protocol))
             throw new Error('Invalid discovery source response');
@@ -203,7 +206,14 @@ export class DiscoveryFeedSession {
                 throw new Error('Invalid discovery preview');
             stream.topics = [...new Set(data.items.map(topic => topic.nativeId))].map(topic => ({ topic, used: [] }));
             stream.done = !stream.topics.length;
-            return { items: data.items.flatMap(topic => !this.category && topic.preview ? [{ key: key(topic.preview.protocol, topic.preview.nativeId), kind: 'social', post: topic.preview }] : []), layout: ordinary, partial: data.categoryFilter?.status === 'partial' };
+            const partial = data.categoryFilter?.status === 'partial';
+            // Outside a category the catalog's previews are this page. In a category a preview is not
+            // judged to be in it, so the catalog carries no card: the read walks into its topics now,
+            // not a round later, so the network's first page in a category is not empty by design.
+            const previews = data.items.flatMap(topic => !this.category && topic.preview ? [{ key: key(topic.preview.protocol, topic.preview.nativeId), kind: 'social', post: topic.preview }] : []);
+            if (previews.length || stream.done)
+                return { items: previews, layout: ordinary, partial };
+            return this.walkTopics(stream, params, validatePosts, partial, started);
         }
         validatePosts(data);
         const next = data.cursor ?? undefined;
@@ -213,6 +223,42 @@ export class DiscoveryFeedSession {
         stream.cursor = next;
         return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
     }
+    /**
+     * One read of a topics network: the next topic page that carries posts. A topic the provider no
+     * longer lists (Bluesky rotates its trends between the catalog read and the walk through it) is
+     * that topic's end, not the network's failure; a topic page with nothing in the category is
+     * walked past too, and its continuation kept, so the page reaches a topic that carries posts
+     * instead of spending a round on each empty one. Bounded by TOPIC_WALK reads and TOPIC_WALK_MS;
+     * a walk that stops short has moved the stream on, and the next read continues from there.
+     */
+    async walkTopics(stream, params, validatePosts, partial, started) {
+        const topics = stream.topics;
+        for (let reads = 0; reads < TOPIC_WALK && Date.now() - started < TOPIC_WALK_MS; reads++) {
+            const topic = topics[0];
+            if (!topic)
+                break;
+            const response = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY)
+                .catch((error) => { if (isGone(error))
+                return null; throw error; });
+            topics.shift();
+            if (!response)
+                continue;
+            const { data } = response;
+            validatePosts(data);
+            if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
+                throw new Error('Invalid discovery topic');
+            const next = data.cursor;
+            if (next && next !== topic.cursor && !topic.used.includes(next))
+                topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
+            partial ||= data.categoryFilter?.status === 'partial';
+            if (data.items.length) {
+                stream.done = !topics.length;
+                return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial };
+            }
+        }
+        stream.done = !topics.length;
+        return { items: [], layout: ordinary, partial };
+    }
     async readPage() {
         // The radar is one small snapshot read: start it with the page, not after the slowest provider,
         // and start the lead story's member reads the moment the snapshot names it.
@@ -462,9 +508,54 @@ export class DiscoveryFeedSession {
 export class DiscoveryResource {
     posts;
     protocols;
-    constructor(posts, protocols) {
+    curator;
+    http;
+    constructor(posts, protocols, curator, http) {
         this.posts = posts;
         this.protocols = protocols;
+        this.curator = curator;
+        this.http = http;
+    }
+    /**
+     * Suggestions for the signed-in viewer from the app's one recommender: active or warm members, groups
+     * with several posters, tags used by several people, open-network accounts or stories, overall or in one
+     * browse category. What the viewer follows, joined, blocked or muted is left out, and so is anything
+     * resting for them. Call `recordImpressions` when suggestions are actually on screen and when one is tapped.
+     */
+    recommendations(params, options) {
+        if (!this.http)
+            throw new Error('recommendations needs the HTTP client');
+        const { exclude, ...rest } = params;
+        return this.http.get('/discover/recommendations', { ...rest, exclude: exclude?.length ? exclude.join(',') : undefined }, options);
+    }
+    /** Records that suggestions were shown (at most once per half hour counts) or engaged with. */
+    recordImpressions(input) {
+        if (!this.http)
+            throw new Error('recordImpressions needs the HTTP client');
+        return this.http.post('/discover/impressions', input);
+    }
+    /**
+     * 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/link-preview.d.ts

@@ -9,7 +9,13 @@ export interface LinkPreview {
     siteName: string | null;
 }
 export interface LinkPreviewResponse {
-    data: LinkPreview;
+    /**
+     * The preview, or null when the link cannot be previewed: the page refused a
+     * server (a private repository, a paywall or bot wall), is not HTML, or could
+     * not be reached. Show the plain link. Servers before this change answered
+     * 422 for these links instead, so treat that rejection the same way.
+     */
+    data: LinkPreview | null;
     cached?: boolean;
 }
 export declare class LinkPreviewResource {
@@ -17,9 +23,10 @@ export declare class LinkPreviewResource {
     constructor(client: HttpClient);
     /**
      * Fetch Open Graph / Twitter card metadata for a public URL. Cached
-     * server-side so repeated lookups are cheap. No auth required — the
-     * endpoint is intentionally public so unauthenticated UIs can render
-     * link previews.
+     * server-side so repeated lookups are cheap, including links that have no
+     * preview (`data: null`). No auth required — the endpoint is intentionally
+     * public so unauthenticated UIs can render link previews. A URL that is not
+     * http(s), or points at a private or internal address, still rejects (422).
      */
     get(url: string): Promise<LinkPreviewResponse>;
 }

package/dist/resources/link-preview.js

@@ -5,9 +5,10 @@ export class LinkPreviewResource {
     }
     /**
      * Fetch Open Graph / Twitter card metadata for a public URL. Cached
-     * server-side so repeated lookups are cheap. No auth required — the
-     * endpoint is intentionally public so unauthenticated UIs can render
-     * link previews.
+     * server-side so repeated lookups are cheap, including links that have no
+     * preview (`data: null`). No auth required — the endpoint is intentionally
+     * public so unauthenticated UIs can render link previews. A URL that is not
+     * http(s), or points at a private or internal address, still rejects (422).
      */
     get(url) {
         return this.client.get('/link-preview', { url });

package/dist/resources/notifications.d.ts

@@ -7,6 +7,12 @@ export interface NotificationActor {
     username: string | null;
     image: string | null;
     is_ai: boolean | null;
+    /**
+     * Follow rows only: whether the viewer already follows this person, so
+     * Follow back can render without reading the follow set. Absent on other
+     * rows and from servers older than this field.
+     */
+    viewer_follows?: boolean;
 }
 /**
  * The post a notification references, as it reads NOW, with the viewer's own
@@ -15,7 +21,18 @@ export interface NotificationActor {
  */
 export interface NotificationPostPreview {
     id: string;
+    /**
+     * The post's words as plain text (no Markdown or HTML marks; a link reads as
+     * its label and a bare URL as its site), up to 140 characters. A longer post
+     * is cut at the last whole word and ends in "…". Show it as it is.
+     */
     excerpt: string | null;
+    /**
+     * True when `excerpt` is a cut of a longer post. Use this rather than the
+     * excerpt's length to decide whether there is more to read. Absent from
+     * servers older than this field.
+     */
+    excerpt_truncated?: boolean;
     media_url: string | null;
     media_type: string | null;
     reactions_count?: number;
@@ -24,7 +41,10 @@ export interface NotificationPostPreview {
     downvote_count?: number;
     /** The viewer's own reaction on this post ('upvote', 'downvote', ...), if any. */
     user_reaction?: string | null;
+    /** Stored replies a reader can open. */
     reply_count?: number;
+    /** A legacy import's comment count; none of those comments are stored as replies. */
+    reply_count_external?: number;
     unique_commenters?: number;
     reposts_count?: number;
     /** Id of the viewer's own repost of this post; delete it to undo the repost. */
@@ -43,6 +63,12 @@ export interface Notification {
     read_at: string | null;
     /** For `post_reaction` rows: which reaction ('upvote', 'downvote', ...). Null otherwise or on older rows. */
     reaction_type?: string | null;
+    /**
+     * For `agent_needs_input` rows: whether you have written in the agent's
+     * thread since it asked, which is what answers an ask. The title then reads
+     * "You answered <agent>". Null on other rows; absent from older servers.
+     */
+    answered?: boolean | null;
     actor?: NotificationActor | null;
     post_preview?: NotificationPostPreview | null;
 }

package/dist/resources/posts.d.ts

@@ -1,17 +1,52 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, DeleteResponse, Post, PostDetail, CreatePostInput, CreatedPost, UpdatePostInput, ListPostsParams, ListPostRepliesParams, PostRepliesPage, SearchPostsParams, ReactionType } from '../types.js';
+import type { PaginatedResponse, SingleResponse, DeleteResponse, Post, PostDetail, CreatePostInput, CreatedPost, UpdatePostInput, ListPostsParams, ListPostRepliesParams, PostRepliesPage, SearchPostsParams, SearchPostsResponse, ReactionType } from '../types.js';
+import type { BookmarkedPost, BookmarksPage, SavedBookmark, UnsavedBookmark } from './bookmarks.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>>;
+    /**
+     * The caller's saved posts in this app, newest saved first, each with `bookmarked_at`. Page on
+     * `meta.next_cursor` (a page can be short while it skips posts the member can no longer read).
+     * Same as `bookmarks.posts`; 503 `bookmarks_unavailable` where synced bookmarks are not available.
+     */
+    bookmarked(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<BookmarksPage<BookmarkedPost>>;
+    /** Save a post to the caller's synced bookmarks (idempotent). A bare repost is saved as its original: see `post_id`. */
+    bookmark(postId: string): Promise<SingleResponse<SavedBookmark>>;
+    /** Remove a post from the caller's synced bookmarks (idempotent). Pass the `post_id` its save returned. */
+    unbookmark(postId: string): Promise<SingleResponse<UnsavedBookmark>>;
     /** Posts similar to this one (embedding neighbours), in the app's scope. */
     similar(id: string, params?: {
         limit?: number;
@@ -27,8 +62,12 @@ export declare class PostsResource {
     update(id: string, input: UpdatePostInput): Promise<SingleResponse<CreatedPost>>;
     /** Delete a post */
     delete(id: string): Promise<DeleteResponse>;
-    /** Search posts by text query */
-    search(params: SearchPostsParams): Promise<PaginatedResponse<Post>>;
+    /**
+     * Search posts by text query. Relevance (the default) ranks relevance x recency x engagement through
+     * the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as
+     * `cursor`; the first relevance page carries `latest`, the last page `fall_over` (SearchPostsResponse).
+     */
+    search(params: SearchPostsParams): Promise<SearchPostsResponse>;
     /** Add or update a reaction on a post */
     react(postId: string, type: ReactionType): Promise<SingleResponse<{
         success: true;

package/dist/resources/posts.js

@@ -7,14 +7,35 @@ 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) {
         return this.list({ ...params, liked: true });
     }
+    /**
+     * The caller's saved posts in this app, newest saved first, each with `bookmarked_at`. Page on
+     * `meta.next_cursor` (a page can be short while it skips posts the member can no longer read).
+     * Same as `bookmarks.posts`; 503 `bookmarks_unavailable` where synced bookmarks are not available.
+     */
+    bookmarked(params) {
+        return this.client.get('/posts', { bookmarked: true, ...params });
+    }
+    /** Save a post to the caller's synced bookmarks (idempotent). A bare repost is saved as its original: see `post_id`. */
+    bookmark(postId) {
+        return this.client.put('/bookmarks', { kind: 'post', post_id: postId });
+    }
+    /** Remove a post from the caller's synced bookmarks (idempotent). Pass the `post_id` its save returned. */
+    unbookmark(postId) {
+        return this.client.delete(`/bookmarks/${encodeURIComponent(`post:${postId}`)}`);
+    }
     /** Posts similar to this one (embedding neighbours), in the app's scope. */
     similar(id, params) {
         return this.client.get(`/posts/${encodeURIComponent(id)}/similar`, params);
@@ -39,7 +60,11 @@ export class PostsResource {
     delete(id) {
         return this.client.delete(`/posts/${id}`);
     }
-    /** Search posts by text query */
+    /**
+     * Search posts by text query. Relevance (the default) ranks relevance x recency x engagement through
+     * the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as
+     * `cursor`; the first relevance page carries `latest`, the last page `fall_over` (SearchPostsResponse).
+     */
     search(params) {
         return this.client.get('/posts/search', params);
     }

package/dist/resources/profiles.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, SuccessResponse, Profile, ProfileDetail, ProfileMe, LeaderboardEntry, UpdateProfileInput, SearchProfilesParams, SearchMentionsParams, MentionCandidate, FollowListProfile, BlockedProfile, MutedProfile, ModerationListParams, ViewerRelationship } from '../types.js';
+import type { PaginatedResponse, SingleResponse, SuccessResponse, Profile, ProfileDetail, ProfileMe, LeaderboardEntry, UpdateProfileInput, SearchProfilesParams, ProfileSearchResult, SearchMentionsParams, MentionCandidate, FollowListParams, FollowListProfile, BlockedProfile, MutedProfile, ModerationListParams, ViewerRelationship } from '../types.js';
 export declare class ProfilesResource {
     private client;
     constructor(client: HttpClient);
@@ -15,14 +15,25 @@ export declare class ProfilesResource {
     /** Get a user by username */
     getByUsername(username: string): Promise<SingleResponse<ProfileDetail>>;
     /** Search users by name or username */
-    search(params: SearchProfilesParams): Promise<PaginatedResponse<Profile>>;
+    /**
+     * Search accounts by name or handle, ranked by match x ln(1 + followers + min(posts, 100)) (doubled for an
+     * official account): empties last and marked `empty`, the official ones `verified`. Every page is
+     * a slice of one ranked pool of 200; past it `has_more` is false.
+     */
+    search(params: SearchProfilesParams): Promise<PaginatedResponse<ProfileSearchResult>>;
     /**
      * Accounts to @mention: people and agents on the caller's network, the
      * caller's follows first. Unlike `search`, this includes agents the app may
      * discover (an agent answers when mentioned); another member's personal AI
      * is never offered.
+     *
+     * A search that runs over its 2 s budget answers 503 with Retry-After. A
+     * type-ahead has its own deadline, so pass `{ retry: false }` to get that
+     * answer at once instead of waiting through retries.
      */
-    mentions(params: SearchMentionsParams): Promise<PaginatedResponse<MentionCandidate>>;
+    mentions(params: SearchMentionsParams, options?: {
+        retry?: boolean;
+    }): Promise<PaginatedResponse<MentionCandidate>>;
     /** Update own profile */
     update(input: UpdateProfileInput): Promise<SingleResponse<Profile>>;
     /** Follow a user */
@@ -30,18 +41,16 @@ export declare class ProfilesResource {
     /** Unfollow a user */
     unfollow(userId: string): Promise<SuccessResponse>;
     /**
-     * List a user's followers. Each row carries the caller's relationship with
-     * it (`is_following`, `follows_you`), so a Follow button needs no second read.
+     * List a user's followers, newest follow first once the server's database
+     * has the follow-list order indexes (until then, in the order it reads
+     * them). Each row carries the caller's relationship with it (`is_following`,
+     * `follows_you`), so a Follow button needs no second read. `search` narrows
+     * the whole list to accounts whose name or handle contains it (at most 200
+     * characters); page the matches with `limit` and `offset`.
      */
-    followers(userId: string, params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<FollowListProfile>>;
-    /** List who a user follows, each row with the caller's relationship with it. */
-    following(userId: string, params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<FollowListProfile>>;
+    followers(userId: string, params?: FollowListParams): Promise<PaginatedResponse<FollowListProfile>>;
+    /** List who a user follows, in the order `followers` uses, each row with the caller's relationship with it; `search` as on `followers`. */
+    following(userId: string, params?: FollowListParams): Promise<PaginatedResponse<FollowListProfile>>;
     /**
      * The caller's whole follow set as ids, up to 5000 per page (default 1000).
      * Answers what `isFollowing` answers, for every account at once. Pass

package/dist/resources/profiles.js

@@ -20,6 +20,11 @@ export class ProfilesResource {
         return this.client.get(`/profiles/by-username/${username}`);
     }
     /** Search users by name or username */
+    /**
+     * Search accounts by name or handle, ranked by match x ln(1 + followers + min(posts, 100)) (doubled for an
+     * official account): empties last and marked `empty`, the official ones `verified`. Every page is
+     * a slice of one ranked pool of 200; past it `has_more` is false.
+     */
     search(params) {
         return this.client.get('/profiles/search', params);
     }
@@ -28,9 +33,13 @@ export class ProfilesResource {
      * caller's follows first. Unlike `search`, this includes agents the app may
      * discover (an agent answers when mentioned); another member's personal AI
      * is never offered.
+     *
+     * A search that runs over its 2 s budget answers 503 with Retry-After. A
+     * type-ahead has its own deadline, so pass `{ retry: false }` to get that
+     * answer at once instead of waiting through retries.
      */
-    mentions(params) {
-        return this.client.get('/profiles/mentions', params);
+    mentions(params, options) {
+        return this.client.get('/profiles/mentions', params, options);
     }
     /** Update own profile */
     update(input) {
@@ -45,13 +54,17 @@ export class ProfilesResource {
         return this.client.delete(`/profiles/${userId}/follow`);
     }
     /**
-     * List a user's followers. Each row carries the caller's relationship with
-     * it (`is_following`, `follows_you`), so a Follow button needs no second read.
+     * List a user's followers, newest follow first once the server's database
+     * has the follow-list order indexes (until then, in the order it reads
+     * them). Each row carries the caller's relationship with it (`is_following`,
+     * `follows_you`), so a Follow button needs no second read. `search` narrows
+     * the whole list to accounts whose name or handle contains it (at most 200
+     * characters); page the matches with `limit` and `offset`.
      */
     followers(userId, params) {
         return this.client.get(`/profiles/${userId}/followers`, params);
     }
-    /** List who a user follows, each row with the caller's relationship with it. */
+    /** List who a user follows, in the order `followers` uses, each row with the caller's relationship with it; `search` as on `followers`. */
     following(userId, params) {
         return this.client.get(`/profiles/${userId}/following`, params);
     }