@recursiv/sdk 0.7.52 → 0.7.54

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, ProfileRelationship } 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
@@ -51,8 +60,12 @@ export declare class ProfilesResource {
         cursor?: string;
         limit?: number;
     }): Promise<PaginatedResponse<string>>;
-    /** The follow relationship with another user in both directions (mutual when both are true). */
-    isFollowing(userId: string): Promise<SingleResponse<ViewerRelationship>>;
+    /**
+     * The caller's relationship with another user: follows in both directions
+     * (mutual when both are true), and whether the caller blocks (`is_blocking`)
+     * or mutes (`is_muting`) them, left out when the server cannot say.
+     */
+    isFollowing(userId: string): Promise<SingleResponse<ProfileRelationship>>;
     /**
      * Block a user. A block is a two-way wall: it severs follows in both
      * directions and hides each side's posts from the other.

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);
     }
@@ -63,7 +76,11 @@ export class ProfilesResource {
     followingIds(params) {
         return this.client.get('/profiles/me/following/ids', params);
     }
-    /** The follow relationship with another user in both directions (mutual when both are true). */
+    /**
+     * The caller's relationship with another user: follows in both directions
+     * (mutual when both are true), and whether the caller blocks (`is_blocking`)
+     * or mutes (`is_muting`) them, left out when the server cannot say.
+     */
     isFollowing(userId) {
         return this.client.get(`/profiles/${userId}/is-following`);
     }

package/dist/resources/protocols.d.ts

@@ -305,6 +305,8 @@ export interface SocialSourceControlDisplay {
     avatarUrl: string | null;
     /** A hidden post's text, at most 140 characters; null for accounts, deleted posts, and moderated posts or authors. */
     excerpt: string | null;
+    /** A hidden ActivityPub post's public reader id, for the conversation read; absent for accounts, other networks and posts observed without one. */
+    readRef?: string;
     observedAt: string;
 }
 export interface SocialSourceControl {
@@ -641,6 +643,8 @@ export interface NativeReplyBatch {
             authorHandle: string;
             text: string;
             textTruncated?: boolean;
+            /** An ActivityPub parent's public reader id, when the reply was prepared with one: pass it to the conversation read. */
+            readRef?: string;
         };
         text: string;
         wireText: string;
@@ -742,7 +746,7 @@ export interface NativeDelegatedReplyHistoryItem {
     createdAt: string;
     text: string;
     textTruncated: boolean;
-    source: Pick<NativeReplyBatch['deliveries'][number]['parent'], 'protocol' | 'nativeId' | 'sourceUrl'>;
+    source: Pick<NativeReplyBatch['deliveries'][number]['parent'], 'protocol' | 'nativeId' | 'sourceUrl' | 'readRef'>;
     deliveries: Array<Pick<NativeReplyBatch['deliveries'][number], 'id' | 'protocol' | 'kind' | 'state' | 'attemptedAt' | 'account' | 'recoverable' | 'replacedBy'> & {
         removalReceipt: NativeReplyRemovalReceipt | null;
     }>;
@@ -751,10 +755,12 @@ export interface NativeNostrReplyResult {
     id: string;
     createdAt: string;
     text: string;
+    /** `readRef`: a linked ActivityPub source's public reader id, for the conversation read (replies saved before it existed have none). */
     source: {
         protocol: SocialSourceRef['protocol'];
         nativeId: string;
         sourceUrl: string;
+        readRef?: string;
     };
     identityId: string;
     pubkey: string;
@@ -922,6 +928,8 @@ export interface SocialProfile {
     followersCount: number | null;
     followingCount: number | null;
     postsCount: number | null;
+    /** Nostr only: the NIP-05 name its domain has confirmed for this key ("lyn@primal.net"); `handle` stays the key. */
+    nip05?: string;
     subscription: SocialSubscription | null;
 }
 export interface SocialSubscription {
@@ -962,6 +970,12 @@ export interface SocialPost {
     replyCount: number | null;
     likeCount: number | null;
     repostCount: number | null;
+    /**
+     * When the counts were read from the source network. Present only on a post a category feed served
+     * from the open-network index, whose copy can be older than the page (the server refreshes counts
+     * older than 15 minutes when the provider answers in time). Absent: the counts are from this read.
+     */
+    countsObservedAt?: string;
     /** Pixel dimensions when the source declares them (Bluesky aspect ratio, Mastodon attachment meta), so a card can take the clip's shape before it loads. */
     media: Array<{
         type: 'image' | 'video';
@@ -1061,6 +1075,20 @@ export interface SocialTrendFeed extends SocialTrendProvenance {
     trend: SocialTrend;
     items: SocialPost[];
     cursor: string | null;
+    /**
+     * Present when the page came from the app's open-network source index instead of the provider:
+     * with a category, a topic the provider no longer lists (`gone`) or whose feed held nothing in the
+     * category (`empty`) is served the network's indexed posts in the category. While the provider has
+     * more of the topic, `cursor` is the provider's own continuation (the topic's deeper pages may hold
+     * the category); once it has none, or the topic is gone, it is an `idx:tf:` cursor that continues in
+     * the index (`cursor`), the same stream for every topic of the network. The `trend` of a gone topic
+     * carries its id as its title. Pass the cursor back unchanged like any other. When the index cannot
+     * answer, the page is what the provider answered (the empty page with its cursor, or the gone topic's
+     * 404); only an `idx:tf:` page is 503 `unavailable`, which ends that continuation, not the network.
+     */
+    sourceIndex?: SocialTrendSourceIndex & {
+        reason: 'gone' | 'empty' | 'cursor';
+    };
 }
 /** A member of a radar cluster: a headline or excerpt and a link only, never a body. */
 export type SocialRadarSourceKind = 'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds';
@@ -1165,17 +1193,46 @@ export interface SocialRadarPosts {
     builtAt: string | null;
     items: SocialPost[];
 }
+/** A story that has left the radar, as the radar's story archive keeps it (up to 30 days after it was last on the radar). */
+export interface SocialRadarStoryArchive {
+    /** The story as the radar last published it. Articles keep their headline and link; a post is a member by reference only (no `title`). */
+    cluster: Pick<SocialRadarCluster, 'id' | 'label' | 'kind' | 'seed' | 'theme' | 'sources' | 'laneMix'> & {
+        members: Array<Pick<SocialRadarMember, 'kind' | 'key' | 'url' | 'publishedAt' | 'outlet'> & {
+            title?: string;
+        }>;
+    };
+    /** Its open-network posts the app's source index still holds and its source controls and safety floor admit today, in member order. */
+    items: SocialPost[];
+    /** A World Today story's dek: an outlet's own sentence, or the editor model's. */
+    summary: {
+        text: string;
+        origin: 'outlet' | 'editor';
+    } | null;
+    /** The first and the last radar build that published it. */
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /** The index holds none of its open-network posts any more (retention or deletion), so none are listed. */
+    postsExpired: boolean;
+}
 /**
  * One radar story by id, with its social member posts.
- * `live`: on the current radar (`cluster` and `items` present). `aged_out`: on one of the last six
- * radars but not this one. `unknown`: not seen in that window (never existed, or aged out long ago).
+ * `live`: on the current radar (`cluster` and `items` present). `aged_out`: not on this radar, but
+ * held by the story archive (`archive`, and the live story it continues as in `successor`) or seen on
+ * one of the last six radars (`archive` null). `unknown`: in neither (never existed, or left longer ago
+ * than the archive keeps stories). A server without the story archive leaves `archive` and `successor` out.
  */
 export interface SocialRadarStory {
     id: string;
     builtAt: string | null;
     status: 'live' | 'aged_out' | 'unknown';
     cluster: SocialRadarCluster | null;
+    /** The live story's posts; empty otherwise (an archived story's are in `archive.items`). */
     items: SocialPost[];
+    archive?: SocialRadarStoryArchive | null;
+    successor?: {
+        id: string;
+        label: string;
+    } | null;
 }
 /** Read options for callers that hold their own deadline, such as a discovery page. */
 export interface SocialReadOptions {

package/dist/resources/search.d.ts

@@ -0,0 +1,159 @@
+import type { HttpClient } from '../client.js';
+import type { Post } from '../types.js';
+import type { SocialPost } from './protocols.js';
+/** The sections a blended search can answer, in no particular order (see `SearchAnswer.order`). */
+export declare const SEARCH_SECTIONS: readonly ["top_posts", "latest_posts", "open_network", "people", "groups", "topics", "stories", "related", "trending"];
+export type SearchSection = (typeof SEARCH_SECTIONS)[number];
+/** Why a section is absent: out of time, the server was busy, not available for this app, not allowed for this key, or it failed. */
+export type SearchOmitReason = 'timeout' | 'saturated' | 'unavailable' | 'scope' | 'error';
+export interface SearchParams {
+    q: string;
+    /** Items per section, 1-20 (default 6). */
+    limit?: number;
+    /** Only these sections (default: all). */
+    sections?: readonly SearchSection[];
+    /** For organization-bound keys, as on `posts.search`. */
+    organization_id?: string;
+}
+export interface SearchPerson {
+    id: string;
+    name: string | null;
+    username: string | null;
+    image: string | null;
+    is_ai: boolean;
+    /** The query is this account's handle. */
+    exact: boolean;
+    /** The account's public life, what the ranking read: match x ln(1 + followers + min(posts, 100)). */
+    followers_count: number;
+    posts_count: number;
+    /** Nobody follows it and it never posted: listed after every account with a public life, so a client can fold these under "more handles". */
+    empty: boolean;
+    /** An account the operator vouches for: draw the verified badge. */
+    verified: boolean;
+    /** Membership badges, as every embedded author carries them. */
+    plus: boolean;
+    pro: boolean;
+    founder: boolean;
+}
+export interface SearchGroup {
+    id: string;
+    name: string;
+    slug: string;
+    image: string | null;
+    member_count: number;
+    post_count: number;
+    is_member: boolean;
+}
+export type SearchTopic = {
+    kind: 'tag';
+    id: string;
+    name: string;
+    slug: string;
+} | {
+    kind: 'category';
+    id: string;
+    name: string;
+};
+export interface SearchStory {
+    /** Radar cluster id: open it with `protocols` radar story reads. */
+    id: string;
+    label: string;
+    kind: 'breaking' | 'viral' | 'story';
+    theme: string | null;
+    newest_at: string;
+    sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
+    lead: {
+        type: 'image' | 'video';
+        url: string;
+        poster?: string;
+        width?: number;
+        height?: number;
+    } | null;
+    /** Where the words were found: the story's headline, or only one of its members'. */
+    matched: 'label' | 'member';
+}
+export interface SearchRelated {
+    categories: Array<{
+        id: string;
+        name: string;
+        count: number;
+    }>;
+    tags: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        count: number;
+    }>;
+}
+/** One blended search answer. Only answered sections are present; an answered section may be empty. */
+export interface SearchAnswer {
+    query: string;
+    sections: {
+        /** Relevance x recency x engagement, through the promotion safety floor. `has_more`: page further with `posts.search`. */
+        top_posts?: {
+            items: Post[];
+            has_more: boolean;
+        };
+        /** Newest first, never repeating a top post. `partial`: these are the newest of what was read in time. */
+        latest_posts?: {
+            items: Post[];
+            partial: boolean;
+        };
+        open_network?: {
+            items: SocialPost[];
+            withheld: number;
+        };
+        people?: {
+            items: SearchPerson[];
+        };
+        groups?: {
+            items: SearchGroup[];
+        };
+        topics?: {
+            items: SearchTopic[];
+        };
+        stories?: {
+            items: SearchStory[];
+        };
+        /** Categories and topics around the matches. */
+        related?: SearchRelated;
+        /** Present when the answer is thin or old: what is moving in the nearest category. */
+        trending?: {
+            category: {
+                id: string;
+                name: string;
+            } | null;
+            items: Post[];
+        };
+    };
+    /** Answered, non-empty sections in the order to render them. */
+    order: SearchSection[];
+    /** Sections the server left out, and why; the rest of the answer stands. */
+    omitted: Array<{
+        section: SearchSection;
+        reason: SearchOmitReason;
+    }>;
+    /** Fewer than five matches across Minds and the open networks. */
+    few_results: boolean;
+}
+export interface SearchResponse {
+    data: SearchAnswer;
+    meta: {
+        limit: number;
+        elapsed_ms: number | null;
+    };
+}
+export declare class SearchResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Blended search (GET /search): the best and newest posts, open-network posts, people, groups, topics,
+     * news stories, and, so a search never dead-ends, related categories and trending posts. Each section
+     * has its own time budget; one that runs out is listed in `omitted` instead of failing the answer.
+     * Needs `posts:read`. People need `users:read`, groups `communities:read`; open network and stories need
+     * `users:read` and the caller's own app key bound to its network, trending that app key. A section the
+     * key cannot have is listed in `omitted` with reason `scope` or `unavailable`.
+     * Servers before this endpoint answer 404: fall back to `posts.search`.
+     */
+    query(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/resources/search.js

@@ -0,0 +1,21 @@
+/** The sections a blended search can answer, in no particular order (see `SearchAnswer.order`). */
+export const SEARCH_SECTIONS = ['top_posts', 'latest_posts', 'open_network', 'people', 'groups', 'topics', 'stories', 'related', 'trending'];
+export class SearchResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Blended search (GET /search): the best and newest posts, open-network posts, people, groups, topics,
+     * news stories, and, so a search never dead-ends, related categories and trending posts. Each section
+     * has its own time budget; one that runs out is listed in `omitted` instead of failing the answer.
+     * Needs `posts:read`. People need `users:read`, groups `communities:read`; open network and stories need
+     * `users:read` and the caller's own app key bound to its network, trending that app key. A section the
+     * key cannot have is listed in `omitted` with reason `scope` or `unavailable`.
+     * Servers before this endpoint answer 404: fall back to `posts.search`.
+     */
+    query(params) {
+        const { sections, ...rest } = params;
+        return this.client.get('/search', { ...rest, ...(sections && sections.length > 0 ? { sections: sections.join(',') } : {}) });
+    }
+}