@recursiv/sdk 0.7.52 → 0.7.53

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(',') } : {}) });
+    }
+}

package/dist/types.d.ts

@@ -123,9 +123,31 @@ export interface MediaItem {
     id: string;
     url: string;
     type: string;
+    /**
+     * Set on a legacy Minds video whose file is known to be gone (the server probes it): leave it out
+     * of Watch and clip queues and show the poster instead. Absent when the file plays or is unjudged.
+     */
+    unplayable?: boolean;
+}
+/** The group a post is in, as every post payload carries it. */
+export interface PostCommunity {
+    id: string;
+    name: string;
+    slug: string;
+    /**
+     * A post in a group that is not public is for the group's members, and is
+     * never boosted: offer Boost only when this is 'public'.
+     */
+    privacy: 'public' | 'private' | 'hidden';
 }
 export interface Post {
+    /** Stored replies a reader can open. */
     reply_count?: number;
+    /**
+     * The comment count a legacy import brought with the post (minds.com). None of those comments are
+     * stored as replies, so it is not in `reply_count`.
+     */
+    reply_count_external?: number;
     id: string;
     /** Original Minds numeric GUID when this row came from the legacy import. */
     legacy_guid?: string | null;
@@ -133,6 +155,8 @@ export interface Post {
     content_format: 'plain' | 'markdown';
     author: UserSummary;
     community_id: string | null;
+    /** The group the post is in (null when it is in none). */
+    community?: PostCommunity | null;
     organization_id: string | null;
     reply_to_id?: string | null;
     /** Present when this post is an X-style repost — the original post is nested. */
@@ -154,10 +178,25 @@ export interface RepostedPost {
     content_format: 'plain' | 'markdown';
     author: UserSummary | null;
     community_id: string | null;
+    /** The group the original is in (null when it is in none): it decides what the repost card offers. */
+    community?: PostCommunity | null;
     organization_id: string | null;
     tags: Tag[];
     reactions_count: number;
     score: number;
+    /** The original's engagement, as the REST payload sends it for the original itself. */
+    upvote_count?: number;
+    downvote_count?: number;
+    /** The viewer's own reaction on the original ('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, so it is not in `reply_count`. */
+    reply_count_external?: number;
+    unique_commenters?: number;
+    reposts_count?: number;
+    /** Id of the viewer's own repost of the original; delete it to undo the repost. */
+    reposted_by_viewer_id?: string | null;
     media: MediaItem[];
     created_at: string;
 }
@@ -178,6 +217,8 @@ export interface PostReply {
     user_reaction?: string | null;
     /** This reply's own reply count, so its sub-thread can be opened. */
     reply_count?: number;
+    /** A legacy import's comment count for this reply; not stored as replies, so not in `reply_count`. */
+    reply_count_external?: number;
     created_at: string;
 }
 export interface ListPostRepliesParams {
@@ -243,6 +284,11 @@ export interface ListPostsParams extends PaginationParams {
     audience_user_id?: 'me' | string;
     /** Return only posts the authenticated caller has upvoted. */
     liked?: boolean;
+    /**
+     * Return only the caller's saved posts, newest saved first, each with `bookmarked_at`. Takes only `limit`
+     * (at most 50) and `cursor`; see `posts.bookmarked` / `bookmarks.posts`.
+     */
+    bookmarked?: boolean;
 }
 export interface SearchPostsParams extends PaginationParams {
     q: string;
@@ -251,6 +297,42 @@ export interface SearchPostsParams extends PaginationParams {
     sort?: 'relevance' | 'new';
     since?: string;
     until?: string;
+    /**
+     * The `meta.next_cursor` of the previous page. Later relevance pages are slices of the ranking the
+     * first page kept (ten minutes), so nothing is skipped or repeated while it lives; after that the page
+     * continues past the last post's score boundary. Newest-first pages continue by (created_at, id). A
+     * cursor is bound to its search and sort: another's is refused (400 `invalid_cursor`). Without one,
+     * `offset` counts.
+     */
+    cursor?: string;
+}
+/** A way on from the end of a search: newest first, the open networks, or a topic the matches share. */
+export type SearchFallOverLane = {
+    kind: 'new';
+} | {
+    kind: 'open_network';
+} | {
+    kind: 'tag';
+    id: string;
+    name: string;
+    slug: string;
+};
+/** One page of `posts.search`. */
+export interface SearchPostsResponse extends PaginatedResponse<Post> {
+    /**
+     * On the first relevance page: up to three of the newest matches that are not on the page, newest
+     * first, one per author, for a "Latest" strip above the best matches. Absent when there are none, and on later pages.
+     */
+    latest?: Post[];
+    /**
+     * On the last page (`meta.has_more` false): what exists past the end of this search, so a client
+     * can offer a way on instead of a wall. `new` when newest-first goes deeper than the ranking did;
+     * `open_network` when the caller's app can search the open networks; `tag` for the topic the
+     * page's posts share most. May be empty.
+     */
+    fall_over?: {
+        lanes: SearchFallOverLane[];
+    };
 }
 export type QueryParams = Record<string, unknown>;
 export interface CommunityCreator {
@@ -273,6 +355,8 @@ export interface Community {
     post_count?: number;
     /** Whether the caller is an accepted member. Returned by `list` and `search`. */
     is_member?: boolean;
+    /** The caller's role in the group, or null outside it. Returned by `list` and the detail read; a group's creator reads as its owner. */
+    viewer_role?: 'owner' | 'admin' | 'moderator' | 'member' | null;
     created_at: string;
 }
 /** Filters accepted by the communities directory. */
@@ -281,14 +365,36 @@ 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. With `q`, name matches come first and this breaks ties. */
-    sort?: 'members' | 'active' | 'newest';
+    /**
+     * Server-side ordering. With `q`, name matches come first and this breaks ties. `joined` (with
+     * `member: true`) lists the caller's groups by when they joined, newest first.
+     */
+    sort?: 'members' | 'active' | 'newest' | 'joined';
     /**
      * 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;
 }
+/** Which join requests to answer at once: named people (at most 100), or the oldest 100 waiting. */
+export type AnswerJoinRequestsInput = {
+    user_ids: string[];
+} | {
+    all: true;
+};
+/** What a many-at-once answer did: how many it answered, who it skipped, and how many still wait. */
+export interface ApprovedJoinRequests {
+    approved: number;
+    /** Named people with no pending request here: already in, already answered, banned, or never asked. */
+    skipped: string[];
+    /** Pending requests left in the group (bans not counted). */
+    remaining: number;
+}
+export interface DeclinedJoinRequests {
+    declined: number;
+    skipped: string[];
+    remaining: number;
+}
 /** The caller's own membership row in a group, if any. */
 export type CommunityMembershipStatus = 'accepted' | 'pending' | 'invited' | 'banned';
 export interface CommunityDetail extends Community {
@@ -862,6 +968,14 @@ export interface Profile {
 /** A row of a followers/following list: the profile plus the caller's relationship with it. */
 export interface FollowListProfile extends Profile, ViewerRelationship {
 }
+/** Paging and search for a follower or following list (profiles.followers / following). */
+export interface FollowListParams {
+    limit?: number;
+    offset?: number;
+    /** Name or handle, matched anywhere in either (at most 200 characters); a blank term lists everyone. */
+    search?: string;
+    [key: string]: unknown;
+}
 /** An account the caller blocked. */
 export interface BlockedProfile extends Profile {
     blocked_at: string;
@@ -901,10 +1015,24 @@ export interface UpdateProfileInput {
     username?: string;
     bio?: string | null;
     image?: string | null;
+    /** The profile banner as an absolute image URL, or null to remove it (PUT /profiles/me has accepted it since #1867). */
+    banner?: string | null;
 }
 export interface SearchProfilesParams extends PaginationParams {
     q: string;
 }
+/** A row of `profiles.search`: the profile plus what the ranking read (match x ln(1 + followers + min(posts, 100))). */
+export interface ProfileSearchResult extends Profile {
+    followers_count: number;
+    posts_count: number;
+    /** Nobody follows it and it never posted: listed after every account with a public life, for a client to fold under "more handles". */
+    empty: boolean;
+    /** An account the operator vouches for: draw the verified badge. */
+    verified: boolean;
+    plus: boolean;
+    pro: boolean;
+    founder: boolean;
+}
 export interface SearchMentionsParams {
     /** What the member typed after `@` (a leading `@` is ignored). */
     q: string;

package/llm.md

@@ -479,7 +479,7 @@ const { data: rows } = await r.profiles.followers('user_xxx') // each row: is_fo
 await r.profiles.mute('user_xxx') // server hides their posts and reposts of them from your feeds
 ```
 
-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`
+Methods: `list`, `me`, `get`, `getByUsername`, `search` (ranked by match x ln(1 + followers + min(posts, 100)) over one pool of 200, the same for every page; each row (`ProfileSearchResult`) carries `followers_count`, `posts_count`, `empty` (fold empties under "more handles") and `verified` (the accounts the operator names)), `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`
 
 ---
 
@@ -580,7 +580,36 @@ 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` (`sort: 'new'` for newest first), `replies(id, { limit, cursor })` (after `replies_next_cursor` on `get`), `react`, `unreact`
+Methods: `list`, `get`, `create`, `update`, `delete`, `search`, `replies(id, { limit, cursor })` (after `replies_next_cursor` on `get`), `react`, `unreact`, `liked`, `bookmarked`, `bookmark`, `unbookmark`
+
+`search` ranks relevance x recency x engagement (recency falls as a power of age: this month outranks years ago) through the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as `cursor`: later relevance pages are slices of the ranking the first page kept for ten minutes (nothing skipped or repeated while it lives; after that, the page continues past the last post's score boundary), newest-first pages continue by (created_at, id). A cursor is bound to its search and sort: another search's, or the other sort's, is 400 `invalid_cursor`. The first relevance page carries `latest` (up to three of the newest matches not on the page, one per author, for a Latest strip); the last page carries `fall_over.lanes` (`new`, `open_network`, `tag`): draw a way on, not a wall.
+
+### r.bookmarks — Synced saves (per member, per app)
+
+```typescript
+await r.bookmarks.save({ kind: 'post', post_id: post.id })             // idempotent; a bare repost saves its original (see data.post_id)
+await r.bookmarks.save({ kind: 'social', protocol: 'bluesky', native_id: 'at://did:plc:.../app.bsky.feed.post/...',
+  author: { display_name: 'Alice', handle: 'alice.bsky.social' }, snippet: 'hello' })
+await r.bookmarks.save({ kind: 'article', url: 'https://news.example/a', title: 'Headline', outlet: 'Example' })
+const { data: saved, meta } = await r.bookmarks.posts({ limit: 20 })   // = r.posts.bookmarked(); page on meta.next_cursor
+const { data: items } = await r.bookmarks.list({ kind: 'social' })     // open-network posts and articles, as saved snapshots
+const { data: keys } = await r.bookmarks.keys(undefined, { retry: false }) // every key, for a saved-state cache
+const { data: merged } = await r.bookmarks.merge(deviceItems)          // ≤200 per call, each with its own saved_at; idempotent
+await r.bookmarks.unsave(key)                                          // or unsave({ postId }); r.posts.bookmark/unbookmark too
+```
+
+Newest saved first. Pages can be short while they skip posts the member can no longer read: page on `meta.next_cursor`, not length. Needs the member's own app key (else 403 `project_binding_required`). 503 `bookmarks_unavailable` means the server has no synced bookmarks yet: keep saves on the device (pass `{ retry: false }` to the probe so the 503 is not retried).
+
+### r.search
+
+```typescript
+// One query, answered as sections. Each has its own time budget; a slow one is listed in `omitted`.
+const { data: answer } = await r.search.query({ q: 'apple', limit: 6 })
+for (const section of answer.order) render(section, answer.sections[section])
+// top_posts, latest_posts, open_network, people, groups, topics, stories, related, trending
+```
+
+`trending` joins when the answer is thin or old, so a search never dead-ends. `top_posts` is floored as `r.posts.search`'s relevance page is; `people` rows carry `followers_count`, `posts_count`, `empty` and `verified` (see `r.profiles.search`). Page further with `r.posts.search`. Needs `posts:read`; `people` needs `users:read`, `groups` `communities:read`; `open_network` and `stories` need `users:read` plus the caller's own app key on its network, `trending` that app key. What the key cannot have is in `omitted` (`scope` / `unavailable`).
 
 ### r.communities
 
@@ -649,7 +678,7 @@ Methods: `list`, `get`, `create`, `delete`
 - `r.billing` — Usage tracking, checkout sessions, portal sessions, metered billing
 - `r.appSubscriptions` — Project-scoped consumer plans: `checkout` (409 `subscription_exists` when the member already pays), `status`, `createPortalSession({ return_url, flow?: 'cancel' })` (`flow: 'cancel'` opens Stripe's cancel confirmation; 409 `no_subscription` when there is no plan to cancel), `previewTierChange({ tier })`, `changeTier({ tier, proration_date? })` (in-place, prorated, never a second subscription)
 - `r.boosts` — Promoted posts (micro-USD): `create`, `mine`, `balance`, `pause`, `resume`, `cancel`, `recordEvent`; buy credit with `topup({ amount_cents, return_url })` then `confirmTopup(sessionId)` (credits once); admin `listPendingReview`, `review`, `grant`
-- `r.notifications` — The notification stream: `list({ category: 'social' })` (rows carry `actor`, `reaction_type` and a `post_preview` with the viewer's `user_reaction`/`reposted_by_viewer_id` and counts), `unreadCount({ category })` for badges (`const { data } = await r.notifications.unreadCount({ category: 'social' })`), `markAsRead(id)`, `archive(id)` to dismiss, `markAllAsRead(category)` or `markAllAsRead({ category, organization_id })`, plus push token `registerToken`/`unregisterToken`. A push's `data.notificationId` is the row to mark read on tap. DMs are not in the stream.
+- `r.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; an `agent_needs_input` row carries `answered`, true once you have written in the agent's thread since it asked, when its title reads "You answered <agent>"), `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)

package/package.json

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