@recursiv/sdk 0.7.52 → 0.7.54

package/dist/resources/discovery.d.ts

@@ -1,9 +1,126 @@
-import type { DiscoveryLayout, Post } from '../types.js';
+import type { HttpClient } from '../client.js';
+import type { DiscoveryLayout, FalloverStep, Post } from '../types.js';
 import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
 export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
+/** What GET /discover/recommendations suggests: members, groups, tags, open-network accounts or World Today stories. */
+export type EntityKind = 'member' | 'group' | 'tag' | 'network_account' | 'story';
+/**
+ * One suggestion. `key` is the entity's id (a uuid), or `<protocol>:<native id>` for an open-network account.
+ * The public display fields depend on the kind: members carry id, username, name, image, bio and
+ * follower_count; groups id, name, slug, image, description and member_count; tags id, name and slug;
+ * open-network accounts protocol, actor, handle, display_name and avatar_url (never a link out); stories id,
+ * headline, kicker, story_kind and edition_date.
+ */
+export interface EntityRecommendation {
+    kind: EntityKind;
+    key: string;
+    /** active: posted in the last 7 days or 4+ times in 30 (for groups, 3+ distinct posters in 30 days); warm: activity in 90 days. */
+    tier: 'active' | 'warm';
+    score: number;
+    /** The entity's share of the requested category, or null for category=all. */
+    share: number | null;
+    last_active_at: string | null;
+    posts_30d: number;
+    /** Distinct posters in 30 days (groups and tags), otherwise null. */
+    authors_30d: number | null;
+    /** Up to three browse categories, largest share first. */
+    categories: Array<{
+        category: string;
+        share: number;
+    }>;
+    [display: string]: unknown;
+}
+export interface EntityRecommendationsParams {
+    kind: EntityKind;
+    /** 'all' (default) or a browse category id. */
+    category?: string;
+    /** 1..50, default 10. */
+    limit?: number;
+    /** A per-session token ([A-Za-z0-9_-], up to 64): the same token keeps the order stable; a new one rotates near-ties. */
+    session?: string;
+    /** Up to 50 keys of the kind to leave out, e.g. open-network accounts the member follows through a connected account. */
+    exclude?: string[];
+}
+export interface EntityRecommendationsResponse {
+    data: EntityRecommendation[];
+    meta: {
+        kind: EntityKind;
+        category: string;
+        as_of: string | null;
+        /** Why the list is empty: serving is off, the key's app is not the one signals are built for, no snapshot yet, the viewer's follows could not be checked, or the key has no app. */
+        reason?: 'disabled' | 'other_app' | 'no_snapshot' | 'viewer_facts_unavailable' | 'no_app';
+        /** Suggestions left out because they are resting for this viewer, and because the viewer follows, joined, blocked or muted them. */
+        resting: number;
+        excluded: number;
+        /** True when the member's own category order lifted suggestions in their first categories. */
+        personalized: boolean;
+    };
+}
+export interface EntityImpressionsInput {
+    kind: EntityKind;
+    /** 1..50 keys of the kind. */
+    keys: string[];
+    /** 'shown' when a suggestion was on screen; 'engaged' on a tap, follow or join. Three showings without a tap rest a suggestion for fourteen days; engaging clears it. */
+    event: 'shown' | 'engaged';
+}
+/** One section of a category surface: bounded, read under its own deadline; empty with a `reason` when it timed out, failed, is off, or the recommender said why. */
+export interface CategorySurfaceSection<T> {
+    items: T[];
+    ms: number;
+    reason?: string;
+}
+/** A radar cluster themed into the category, with up to six members (headline or excerpt and link only). */
+export type CategoryStory = Pick<SocialRadar['clusters'][number], 'id' | 'label' | 'kind' | 'theme' | 'sources' | 'corroboration' | 'laneMix' | 'velocity' | 'media' | 'freshness' | 'score' | 'members'>;
+export interface CategoryClip {
+    id: string;
+    title: string | null;
+    excerpt: string;
+    created_at: string;
+    author: {
+        id: string;
+        username: string | null;
+        name: string;
+        image: string | null;
+    };
+    media: Array<{
+        id: string;
+        url: string;
+        type: string;
+        thumbnail_url: string | null;
+        unplayable?: boolean;
+    }>;
+    engagement: {
+        score: number;
+        like_count: number;
+        reply_count: number;
+        repost_count: number;
+    };
+}
+export interface CategorySurface {
+    category: string;
+    /** When the oldest cached section served (stories, network, clips) was built. */
+    as_of: string;
+    stories: CategorySurfaceSection<CategoryStory>;
+    network: CategorySurfaceSection<SocialPost> & {
+        by_protocol: Record<string, number>;
+    };
+    clips: CategorySurfaceSection<CategoryClip>;
+    people: CategorySurfaceSection<EntityRecommendation>;
+    groups: CategorySurfaceSection<EntityRecommendation>;
+}
+export interface CategorySurfaceResponse {
+    /** Null when the key has no app (meta.reason `no_app`). */
+    data: CategorySurface | null;
+    meta: {
+        category: string;
+        as_of?: string;
+        reason?: 'no_app';
+        personalized: boolean;
+    };
+}
 export interface DiscoveryGroupCandidate {
     id: string;
     name: string;
@@ -157,12 +274,18 @@ export interface DiscoveryFeedPage {
     hasMore: boolean;
     failedSources: string[];
     partialCategories: boolean;
+    /**
+     * The Minds feed's fall-through, once its category feed has ended a stage (the server's
+     * `meta.fallover`): where to read next when this session has no more. Absent until then, and
+     * on servers that predate it.
+     */
+    fallover?: FalloverStep[];
 }
 /** A gallery strip holds up to twelve image posts gathered from the whole page. */
 export declare const GALLERY_MAX_ITEMS = 12;
 /** 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 declare class DiscoveryFeedSession {
     private posts;
     private protocols;
@@ -187,6 +310,15 @@ export declare class DiscoveryFeedSession {
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
+    /**
+     * 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.
+     */
+    private walkTopics;
     private readPage;
     /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
     private radarCluster;
@@ -203,7 +335,40 @@ export declare class DiscoveryResource {
     private posts;
     private protocols;
     private curator?;
-    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined);
+    private http?;
+    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined, http?: Pick<HttpClient, "get" | "post"> | undefined);
+    /**
+     * 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: EntityRecommendationsParams, options?: {
+        retry?: boolean;
+    }): Promise<EntityRecommendationsResponse>;
+    /** Records that suggestions were shown (at most once per half hour counts) or engaged with. */
+    recordImpressions(input: EntityImpressionsInput): Promise<{
+        data: {
+            recorded: number;
+            reason?: 'disabled' | 'other_app' | 'unavailable' | 'no_app';
+        };
+    }>;
+    /**
+     * A category's surface in one call: the modules All has, scoped to the category. `stories` (radar
+     * clusters themed into it), `network` (open-network posts judged into it, newest first) and `clips`
+     * (public video posts among its hot window) are shared per app and category (refreshed after 30 s, kept up to 300 s, so a copy
+     * may be that old) and filtered for the viewer on every call: the cached safety verdicts and the promotion term list again, the
+     * viewer's blocks and mutes, and for stories and network the member's own hidden sources. `people` and `groups` are the
+     * viewer's suggestions in it. A section that timed out, failed or is off is empty
+     * with a `reason` and never delays the others. The posts feed itself is `posts.list({ category })`,
+     * whose pages carry `meta.next` and `meta.fallover`.
+     */
+    category(params: {
+        category: string;
+        session?: string;
+    }, options?: {
+        retry?: boolean;
+    }): Promise<CategorySurfaceResponse>;
     /**
      * 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

package/dist/resources/discovery.js

@@ -8,6 +8,30 @@ 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;
+/**
+ * A topic page the server answered from its open-network source index (`sourceIndex`): in a category, a
+ * topic that is gone or holds nothing in it is served the network's indexed posts in the category, which
+ * are the same for every such topic. While the provider has more of the topic the page carries the
+ * provider's own cursor, which the walk keeps like any other; a topic that is gone or ended carries an
+ * `idx:tf:` cursor, the one index stream of the network. So a walk starts that stream at most once per
+ * session (a second start would re-read what it already showed), and an index page that shows nothing
+ * new counts as an empty topic.
+ */
+const INDEX_CURSOR = 'idx:tf:';
 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 +140,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;
@@ -174,6 +198,9 @@ export class DiscoveryFeedSession {
             if (stream.cursor)
                 stream.used = [...stream.used, stream.cursor].slice(-32);
             stream.cursor = next;
+            // A category feed that ended a stage says where to go next; kept on the stream and reported on every page from here.
+            if (Array.isArray(response.meta.fallover))
+                stream.fallover = response.meta.fallover;
             return { items: response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post })),
                 layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial' };
         }
@@ -181,23 +208,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');
@@ -206,7 +219,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;
@@ -216,6 +236,61 @@ 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;
+            // A failed read of the network's index stream (the server's index busy, or its safety cache down) ends that
+            // continuation, not the network: the stream may start again from a later topic's page. A provider topic
+            // read that fails any other way than gone is still the network's failure.
+            const indexContinuation = !!topic.cursor?.startsWith(INDEX_CURSOR);
+            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;
+                if (indexContinuation) {
+                    stream.indexStarted = false;
+                    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;
+            // A provider cursor is always kept. An index cursor from a provider page starts the network's one index
+            // stream: queued the first time only, since every later start would re-read the same stream from its top.
+            const indexed = !!data.sourceIndex;
+            const startsIndex = !!next?.startsWith(INDEX_CURSOR) && !topic.cursor?.startsWith(INDEX_CURSOR);
+            if (next && next !== topic.cursor && !topic.used.includes(next) && !(startsIndex && stream.indexStarted)) {
+                topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
+                if (startsIndex)
+                    stream.indexStarted = true;
+            }
+            partial ||= data.categoryFilter?.status === 'partial';
+            const items = indexed ? data.items.filter(post => !this.seen.has(key(post.protocol, post.nativeId))) : data.items;
+            if (items.length) {
+                stream.done = !topics.length;
+                return { items: 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.
@@ -326,8 +401,10 @@ export class DiscoveryFeedSession {
             modules.splice(Math.min(2, modules.length), 0, recommendation);
         if (cluster)
             modules.splice(page === 0 ? 0 : Math.min(2, modules.length), 0, this.radarModule(page, cluster, clusterItems));
+        const fallover = this.streams.find(stream => stream.protocol === 'minds')?.fallover;
         return { modules, hasMore: this.streams.some(stream => !stream.done && !stream.failed),
-            failedSources: this.streams.filter(stream => stream.failed).map(stream => stream.protocol), partialCategories: reads.some(read => read.partial) };
+            failedSources: this.streams.filter(stream => stream.failed).map(stream => stream.protocol), partialCategories: reads.some(read => read.partial),
+            ...(fallover ? { fallover } : {}) };
     }
     /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
     async radarCluster(page) {
@@ -466,10 +543,45 @@ export class DiscoveryResource {
     posts;
     protocols;
     curator;
-    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 category's surface in one call: the modules All has, scoped to the category. `stories` (radar
+     * clusters themed into it), `network` (open-network posts judged into it, newest first) and `clips`
+     * (public video posts among its hot window) are shared per app and category (refreshed after 30 s, kept up to 300 s, so a copy
+     * may be that old) and filtered for the viewer on every call: the cached safety verdicts and the promotion term list again, the
+     * viewer's blocks and mutes, and for stories and network the member's own hidden sources. `people` and `groups` are the
+     * viewer's suggestions in it. A section that timed out, failed or is off is empty
+     * with a `reason` and never delays the others. The posts feed itself is `posts.list({ category })`,
+     * whose pages carry `meta.next` and `meta.fallover`.
+     */
+    category(params, options) {
+        if (!this.http)
+            throw new Error('category needs the HTTP client');
+        return this.http.get('/discover/category', params, options);
     }
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a

package/dist/resources/human-input.js

@@ -18,7 +18,8 @@ export class HumanInputResource {
     }
     /** Raise a blocking question and notify the human wherever they are. */
     request(input) {
-        return this.client.post('/human-input', input);
+        // This write is not idempotent. A lost response must not replay the ask.
+        return this.client.post('/human-input', input, { retry: false });
     }
     /** Has the human answered yet? */
     answers(conversationId) {

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,5 +1,6 @@
 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`. */
@@ -33,6 +34,19 @@ export declare class PostsResource {
     }>;
     /** 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;
@@ -48,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

@@ -20,6 +20,22 @@ export class PostsResource {
     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);
@@ -44,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);
     }