@recursiv/sdk 0.7.53 → 0.7.54

package/README.md

@@ -675,6 +675,35 @@ what the viewer follows, joined, blocked or muted, and says why a list is empty
 showings without a tap rest a suggestion for fourteen days, and engaging clears it.
 Keep one `session` token per app session so a rail does not reshuffle on every render.
 
+A category feed never ends at an empty page. `sdk.posts.list({ category, sort: 'hot' })`
+(or `score`, or the default chronological order) pages the window of the category's
+newest judged posts, then continues by keyset through the whole indexed
+history: every page's `meta.next` is `{ offset }`, `{ cursor }` or `null`, and when a
+stage ends `meta.fallover` lists where to go, in order: `category_older` (the keyset
+cursor `next` also carries), `category_network` (the same category on the open
+networks), the member's next categories (`via` names the order they came from), `for_you`
+and `all`. A `DiscoveryFeedSession` follows the cursor itself and reports the Minds
+feed's `fallover` on its pages. `sdk.discovery.category({ category, session? })` answers a
+category's surface in one call: `stories`, `network` and `clips` (each shared per app and
+category, refreshed after 30 s, kept up to 300 s and warmed as the warmer reaches the category, then filtered for the viewer on every call: the cached safety verdicts of story members, network posts and clips again, the term list, the viewer's blocks and mutes over clips, and the member's own hidden sources over network posts and story members) and the
+viewer's `people` and `groups`; a section that timed out, failed or is off is empty with a
+`reason` for that request only (a failure is never cached, so asking again retries it), and one this
+key may not read is empty with `refused` (`stories` and `network` need the member's own app
+key with `users:read`; `people` and `groups` need `users:read`). In a category, a Bluesky
+topic the provider no longer lists, or whose feed holds nothing in the category, is served
+the network's indexed posts in it (`sourceIndex.reason` of `gone` or `empty`). While the
+provider has more of the topic the page's cursor is the provider's own, so the topic's
+deeper pages are still read; once it has none, or the topic is gone, the cursor is an
+`idx:tf:` one that continues in the index. When the index cannot answer (busy, or its safety
+cache unreadable), the page is what the provider answered: the empty page with its own
+cursor, or the gone topic's 404; only an `idx:tf:` page answers 503 `unavailable`, and that
+ends the index continuation, not the network. The app contract: a `trend_unavailable` 404,
+an empty topic page or a failed `idx:tf:` page never disables a network for the session;
+move to the next topic, keep every provider continuation, start the `idx:tf:` stream once
+per network and session (every such topic answers the same index stream; after a failed
+page it may start again), and pass cursors back unchanged. `DiscoveryFeedSession` does
+this for you.
+
 `sdk.posts.categories()` answers the app's categories in the order this member
 should see them. `meta.order` is `personal`, `popular` or `static`; `meta.reason`
 says why an answer is not personal (`low_signal`, `deadline`, `requested`,

package/dist/index.d.ts

@@ -147,7 +147,7 @@ export { HttpClient } from './client.js';
 export { RealtimeClient } from './realtime.js';
 export type { RealtimeConnectOptions } from './realtime.js';
 export { AuthResource } from './resources/auth.js';
-export type { AuthSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, } from './resources/auth.js';
+export type { AuthSession, CurrentSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, } from './resources/auth.js';
 export { PostsResource } from './resources/posts.js';
 export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';

package/dist/resources/auth.d.ts

@@ -8,6 +8,20 @@ export interface AuthSession {
         image: string | null;
     };
 }
+/**
+ * What `getSession` answers: the account, and which of its sessions the token
+ * is. `session.id` is the id `settings.listSessions()` lists that session
+ * under. A client that authenticates with an API key gets `is_current: false`
+ * on every listed row (a key belongs to no session), so it matches this id to
+ * mark its own device.
+ */
+export interface CurrentSession extends AuthSession {
+    /** Null only when the server's answer names no session row. */
+    session: {
+        id: string;
+        expiresAt: string | null;
+    } | null;
+}
 export interface SignUpInput {
     email: string;
     password: string;
@@ -275,10 +289,10 @@ export declare class AuthResource {
         success: true;
     }>;
     /**
-     * Get current session info using a session token.
-     * Returns null if the session is invalid or expired.
+     * Get current session info using a session token: the account, and the
+     * session's id and expiry. Returns null if the session is invalid or expired.
      */
-    getSession(sessionToken: string): Promise<AuthSession | null>;
+    getSession(sessionToken: string): Promise<CurrentSession | null>;
     /**
      * Sign out (invalidate session).
      */

package/dist/resources/auth.js

@@ -596,8 +596,8 @@ export class AuthResource {
         return { success: true };
     }
     /**
-     * Get current session info using a session token.
-     * Returns null if the session is invalid or expired.
+     * Get current session info using a session token: the account, and the
+     * session's id and expiry. Returns null if the session is invalid or expired.
      */
     async getSession(sessionToken) {
         const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/get-session`, {
@@ -612,6 +612,8 @@ export class AuthResource {
         const data = await res.json();
         if (!data?.user)
             return null;
+        const sessionId = data.session?.id;
+        const expiresAt = data.session?.expiresAt;
         return {
             token: sessionToken,
             user: {
@@ -620,6 +622,9 @@ export class AuthResource {
                 email: data.user.email,
                 image: data.user.image ?? null,
             },
+            session: typeof sessionId === 'string' && sessionId
+                ? { id: sessionId, expiresAt: typeof expiresAt === 'string' ? expiresAt : null }
+                : null,
         };
     }
     /**

package/dist/resources/curator.d.ts

@@ -7,7 +7,7 @@ export type ForYouParams = {
     offset?: number;
     /** The previous page's `meta.next_cursor`: pages a stored ranking, so posts read meanwhile never shift the next page. */
     cursor?: string;
-    /** Adds `meta.discovery` (layouts) and the public safety floor; limit <= 25. */
+    /** Adds `meta.discovery` (layouts); limit <= 25. Every page carries the promotion safety floor, with or without it. */
     discovery?: boolean;
     /** `discover` ranks for Discover: fresher, beyond the member's follows, with their category order. */
     surface?: ForYouSurface;

package/dist/resources/discovery.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { DiscoveryLayout, Post } from '../types.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';
@@ -66,6 +66,61 @@ export interface EntityImpressionsInput {
     /** '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;
@@ -219,6 +274,12 @@ 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;
@@ -292,6 +353,22 @@ export declare class DiscoveryResource {
             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

@@ -22,6 +22,16 @@ const isGone = (error) => typeof error === 'object' && error !== null && error.c
 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) {
@@ -188,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' };
         }
@@ -237,9 +250,20 @@ export class DiscoveryFeedSession {
             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; throw error; });
+                .catch((error) => {
+                if (isGone(error))
+                    return null;
+                if (indexContinuation) {
+                    stream.indexStarted = false;
+                    return null;
+                }
+                throw error;
+            });
             topics.shift();
             if (!response)
                 continue;
@@ -248,12 +272,20 @@ export class DiscoveryFeedSession {
             if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
                 throw new Error('Invalid discovery topic');
             const next = data.cursor;
-            if (next && next !== topic.cursor && !topic.used.includes(next))
+            // 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';
-            if (data.items.length) {
+            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: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial };
+                return { items: items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial };
             }
         }
         stream.done = !topics.length;
@@ -369,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) {
@@ -534,6 +568,21 @@ export class DiscoveryResource {
             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
      * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts

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/profiles.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, SuccessResponse, Profile, ProfileDetail, ProfileMe, LeaderboardEntry, UpdateProfileInput, SearchProfilesParams, ProfileSearchResult, SearchMentionsParams, MentionCandidate, FollowListParams, 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);
@@ -60,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

@@ -76,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

@@ -928,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 {
@@ -1073,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';

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;

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` (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`
+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`
 
 ---
 
@@ -708,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.53",
+  "version": "0.7.54",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",