@recursiv/sdk 0.7.52 → 0.7.54

package/dist/types.d.ts

@@ -22,6 +22,38 @@ export interface DiscoveryLayout {
     theme?: string;
     windows?: DiscoveryLayoutWindow[];
 }
+/**
+ * How to ask for the next page of the same feed: the next offset while the page order is a ranking,
+ * the cursor once the feed pages by keyset (a category feed past its window of newest judged posts), or null when the
+ * feed has no more. On a category feed, `fallover` then says where to go.
+ */
+export type FeedNext = {
+    offset: number;
+} | {
+    cursor: string;
+} | null;
+/**
+ * One step of a category feed's fall-through, in order: the same category's older posts (the keyset
+ * cursor; the same continuation `next` carries), the same category on the open networks, the member's
+ * next categories (`via`: the order they came from, the one `posts.categories()` serves), For you
+ * (signed in), All.
+ */
+export type FalloverStep = {
+    kind: 'category_older';
+    category: string;
+    cursor: string;
+} | {
+    kind: 'category_network';
+    category: string;
+} | {
+    kind: 'category';
+    category: string;
+    via: 'personal' | 'popular' | 'static';
+} | {
+    kind: 'for_you';
+} | {
+    kind: 'all';
+};
 export interface PaginationMeta {
     discovery?: DiscoveryLayout;
     scanned?: number;
@@ -36,6 +68,10 @@ export interface PaginationMeta {
     has_more: boolean;
     /** Pass this as `cursor` for the next page. Absent on offset-only endpoints. */
     next_cursor?: string | null;
+    /** The next page of this feed (offset or cursor), or null at its end. Absent on older servers. */
+    next?: FeedNext;
+    /** Present when a stage of a category feed ends: the ordered steps to follow so scrolling never stops. */
+    fallover?: FalloverStep[];
 }
 export interface PaginatedResponse<T> {
     data: T[];
@@ -99,6 +135,18 @@ export interface ViewerRelationship {
     /** This account follows the caller. */
     follows_you: boolean;
 }
+/**
+ * The caller's relationship with one account (`profiles.isFollowing`): follows
+ * in both directions, and whether the caller blocks or mutes it. A server
+ * from before the moderation fields, or one whose read of them failed, leaves
+ * them out: absent means unknown, never "not blocked".
+ */
+export interface ProfileRelationship extends ViewerRelationship {
+    /** The caller blocks this account. */
+    is_blocking?: boolean;
+    /** The caller mutes this account. */
+    is_muting?: boolean;
+}
 export interface FollowUser extends ViewerRelationship {
     id: string;
     name: string;
@@ -123,9 +171,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 +203,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 +226,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 +265,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 +332,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 +345,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 +403,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 +413,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 +1016,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 +1063,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

@@ -367,7 +367,9 @@ await r.auth.signOut(session.token)
 ```
 
 `getSession(token)` and `signOut(token)` send the explicit session token as
-Bearer auth, with a Cookie fallback for native/server runtimes.
+Bearer auth, with a Cookie fallback for native/server runtimes. `getSession`
+also answers `session: { id, expiresAt }`; an API-key client lists sessions with
+`is_current: false`, so it matches `session.id` to mark its own device.
 
 Methods: `signUp`, `signIn`, `getSession`, `signOut`, `createApiKey`, `signInAndCreateKey`, `signUpAndCreateKey`, `verifyOtpAndCreateKey`
 
@@ -479,7 +481,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` (follows both ways, plus `is_blocking`/`is_muting` when the server knows), `related`, `leaderboard`, `block`, `unblock`, `blocked`, `mute`, `unmute`, `muted`
 
 ---
 
@@ -580,7 +582,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 +680,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)
@@ -679,7 +710,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 - `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
   - Native Nostr: `const { data: preview } = await r.protocols.prepareNativeNostr(identityId, { action: "publish", content: draft })`; review and sign the exact public event, then `submitNativeNostr(identityId, { intent: preview.intent, event, approve: true })`. Preparation/submission never auto-retry. After uncertainty, use `getNativeNostrPost(identityId, preview.postId ?? preview.eventId)` before a user-selected retry of the identical intent/event: deletion checks the original note's `postId`, publication checks `eventId`. Check `nativeNostrAccount()` enablement first; keys stay with the signer. For replies, after `nativeNostrAccount()` advertises `reply_text_note`, use `prepareNativeNostr(identityId, { action: "reply", content: draft, parentId: post.nativeId })`. Review returned parent/root/participants/relay and exact event, sign with the connected client signer, then `submitNativeNostr(identityId, { intent, event, approve: true })`. Requires users:read, posts:read and posts:write. Kind1 public notes only; reply enablement and shared UI/live proof remain pending. Do not inherit arbitrary notification tags or relay hints. Signing mutations never auto-retry; check `getNativeNostrPost(identityId, eventId)` after uncertainty before a user-selected identical-event retry.
   - Hosted Bluesky account on the app's own PDS: `const { data } = await r.protocols.createHostedIdentity({ protocol: 'atproto', handle: 'alice', email })`. Only the label is sent; `data.handle` carries the domain and `data.password` is returned this once, never stored. Never auto-retried. Either the account is finished or it is removed again. 409 `handle_unavailable` = choose another label; 503 `handle_dns_unavailable`/`handle_unresolvable`/`handle_unverified` = operator setup, retry later unchanged.
-  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows.
+  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows. Category depth: `r.posts.list({ category: 'science', sort: 'hot', discovery: true })` pages the hot window by offset and then by keyset (`meta.next` is `{ offset }`, `{ cursor }` or `null`; pass a cursor back as `cursor`); when a stage ends, `meta.fallover` lists the next feeds in order (`category_older`, `category_network`, `category` with `via`, `for_you`, `all`). One call for a category's modules: `const { data } = await r.discovery.category({ category: 'science' })` returns `stories`, `network`, `clips`, `people`, `groups`, each `{ items, ms, reason? }`.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor? })`; render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.
   - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.
   - Lists return `{ data: ProtocolQuarantinedCandidate[], meta: { limit, has_more, next_cursor } }`; use the opaque `next_cursor`, not offset pagination. The API defaults `limit` to 20 and permits at most 50. Details return `{ data: ProtocolQuarantinedCandidate }`. Every candidate has `state: 'quarantined'` and `content_format: 'plain'`; render its bounded `content` as text, respect `content_truncated`, and distinguish upstream `published_at` from local `observed_at` / `created_at`.

package/package.json

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