@recursiv/sdk 0.7.39 → 0.7.40

package/README.md

@@ -595,3 +595,17 @@ Standalone public text publication uses `protocols.prepareNativePost({ clientMut
 For Bluesky accounts advertising `quote`, prepare the same publication with `quote: { protocol: 'bluesky', nativeId: sourceAtUri }`. The server resolves the exact source CID using each connected account, checks quote permission and Minds safety, and rechecks before writing. Review each delivery’s `quote` alongside the account and comment before submitting. Changed or unavailable sources cannot publish; uncertain deliveries reconcile the original record key. ActivityPub/Nostr quotes are not provided by this method. Public post reads include at most one filtered `quote` with `state: 'available'` and `post`, or `state: 'unavailable'` without source content. Available quotes may include `embeddedReferences`: exact standalone source-reference lines in the unchanged outer `text`. Omit them only when the quoted original is actually visible; retain them for unavailable or locally hidden quotes. Nostr references are decoded and matched by the server, without following relay hints.
 
 Topic browsing can request `getPublicTrends({ protocol: "bluesky", includePreviews: true })`. Optional `SocialTrend.preview` is a real image-bearing post from that topic, never a generated illustration. The server samples at most eight posts for each of ten topics, with three concurrent reads and a shared 2.5-second deadline; missing images leave usable text topics. App moderation and user source controls filter previews on every request. Bluesky CDN image attachments, quote-with-media images, and unlabeled link-preview thumbnails are supported; omitted content retains the source link.
+
+### Continuous public discovery
+
+Create one `sdk.discovery.createFeed({ networks, category, source, learning })`
+per signed-in viewer and filter. Pass the app-advertised network catalog, then call
+`next()` as the reader approaches the end. Each page contains safe json-render
+module specs and native or protocol post objects. Preserve their existing source
+authority and interactive controls. `retryFailed()` explicitly retries unavailable
+sources; create a new session to refresh exhausted source windows.
+
+Optional `DiscoveryLearning` consumes real visible impressions and explicit
+engagement/hide outcomes. Persist its count-only snapshot per viewer; never share
+a session or learning state across accounts. It starts conservatively and does
+not imply measured retention improvement.

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+export * from './resources/discovery-learning.js';
+import { DiscoveryResource } from './resources/discovery.js';
+export * from './resources/discovery.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
@@ -113,6 +116,7 @@ export declare class Recursiv {
     readonly webhooks: WebhooksResource;
     readonly jobs: JobsResource;
     readonly curator: CuratorResource;
+    readonly discovery: DiscoveryResource;
     readonly video: VideoResource;
     readonly appSubscriptions: AppSubscriptionsResource;
     readonly reports: ReportsResource;

package/dist/index.js

@@ -1,3 +1,6 @@
+export * from './resources/discovery-learning.js';
+import { DiscoveryResource } from './resources/discovery.js';
+export * from './resources/discovery.js';
 import { HttpClient } from './client.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
@@ -114,6 +117,7 @@ export class Recursiv {
     webhooks;
     jobs;
     curator;
+    discovery;
     video;
     appSubscriptions;
     reports;
@@ -175,6 +179,7 @@ export class Recursiv {
         this.webhooks = new WebhooksResource(client);
         this.jobs = new JobsResource(client);
         this.curator = new CuratorResource(client);
+        this.discovery = new DiscoveryResource(this.posts, this.protocols);
         this.video = new VideoResource(client);
         this.appSubscriptions = new AppSubscriptionsResource(client);
         this.reports = new ReportsResource(client);

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

@@ -0,0 +1,27 @@
+import type { DiscoveryLayout } from '../types.js';
+export type DiscoveryPresentation = DiscoveryLayout['presentation'];
+type Counts = {
+    views: number;
+    engagements: number;
+    hides: number;
+};
+export interface DiscoveryLearningSnapshot {
+    version: 1;
+    startedAt: number;
+    layouts: Record<DiscoveryPresentation, Counts>;
+}
+/** Local, per-viewer experimental presentation preferences. Stores counts only,
+ * never source text, author IDs or inferred traits. It cannot promote content,
+ * bypass safety, add unsupported layouts or establish a causal lift claim. */
+export declare class DiscoveryLearning {
+    private now;
+    private value;
+    private observed;
+    constructor(input?: unknown, now?: () => number);
+    observe(id: string, presentation: DiscoveryPresentation, event: 'view' | 'engage' | 'hide'): void;
+    /** Jev proposes a suitable layout. Sufficient recent feedback may restore full
+     * post cards; every tenth eligible batch explores the safe proposal again. */
+    choose(proposal: DiscoveryPresentation, page: number): DiscoveryPresentation;
+    snapshot(): DiscoveryLearningSnapshot;
+}
+export {};

package/dist/resources/discovery-learning.js

@@ -0,0 +1,58 @@
+const names = ['posts', 'visual', 'conversation', 'video'];
+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 },
+    } });
+/** Local, per-viewer experimental presentation preferences. Stores counts only,
+ * never source text, author IDs or inferred traits. It cannot promote content,
+ * bypass safety, add unsupported layouts or establish a causal lift claim. */
+export class DiscoveryLearning {
+    now;
+    value;
+    observed = new Set();
+    constructor(input, now = Date.now) {
+        this.now = now;
+        const value = input;
+        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];
+            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);
+    }
+    observe(id, presentation, event) {
+        if (!names.includes(presentation) || !id || id.length > 8192)
+            return;
+        const key = `${id}:${event}`;
+        if (this.observed.has(key))
+            return;
+        // Engagements/hides require a real visible impression in this session.
+        if (event !== 'view' && !this.observed.has(`${id}:view`))
+            return;
+        this.observed.add(key);
+        while (this.observed.size > 4096)
+            this.observed.delete(this.observed.values().next().value);
+        const counters = this.value.layouts[presentation];
+        counters[event === 'view' ? 'views' : event === 'engage' ? 'engagements' : 'hides']++;
+        if (counters.views >= 10000)
+            for (const counts of Object.values(this.value.layouts)) {
+                counts.views = Math.floor(counts.views / 2);
+                counts.engagements = Math.floor(counts.engagements / 2);
+                counts.hides = Math.floor(counts.hides / 2);
+            }
+    }
+    /** Jev proposes a suitable layout. Sufficient recent feedback may restore full
+     * post cards; every tenth eligible batch explores the safe proposal again. */
+    choose(proposal, page) {
+        if (proposal === 'posts' || page % 10 === 0)
+            return proposal;
+        const selected = this.value.layouts[proposal];
+        const baseline = this.value.layouts.posts;
+        if (selected.views < 50 || baseline.views < 50)
+            return proposal;
+        const value = (c) => (c.engagements + 2 - 3 * c.hides) / (c.views + 10);
+        // Require a material difference, rather than switching on a single click.
+        return value(selected) + 0.1 < value(baseline) ? 'posts' : proposal;
+    }
+    snapshot() { return JSON.parse(JSON.stringify(this.value)); }
+}

package/dist/resources/discovery.d.ts

@@ -0,0 +1,69 @@
+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 = {
+    key: string;
+    kind: 'minds';
+    post: Post;
+} | {
+    key: string;
+    kind: 'social';
+    post: SocialPost;
+};
+/** 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'];
+    source: DiscoveryLayout['source'];
+    items: DiscoveryItem[];
+    spec: {
+        root: 'module';
+        elements: {
+            module: {
+                type: 'DiscoveryPosts' | 'DiscoveryGallery' | 'DiscoveryConversation' | 'DiscoveryVideo';
+                props: {
+                    itemKeys: string[];
+                };
+                children: [];
+            };
+        };
+    };
+}
+export interface DiscoveryFeedPage {
+    modules: DiscoveryModule[];
+    hasMore: boolean;
+    failedSources: string[];
+    partialCategories: boolean;
+}
+/** 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. */
+export declare class DiscoveryFeedSession {
+    private posts;
+    private protocols;
+    private category?;
+    private learning?;
+    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);
+    retryFailed(): void;
+    next(): Promise<DiscoveryFeedPage>;
+    private read;
+    private readPage;
+}
+export declare class DiscoveryResource {
+    private posts;
+    private protocols;
+    constructor(posts: PostsResource, protocols: ProtocolsResource);
+    createFeed(options: {
+        networks: SocialNetwork[];
+        category?: string;
+        source?: string;
+        learning?: DiscoveryLearning;
+    }): DiscoveryFeedSession;
+}

package/dist/resources/discovery.js

@@ -0,0 +1,156 @@
+const ordinary = { version: 'discovery-layout-v1', presentation: 'posts', source: 'fallback' };
+const key = (protocol, id) => JSON.stringify([protocol, id]);
+/** 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. */
+export class DiscoveryFeedSession {
+    posts;
+    protocols;
+    category;
+    learning;
+    streams;
+    pending = null;
+    seen = new Set();
+    page = 0;
+    nextSource = 0;
+    constructor(posts, protocols, networks, category, source, learning) {
+        this.posts = posts;
+        this.protocols = protocols;
+        this.category = category;
+        this.learning = learning;
+        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: [] }));
+    }
+    retryFailed() { for (const stream of this.streams)
+        stream.failed = false; }
+    next() {
+        if (this.pending)
+            return this.pending;
+        this.pending = this.readPage().finally(() => { this.pending = null; });
+        return this.pending;
+    }
+    async read(stream) {
+        const params = { limit: 20, ...(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;
+            const next = response.meta.next_cursor ?? undefined;
+            stream.done = !response.meta.has_more || !!next && (next === stream.cursor || stream.used.includes(next));
+            if (stream.cursor)
+                stream.used = [...stream.used, stream.cursor].slice(-32);
+            stream.cursor = next;
+            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' };
+        }
+        const validatePosts = (data) => {
+            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 });
+            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 { data } = await this.protocols.getPublicTrends({ ...params, protocol: stream.protocol, cursor: stream.cursor, includePreviews: true });
+        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');
+        if (data.kind === 'topics') {
+            if (data.items.some(topic => topic.preview && (topic.preview.protocol !== stream.protocol || topic.preview.author.protocol !== stream.protocol)))
+                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' };
+        }
+        validatePosts(data);
+        const next = data.cursor ?? undefined;
+        stream.done = !next || next === stream.cursor || stream.used.includes(next);
+        if (stream.cursor)
+            stream.used = [...stream.used, stream.cursor].slice(-32);
+        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' };
+    }
+    async readPage() {
+        const active = this.streams.filter(stream => !stream.done && !stream.failed);
+        const native = active.find(stream => stream.protocol === 'minds');
+        const remote = active.filter(stream => stream.protocol !== 'minds');
+        const selected = [...(native ? [native] : []), ...Array.from({ length: Math.min(native ? 3 : 4, remote.length) }, (_, index) => remote[(this.nextSource + index) % remote.length])];
+        this.nextSource += 3;
+        const reads = await Promise.all(selected.map(async (stream) => {
+            // Commit continuation state only if this page finishes within its UI
+            // deadline. A late provider cannot move the cursor past unseen content.
+            const candidate = { ...stream, used: [...stream.used], topics: stream.topics?.map(topic => ({ ...topic, used: [...topic.used] })) };
+            let cancel = () => { };
+            try {
+                const read = await Promise.race([this.read(candidate), new Promise((_resolve, reject) => {
+                        const timer = setTimeout(() => reject(new Error('Discovery source timed out')), 15000);
+                        cancel = () => clearTimeout(timer);
+                    })]);
+                Object.assign(stream, candidate);
+                return read;
+            }
+            catch {
+                stream.failed = true;
+                return { items: [], layout: ordinary, partial: false };
+            }
+            finally {
+                cancel();
+            }
+        }));
+        // Round-robin before grouping: the largest network cannot occupy every slot.
+        const mixed = [];
+        for (let index = 0; index < Math.max(0, ...reads.map(read => read.items.length)); index++)
+            for (const read of reads) {
+                const item = read.items[index];
+                if (!item || this.seen.has(item.key))
+                    continue;
+                this.seen.add(item.key);
+                mixed.push({ item, layout: read.layout });
+            }
+        // Deduplication memory is bounded independently of the UI's virtual window.
+        while (this.seen.size > 4096)
+            this.seen.delete(this.seen.values().next().value);
+        const modules = [];
+        const page = this.page++;
+        for (let index = 0; index < mixed.length;) {
+            const first = mixed[index];
+            const proposal = first.layout.source === 'jev' ? first.layout.presentation : 'posts';
+            const preferred = this.learning?.choose(proposal, page) ?? proposal;
+            const group = mixed.slice(index, index + 4);
+            const video = preferred === 'video' && first.item.post.media?.some(media => media.type === 'video');
+            const visual = preferred === 'visual' && group.filter(row => row.item.post.media?.some(media => media.type === 'image')).length >= 2;
+            const discussion = preferred === 'conversation' && group.filter(row => row.item.kind === 'social' ? (row.item.post.replyCount ?? 0) > 0 : (row.item.post.reply_count ?? 0) > 0).length >= 2;
+            const presentation = video ? 'video' : visual ? 'visual' : discussion ? 'conversation' : 'posts';
+            const selected = presentation === 'posts' || video ? [first] : group;
+            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: [] } } } });
+            index += selected.length;
+        }
+        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) };
+    }
+}
+export class DiscoveryResource {
+    posts;
+    protocols;
+    constructor(posts, protocols) {
+        this.posts = posts;
+        this.protocols = protocols;
+    }
+    createFeed(options) {
+        return new DiscoveryFeedSession(this.posts, this.protocols, options.networks, options.category, options.source, options.learning);
+    }
+}

package/dist/resources/protocols.d.ts

@@ -1,3 +1,4 @@
+import type { DiscoveryLayout } from '../types.js';
 import type { HttpClient } from '../client.js';
 import type { PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
 /** Canonical protocol operation names returned by the adapter registry. */
@@ -844,9 +845,10 @@ export interface SocialPost {
     likeCount: number | null;
     repostCount: number | null;
     media: Array<{
-        type: 'image';
+        type: 'image' | 'video';
         url: string;
         alt: string;
+        poster?: string;
     }>;
     hasAdditionalContent: boolean;
     /** At most one independently filtered quoted post. */
@@ -884,6 +886,7 @@ export interface SocialAuthorFeed {
     coverage: 'original_posts';
 }
 export interface SocialTrendProvenance {
+    discovery?: DiscoveryLayout;
     provider: {
         name: string;
         url: string;
@@ -1024,6 +1027,7 @@ export declare class ProtocolsResource {
         cursor?: string;
         includePreviews?: boolean;
         category?: string;
+        discovery?: boolean;
     }): Promise<SingleResponse<SocialTrends>>;
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
     getPublicTrendFeed(params: {
@@ -1032,6 +1036,7 @@ export declare class ProtocolsResource {
         limit?: number;
         cursor?: string;
         category?: string;
+        discovery?: boolean;
     }): Promise<SingleResponse<SocialTrendFeed>>;
     /** Provider-ranked public accounts with explicit provenance; served from the app's index when a fresh snapshot exists. */
     getPublicPopularProfiles(params: {

package/dist/resources/protocols.js

@@ -111,12 +111,14 @@ export class ProtocolsResource {
     getPublicTrends(params) {
         return this.client.get('/protocols/social/trends', { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
             ...(params.includePreviews !== undefined ? { includePreviews: params.includePreviews } : {}),
-            ...(params.category !== undefined ? { category: params.category } : {}) });
+            ...(params.category !== undefined ? { category: params.category } : {}),
+            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) });
     }
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
     getPublicTrendFeed(params) {
         return this.client.get('/protocols/social/trend-feed', { protocol: params.protocol, topic: params.topic, limit: params.limit, cursor: params.cursor,
-            ...(params.category !== undefined ? { category: params.category } : {}) });
+            ...(params.category !== undefined ? { category: params.category } : {}),
+            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) });
     }
     /** Provider-ranked public accounts with explicit provenance; served from the app's index when a fresh snapshot exists. */
     getPublicPopularProfiles(params) {

package/dist/types.d.ts

@@ -5,7 +5,20 @@ export interface PaginationParams {
     cursor?: string;
     [key: string]: unknown;
 }
+export interface DiscoveryLayout {
+    version: 'discovery-layout-v1';
+    presentation: 'posts' | 'visual' | 'conversation' | 'video';
+    source: 'jev' | 'fallback';
+}
 export interface PaginationMeta {
+    discovery?: DiscoveryLayout;
+    scanned?: number;
+    category_filter?: {
+        selected: string;
+        status: 'complete' | 'partial';
+        classified: number;
+        unclassified: number;
+    };
     limit: number;
     offset: number;
     has_more: boolean;
@@ -93,6 +106,7 @@ export interface MediaItem {
     type: string;
 }
 export interface Post {
+    reply_count?: number;
     id: string;
     /** Original Minds numeric GUID when this row came from the legacy import. */
     legacy_guid?: string | null;
@@ -171,6 +185,8 @@ export interface UpdatePostInput {
 }
 export type ReactionType = 'like' | 'heart' | 'fire' | 'laugh' | 'sad' | 'angry' | 'upvote' | 'downvote';
 export interface ListPostsParams extends PaginationParams {
+    /** Public-only feed with a bounded Jev presentation hint. Limit <=25. */
+    discovery?: boolean;
     /** Public-only broad category. Requires an enabled app experiment; limit <=25. */
     category?: string;
     community_id?: string;

package/package.json

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