@recursiv/sdk 0.7.41 → 0.7.44

package/dist/resources/discovery-learning.d.ts

@@ -1,5 +1,6 @@
 import type { DiscoveryLayout } from '../types.js';
-export type DiscoveryPresentation = DiscoveryLayout['presentation'];
+/** Layout presentations plus the recommendation module kinds, so viewers who keep hiding a kind stop seeing it. */
+export type DiscoveryPresentation = DiscoveryLayout['presentation'] | 'groups' | 'people' | 'tags';
 type Counts = {
     views: number;
     engagements: number;

package/dist/resources/discovery-learning.js

@@ -1,6 +1,8 @@
-const names = ['posts', 'visual', 'conversation', 'video'];
+const names = ['posts', 'visual', 'conversation', 'video', 'thread', 'longread', 'groups', 'people', 'tags'];
 const fresh = (now) => ({ version: 1, startedAt: now, layouts: {
         video: { views: 0, engagements: 0, hides: 0 }, posts: { views: 0, engagements: 0, hides: 0 }, visual: { views: 0, engagements: 0, hides: 0 }, conversation: { views: 0, engagements: 0, hides: 0 },
+        thread: { views: 0, engagements: 0, hides: 0 }, longread: { views: 0, engagements: 0, hides: 0 },
+        groups: { views: 0, engagements: 0, hides: 0 }, people: { views: 0, engagements: 0, hides: 0 }, tags: { views: 0, engagements: 0, hides: 0 },
     } });
 /** Local, per-viewer experimental presentation preferences. Stores counts only,
  * never source text, author IDs or inferred traits. It cannot promote content,
@@ -15,10 +17,10 @@ export class DiscoveryLearning {
         const time = now();
         this.value = value?.version === 1 && Number.isFinite(value.startedAt) && value.startedAt <= time
             && time - value.startedAt < 14 * 86400_000 && names.every(name => {
-            const c = value.layouts?.[name];
+            const c = value.layouts?.[name] ?? { views: 0, engagements: 0, hides: 0 };
             return c && [c.views, c.engagements, c.hides].every(n => Number.isSafeInteger(n) && n >= 0 && n <= 10000)
                 && c.engagements <= c.views && c.hides <= c.views;
-        }) ? JSON.parse(JSON.stringify(value)) : fresh(time);
+        }) ? { ...fresh(time), ...JSON.parse(JSON.stringify(value)), layouts: { ...fresh(time).layouts, ...JSON.parse(JSON.stringify(value.layouts)) } } : fresh(time);
     }
     observe(id, presentation, event) {
         if (!names.includes(presentation) || !id || id.length > 8192)

package/dist/resources/discovery.d.ts

@@ -2,7 +2,43 @@ import type { DiscoveryLearning } from './discovery-learning.js';
 import type { DiscoveryLayout, Post } from '../types.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost } from './protocols.js';
-export type DiscoveryItem = {
+export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
+export interface DiscoveryGroupCandidate {
+    id: string;
+    name: string;
+    description?: string | null;
+    image?: string | null;
+    memberCount?: number | null;
+    postCount?: number | null;
+    isMember?: boolean;
+}
+export interface DiscoveryPersonCandidate {
+    id: string;
+    name?: string | null;
+    username?: string | null;
+    image?: string | null;
+    bio?: string | null;
+    followers?: number | null;
+    isFollowing?: boolean;
+}
+export interface DiscoveryTagCandidate {
+    id?: string | null;
+    name: string;
+    slug?: string | null;
+    postCount?: number | null;
+}
+/**
+ * App-supplied candidate lists for recommendation modules. The session decides
+ * when to show one, which kind, dedupes across pages, and drops candidates the
+ * viewer already follows or joined. Each call is bounded to three seconds and a
+ * failure simply means no recommendation on that page.
+ */
+export interface DiscoveryRecommendationSources {
+    groups?: () => Promise<DiscoveryGroupCandidate[]>;
+    people?: () => Promise<DiscoveryPersonCandidate[]>;
+    tags?: () => Promise<DiscoveryTagCandidate[]>;
+}
+export type DiscoveryPostItem = {
     key: string;
     kind: 'minds';
     post: Post;
@@ -11,18 +47,36 @@ export type DiscoveryItem = {
     kind: 'social';
     post: SocialPost;
 };
+export type DiscoveryItem = DiscoveryPostItem | {
+    key: string;
+    kind: 'group';
+    group: DiscoveryGroupCandidate;
+} | {
+    key: string;
+    kind: 'person';
+    person: DiscoveryPersonCandidate;
+} | {
+    key: string;
+    kind: 'tag';
+    tag: DiscoveryTagCandidate;
+};
+export declare const isDiscoveryPost: (item: DiscoveryItem) => item is DiscoveryPostItem;
+/** At most this many candidates per recommendation module. */
+export declare const RECOMMENDATION_MAX_ITEMS = 6;
 /** json-render Spec: values are references to authenticated SDK results, never
  * arbitrary executable components, links, generated text or provider markup. */
 export interface DiscoveryModule {
     id: string;
-    presentation: DiscoveryLayout['presentation'];
+    presentation: DiscoveryLayout['presentation'] | DiscoveryRecommendationKind;
     source: DiscoveryLayout['source'];
+    /** Subject of the featured window (a browse-category id or `mixed`), for specific module copy. */
+    theme?: string;
     items: DiscoveryItem[];
     spec: {
         root: 'module';
         elements: {
             module: {
-                type: 'DiscoveryPosts' | 'DiscoveryGallery' | 'DiscoveryConversation' | 'DiscoveryVideo';
+                type: 'DiscoveryPosts' | 'DiscoveryGallery' | 'DiscoveryConversation' | 'DiscoveryVideo' | 'DiscoveryThread' | 'DiscoveryLongRead' | 'DiscoveryGroups' | 'DiscoveryPeople' | 'DiscoveryTags';
                 props: {
                     itemKeys: string[];
                 };
@@ -37,6 +91,8 @@ export interface DiscoveryFeedPage {
     failedSources: string[];
     partialCategories: boolean;
 }
+/** 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. */
@@ -45,16 +101,18 @@ export declare class DiscoveryFeedSession {
     private protocols;
     private category?;
     private learning?;
+    private recommend?;
     private streams;
     private pending;
     private seen;
     private page;
     private nextSource;
-    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined);
+    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined);
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
     private readPage;
+    private recommendation;
 }
 export declare class DiscoveryResource {
     private posts;
@@ -65,5 +123,6 @@ export declare class DiscoveryResource {
         category?: string;
         source?: string;
         learning?: DiscoveryLearning;
+        recommend?: DiscoveryRecommendationSources;
     }): DiscoveryFeedSession;
 }

package/dist/resources/discovery.js

@@ -1,5 +1,43 @@
+export const isDiscoveryPost = (item) => item.kind === 'minds' || item.kind === 'social';
+/** At most this many candidates per recommendation module. */
+export const RECOMMENDATION_MAX_ITEMS = 6;
+const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 512;
+function recommendationItem(kind, candidate) {
+    if (!candidate || typeof candidate !== 'object')
+        return null;
+    const value = candidate;
+    if (kind === 'groups') {
+        if (!nonEmpty(value.id) || !nonEmpty(value.name) || value.isMember === true)
+            return null;
+        return { key: `rec:group:${value.id}`, kind: 'group', group: value };
+    }
+    if (kind === 'people') {
+        if (!nonEmpty(value.id) || value.isFollowing === true)
+            return null;
+        return { key: `rec:person:${value.id}`, kind: 'person', person: value };
+    }
+    if (!nonEmpty(value.name))
+        return null;
+    return { key: `rec:tag:${(nonEmpty(value.slug) ? value.slug : value.name).toLowerCase()}`, kind: 'tag', tag: value };
+}
 const ordinary = { version: 'discovery-layout-v1', presentation: 'posts', source: 'fallback' };
 const key = (protocol, id) => JSON.stringify([protocol, id]);
+const presentations = new Set(['posts', 'visual', 'conversation', 'video', 'thread', 'longread']);
+/** A gallery strip holds up to twelve image posts gathered from the whole page. */
+export const GALLERY_MAX_ITEMS = 12;
+/** Minimum text for a reading card; mirrors the server's DISCOVERY_LONGREAD_MIN_CHARS. */
+const LONGREAD_MIN_CHARS = 600;
+const quotesAnother = (item) => item.kind === 'social' ? item.post.quote?.state === 'available' : !!item.post.reposted_from && !!item.post.content?.trim();
+const textLength = (item) => item.kind === 'social' ? item.post.text.length : item.post.content?.length ?? 0;
+/** The layout for one response position: its window's judgment when the server provided windows, else the batch-wide one. */
+function windowLayout(layout, index) {
+    const window = layout.windows?.find(candidate => Number.isInteger(candidate.start) && Number.isInteger(candidate.end) && index >= candidate.start && index < candidate.end);
+    if (!window || !presentations.has(window.presentation) || !['jev', 'fallback'].includes(window.source))
+        return layout;
+    const theme = typeof window.theme === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(window.theme) ? window.theme : undefined;
+    return { version: layout.version, presentation: window.presentation, source: window.source, ...(theme ? { theme } : {}) };
+}
 /** 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. */
@@ -8,16 +46,18 @@ export class DiscoveryFeedSession {
     protocols;
     category;
     learning;
+    recommend;
     streams;
     pending = null;
     seen = new Set();
     page = 0;
     nextSource = 0;
-    constructor(posts, protocols, networks, category, source, learning) {
+    constructor(posts, protocols, networks, category, source, learning, recommend) {
         this.posts = posts;
         this.protocols = protocols;
         this.category = category;
         this.learning = learning;
+        this.recommend = recommend;
         const sources = [...new Set(networks.filter(n => n.capabilities.includes('public_trends')).map(n => n.protocol))].slice(0, 16);
         this.streams = ['minds', ...sources].filter(protocol => !source || source === 'all' || source === protocol)
             .map(protocol => ({ protocol, offset: 0, done: false, failed: false, used: [] }));
@@ -31,7 +71,7 @@ export class DiscoveryFeedSession {
         return this.pending;
     }
     async read(stream) {
-        const params = { limit: 20, ...(this.category ? { category: this.category } : {}), discovery: true };
+        const params = { limit: 25, ...(this.category ? { category: this.category } : {}), discovery: true };
         if (stream.protocol === 'minds') {
             const response = await this.posts.list({ ...params, sort: 'new', ...(stream.cursor ? { cursor: stream.cursor } : { offset: stream.offset }) });
             stream.offset += response.meta.scanned ?? response.meta.limit;
@@ -110,6 +150,8 @@ export class DiscoveryFeedSession {
             }
         }));
         // Round-robin before grouping: the largest network cannot occupy every slot.
+        // Each item carries the judgment for its own window of its source response,
+        // so one page can feature several modules instead of one per source batch.
         const mixed = [];
         for (let index = 0; index < Math.max(0, ...reads.map(read => read.items.length)); index++)
             for (const read of reads) {
@@ -117,7 +159,7 @@ export class DiscoveryFeedSession {
                 if (!item || this.seen.has(item.key))
                     continue;
                 this.seen.add(item.key);
-                mixed.push({ item, layout: read.layout });
+                mixed.push({ item, layout: windowLayout(read.layout, index) });
             }
         // Deduplication memory is bounded independently of the UI's virtual window.
         while (this.seen.size > 4096)
@@ -125,31 +167,89 @@ export class DiscoveryFeedSession {
         const modules = [];
         const page = this.page++;
         let remaining = mixed;
+        // One gallery strip per page: it may gather images from the whole page, so a
+        // second one would only sweep up leftovers into a stub.
+        let galleryMinted = false;
         while (remaining.length) {
             const index = modules.length;
             const first = remaining[0];
             const proposal = first.layout.source === 'jev' ? first.layout.presentation : 'posts';
             const preferred = this.learning?.choose(proposal, page) ?? proposal;
-            // Feature eligible posts within a small window, retaining the other posts
-            // in their original order. A gallery must not begin with a text-only card
-            // merely because nearby posts provided enough images for the layout.
-            const group = remaining.slice(0, 8);
-            const images = group.filter(row => row.item.post.media?.some(media => media.type === 'image')).slice(0, 4);
-            const conversations = group.filter(row => row.item.kind === 'social' ? (row.item.post.replyCount ?? 0) > 0 : (row.item.post.reply_count ?? 0) > 0).slice(0, 4);
+            // Feature eligible posts, retaining the other posts in their original
+            // order. A gallery is a horizontal strip, so it may gather image posts
+            // from the whole page (up to twelve); conversations and threads stay
+            // near their position so the vertical feed keeps its sense of time.
+            const group = remaining.slice(0, 12);
+            const images = remaining.filter(row => row.item.post.media?.some(media => media.type === 'image')).slice(0, GALLERY_MAX_ITEMS);
+            const conversations = group.filter(row => row.item.kind === 'social' ? (row.item.post.replyCount ?? 0) > 0 : (row.item.post.reply_count ?? 0) > 0).slice(0, 6);
+            const quotes = group.filter(row => quotesAnother(row.item)).slice(0, 6);
             const video = preferred === 'video' && first.item.post.media?.some(media => media.type === 'video');
-            const visual = preferred === 'visual' && images.length >= 2;
+            const visual = preferred === 'visual' && !galleryMinted && images.length >= 2;
+            if (visual)
+                galleryMinted = true;
             const discussion = preferred === 'conversation' && conversations.length >= 2;
-            const presentation = video ? 'video' : visual ? 'visual' : discussion ? 'conversation' : 'posts';
-            const selected = visual ? images : discussion ? conversations : [first];
+            const thread = preferred === 'thread' && quotes.length >= 2;
+            // A reading card features the post itself, never a neighbour: the first row must be the long one.
+            const longread = preferred === 'longread' && textLength(first.item) >= LONGREAD_MIN_CHARS;
+            const presentation = video ? 'video' : visual ? 'visual' : discussion ? 'conversation' : thread ? 'thread' : longread ? 'longread' : 'posts';
+            const selected = visual ? images : discussion ? conversations : thread ? quotes : [first];
             const items = selected.map(row => row.item);
-            modules.push({ id: `discovery-${page}-${index}-${items[0].key}`, presentation, source: presentation === 'posts' ? 'fallback' : 'jev', items,
-                spec: { root: 'module', elements: { module: { type: video ? 'DiscoveryVideo' : visual ? 'DiscoveryGallery' : discussion ? 'DiscoveryConversation' : 'DiscoveryPosts', props: { itemKeys: items.map(item => item.key) }, children: [] } } } });
+            const type = video ? 'DiscoveryVideo' : visual ? 'DiscoveryGallery' : discussion ? 'DiscoveryConversation' : thread ? 'DiscoveryThread' : longread ? 'DiscoveryLongRead' : 'DiscoveryPosts';
+            const theme = presentation !== 'posts' && first.layout.theme && first.layout.theme !== 'mixed' ? first.layout.theme : undefined;
+            modules.push({ id: `discovery-${page}-${index}-${items[0].key}`, presentation, source: presentation === 'posts' ? 'fallback' : 'jev', items, ...(theme ? { theme } : {}),
+                spec: { root: 'module', elements: { module: { type, props: { itemKeys: items.map(item => item.key) }, children: [] } } } });
             const selectedKeys = new Set(items.map(item => item.key));
             remaining = remaining.filter(row => !selectedKeys.has(row.item.key));
         }
+        // One recommendation module per page with posts, rotating kind, placed after
+        // the opening modules so the page still leads with content.
+        const recommendation = modules.length ? await this.recommendation(page) : null;
+        if (recommendation)
+            modules.splice(Math.min(2, modules.length), 0, recommendation);
         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) };
     }
+    async recommendation(page) {
+        const kinds = RECOMMENDATION_KINDS.filter(kind => typeof this.recommend?.[kind] === 'function');
+        const kind = kinds[page % Math.max(1, kinds.length)];
+        if (!kind)
+            return null;
+        // A viewer who keeps hiding a kind stops seeing it, through the same bandit as layouts.
+        if (this.learning && this.learning.choose(kind, page) === 'posts')
+            return null;
+        let candidates;
+        let cancel = () => { };
+        try {
+            candidates = await Promise.race([this.recommend[kind](), new Promise((_resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error('Recommendation source timed out')), 3000);
+                    cancel = () => clearTimeout(timer);
+                })]);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            cancel();
+        }
+        if (!Array.isArray(candidates))
+            return null;
+        const items = [];
+        for (const candidate of candidates) {
+            const item = recommendationItem(kind, candidate);
+            if (!item || this.seen.has(item.key) || items.some(existing => existing.key === item.key))
+                continue;
+            items.push(item);
+            if (items.length >= RECOMMENDATION_MAX_ITEMS)
+                break;
+        }
+        if (items.length < 2)
+            return null;
+        for (const item of items)
+            this.seen.add(item.key);
+        const type = kind === 'groups' ? 'DiscoveryGroups' : kind === 'people' ? 'DiscoveryPeople' : 'DiscoveryTags';
+        return { id: `discovery-${page}-recommend-${kind}`, presentation: kind, source: 'fallback', items,
+            spec: { root: 'module', elements: { module: { type, props: { itemKeys: items.map(item => item.key) }, children: [] } } } };
+    }
 }
 export class DiscoveryResource {
     posts;
@@ -159,6 +259,6 @@ export class DiscoveryResource {
         this.protocols = protocols;
     }
     createFeed(options) {
-        return new DiscoveryFeedSession(this.posts, this.protocols, options.networks, options.category, options.source, options.learning);
+        return new DiscoveryFeedSession(this.posts, this.protocols, options.networks, options.category, options.source, options.learning, options.recommend);
     }
 }

package/dist/resources/protocols.d.ts

@@ -989,6 +989,24 @@ export declare class ProtocolsResource {
         post: string;
         readRef?: string;
     }): Promise<SingleResponse<SocialConversation>>;
+    /** Public, app-moderated discovery without account authority. Enrichment uses cached judgments only. */
+    getSharedTrends(projectId: string, params: {
+        protocol: string;
+        limit?: number;
+        cursor?: string;
+        includePreviews?: boolean;
+        category?: string;
+        discovery?: boolean;
+    }): Promise<SingleResponse<SocialTrends>>;
+    /** Open a provider-listed topic through the same public-only app boundary. */
+    getSharedTrendFeed(projectId: string, params: {
+        protocol: string;
+        topic: string;
+        limit?: number;
+        cursor?: string;
+        category?: string;
+        discovery?: boolean;
+    }): Promise<SingleResponse<SocialTrendFeed>>;
     publicNetworks(): Promise<SingleResponse<SocialNetwork[]>>;
     /** Query the live public network. It does not import users or posts. */
     searchPublicPosts(params: SearchPublicPostsParams): Promise<SingleResponse<SocialPostSearch>>;

package/dist/resources/protocols.js

@@ -70,6 +70,16 @@ export class ProtocolsResource {
             protocol: params.protocol, post: params.post, readRef: params.readRef,
         });
     }
+    /** Public, app-moderated discovery without account authority. Enrichment uses cached judgments only. */
+    getSharedTrends(projectId, params) {
+        return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trends`, { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
+            includePreviews: params.includePreviews, category: params.category, discovery: params.discovery });
+    }
+    /** Open a provider-listed topic through the same public-only app boundary. */
+    getSharedTrendFeed(projectId, params) {
+        return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trend-feed`, { protocol: params.protocol, topic: params.topic,
+            limit: params.limit, cursor: params.cursor, category: params.category, discovery: params.discovery });
+    }
     publicNetworks() {
         return this.client.get('/protocols/social/networks');
     }

package/dist/types.d.ts

@@ -5,10 +5,22 @@ export interface PaginationParams {
     cursor?: string;
     [key: string]: unknown;
 }
+/** One judgment per consecutive window of the response; `start`/`end` index the response order. */
+export interface DiscoveryLayoutWindow {
+    start: number;
+    end: number;
+    presentation: 'posts' | 'visual' | 'conversation' | 'video' | 'thread' | 'longread';
+    source: 'jev' | 'fallback';
+    /** Browse-category id (or `mixed`) the window's posts share; lets a module be titled after its subject. */
+    theme?: string;
+}
 export interface DiscoveryLayout {
     version: 'discovery-layout-v1';
-    presentation: 'posts' | 'visual' | 'conversation' | 'video';
+    /** The first featured window's presentation; readers that understand `windows` use those instead. */
+    presentation: 'posts' | 'visual' | 'conversation' | 'video' | 'thread' | 'longread';
     source: 'jev' | 'fallback';
+    theme?: string;
+    windows?: DiscoveryLayoutWindow[];
 }
 export interface PaginationMeta {
     discovery?: DiscoveryLayout;

package/llm.md

@@ -637,6 +637,7 @@ if (subscription.active) {
 - Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source and exact `wireText`; connection is not publication approval. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
 - `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 }); 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.
+  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true }); 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.
   - 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.41",
+  "version": "0.7.44",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",