@recursiv/sdk 0.7.42 → 0.7.45

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

@@ -1,8 +1,44 @@
-import type { DiscoveryLearning } from './discovery-learning.js';
 import type { DiscoveryLayout, Post } from '../types.js';
+import type { DiscoveryLearning } from './discovery-learning.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,9 +71,11 @@ 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 }) });
+            // Discover leads with what is moving now: the REST hot order (engagement
+            // decayed by age). Hot pages by offset; the server sends no cursor for it.
+            const response = await this.posts.list({ ...params, sort: 'hot', ...(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));
@@ -110,6 +152,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 +161,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 +169,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 +261,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

@@ -1,6 +1,5 @@
-import type { DiscoveryLayout } from '../types.js';
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
+import type { DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
 /** Canonical protocol operation names returned by the adapter registry. */
 export declare const PROTOCOL_CAPABILITY_OPERATIONS: readonly ["discover", "stream", "backfill", "search", "resolveIdentity", "fetchProfile", "fetchThread", "publish", "reply", "react", "repost", "follow", "delete", "health", "checkpoint"];
 export declare const PROTOCOL_CAPABILITY_STATUSES: readonly ["supported", "planned", "unsupported"];
@@ -844,11 +843,14 @@ export interface SocialPost {
     replyCount: number | null;
     likeCount: number | null;
     repostCount: number | null;
+    /** Pixel dimensions when the source declares them (Bluesky aspect ratio, Mastodon attachment meta), so a card can take the clip's shape before it loads. */
     media: Array<{
         type: 'image' | 'video';
         url: string;
         alt: string;
         poster?: string;
+        width?: number;
+        height?: number;
     }>;
     hasAdditionalContent: boolean;
     /** At most one independently filtered quoted post. */

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/package.json

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