@recursiv/sdk 0.7.70 → 0.7.72

package/dist/resources/discovery-progressive.js

@@ -0,0 +1,414 @@
+import { readFalloverSteps } from './discovery-fallover.js';
+import { composeFirstScreen } from './discovery-first-screen.js';
+/** How long a round keeps waiting for its slower sources once one of them has answered. */
+export const DISCOVERY_STRAGGLER_MS = 3000;
+/**
+ * How long the first load waits for Minds and a second network, once its first source has answered, before it hands on
+ * what it has. Measured live (2026-09-27): the Minds read answers in 0.8-2 s in a category and 1.7-3.4 s on All; the
+ * open networks' in 0.2-1.3 s. Counted from the first answer, not from the load. A member's wait, and the default: the
+ * API caches a Discover page per caller for 30 s, so a member's first load is a fresh build of their Minds page.
+ */
+export const FIRST_SCREEN_MS = 2500;
+/**
+ * A visitor's wait. Every visitor reads the same anonymous page, so once anyone has read it in the last 30 s it answers
+ * in about 0.13 s, well inside this wait, and Minds leads; cold, the networks lead and Minds joins below.
+ */
+export const VISITOR_FIRST_SCREEN_MS = 800;
+/** Other networks read per round, as the session does per page: at most four requests a round. */
+const REMOTE_PER_ROUND = 3;
+const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
+const isPost = (item) => item.kind === 'minds' || item.kind === 'social';
+const isSuggestion = (item) => item.kind === 'group' || item.kind === 'person' || item.kind === 'tag';
+/** A suggestion rail with fewer is not drawn: the session builds none with fewer either. */
+const SUGGESTIONS_MIN = 2;
+/**
+ * A module without the items in `seen` (item keys). Posts already shown by another source's module are not shown again:
+ * the sessions dedupe within themselves, but across them a story's member posts can also arrive in that network's own
+ * page. A module that loses items keeps its spec in step. A suggestion already shown leaves its rail, and a rail left
+ * with fewer than two is dropped; a story already shown is dropped whole, and keeps its headline and outlets when only
+ * its posts were shown; a post module with none left is dropped (null).
+ */
+export function withoutSeenItems(module, seen) {
+    const lead = module.items[0];
+    if (lead?.kind === 'cluster' && seen.has(lead.key))
+        return null;
+    const items = module.items.filter(item => item.kind === 'cluster' || !seen.has(item.key));
+    if (items.length === module.items.length)
+        return module;
+    if (module.items.some(isSuggestion)) {
+        if (items.filter(isSuggestion).length < SUGGESTIONS_MIN)
+            return null;
+    }
+    else if (!items.some(item => isPost(item) || item.kind === 'cluster'))
+        return null;
+    const element = module.spec.elements.module;
+    return { ...module, items, spec: { ...module.spec, elements: { ...module.spec.elements,
+                module: { ...element, props: { ...element.props, itemKeys: items.map(item => item.key) } } } } };
+}
+/**
+ * Claims the posts a module shows, and only those. A story claims the members it carries, never its whole member list:
+ * the Minds session reads a story's network members only through its member reader, which may fail, time out or be
+ * missing. A member the story does not carry still shows in its network's own page.
+ */
+function remember(module, seen) {
+    for (const item of module.items)
+        if (isPost(item))
+            seen.add(item.key);
+}
+/** The other networks a feed over every source reads, in the session's own order. */
+export function discoveryRemoteSources(networks, source) {
+    if (source && source !== 'all')
+        return [];
+    return [...new Set(networks.filter(network => network.capabilities.includes('public_trends')).map(network => network.protocol))].slice(0, 16);
+}
+/**
+ * The suggestions a feed filtered to one network carries. The candidate lists are the whole app's: live on 2026-09-27
+ * Discover filtered to Nostr showed "People to follow" with three ActivityPub accounts. A network's own feed suggests
+ * only that network's accounts (a person's `protocol`, Minds when it has none); groups and tags are Minds', so they come
+ * with Minds' feed and with All's.
+ */
+export function discoveryRecommendationsFor(recommend, source) {
+    if (!recommend || !source || source === 'all')
+        return recommend;
+    const people = recommend.people;
+    const onSource = (person) => {
+        const protocol = person?.protocol;
+        return (typeof protocol === 'string' && protocol ? protocol : 'minds') === source;
+    };
+    const scoped = people ? { people: async () => (await people()).filter(onSource) } : {};
+    return source === 'minds' ? { ...recommend, ...scoped } : scoped;
+}
+/**
+ * The first recommendation read starts with the feed, not after its first page's posts; the Minds session's first call
+ * for that kind answers with that same read, and later calls read afresh.
+ */
+function warmRecommendations(recommend) {
+    const kind = RECOMMENDATION_KINDS.find(candidate => typeof recommend?.[candidate] === 'function');
+    if (!recommend || !kind)
+        return recommend;
+    const source = recommend[kind];
+    let warm = Promise.resolve().then(() => source());
+    warm.catch(() => { });
+    const first = () => {
+        const read = warm;
+        warm = null;
+        return read ?? source();
+    };
+    return { ...recommend, [kind]: first };
+}
+/** A token for one feed open ([A-Za-z0-9_-], up to 64): its sessions read the top of the feed once between them, and the server keeps that open's order stable. */
+export function discoveryFeedOpenToken() {
+    return `f${Math.random().toString(36).slice(2, 12)}${Date.now().toString(36)}`.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 64);
+}
+/** One top read per params for one feed open: every session asks it, and they share the answer. */
+function sharedTopRead(read) {
+    const reads = new Map();
+    return params => {
+        const key = JSON.stringify([params.ref, params.limit, params.session ?? null]);
+        let answer = reads.get(key);
+        if (!answer) {
+            answer = Promise.resolve().then(() => read(params));
+            reads.set(key, answer);
+        }
+        return answer;
+    };
+}
+/**
+ * What every session of one feed open shares: the top of the feed under one token for the open (one read between them:
+ * each places its own network's part), the posts the viewer saw (read once: an iterable may be read only once), and the
+ * stories they passed over and the visitor's rotation bucket.
+ */
+function openingOptions(options) {
+    const top = options.top
+        ? { ...options.top, session: options.top.session ?? discoveryFeedOpenToken(), ...(options.top.read ? { read: sharedTopRead(options.top.read) } : {}) }
+        : undefined;
+    return {
+        ...(top ? { top } : {}),
+        ...(options.seen ? { seen: new Set([...options.seen].filter((ref) => typeof ref === 'string')) } : {}),
+        ...(options.seenClusters ? { seenClusters: options.seenClusters } : {}),
+        ...(options.bucket !== undefined ? { bucket: options.bucket } : {}),
+    };
+}
+/** How long a top answer is shared by the feed opens that ask for it with the same params. */
+export const DISCOVERY_TOP_SHARE_MS = 60_000;
+/** After the top route answers 404 (it is off), how long a share does not ask it again. */
+export const DISCOVERY_TOP_OFF_MS = 5 * 60_000;
+const TOP_SHARE_MAX = 32;
+/** The answer a share gives while the route is off: what the route itself said (a 404). */
+class TopOff extends Error {
+    status = 404;
+    code = 'not_found';
+    constructor() { super('The top of the feed is off.'); this.name = 'TopOff'; }
+}
+const statusOf = (error) => (typeof error === 'object' && error !== null ? error.status : undefined);
+/**
+ * A share of top reads for one viewer's reader: `share(read, scope)` reads the top once for every session that asks
+ * with the same params (ref, limit, the open's session token) and `scope` (e.g. the Politics choice it reads under),
+ * while the read is out and DISCOVERY_TOP_SHARE_MS after. A route that answered 404 (off) is not asked again for
+ * DISCOVERY_TOP_OFF_MS. Make one share per viewer: never hand it another viewer's reader.
+ */
+export function createDiscoveryTopShare(now = Date.now) {
+    const reads = new Map();
+    let offUntil = 0;
+    return (read, scope = '') => params => {
+        const at = now();
+        if (at < offUntil)
+            return Promise.reject(new TopOff());
+        for (const [key, entry] of reads)
+            if (at - entry.at > DISCOVERY_TOP_SHARE_MS)
+                reads.delete(key);
+        const key = JSON.stringify([scope, params.ref, params.limit, params.session ?? null]);
+        const known = reads.get(key);
+        if (known)
+            return known.answer;
+        const answer = Promise.resolve().then(() => read(params));
+        reads.set(key, { at, answer });
+        while (reads.size > TOP_SHARE_MAX)
+            reads.delete(reads.keys().next().value);
+        answer.catch(error => { if (statusOf(error) === 404)
+            offUntil = now() + DISCOVERY_TOP_OFF_MS; });
+        return answer;
+    };
+}
+/**
+ * A progressive Discover feed over `factory`'s sessions (see the note above). `feedOptions` are a session's: over every
+ * source, Minds' session carries the radar and the recommendations (scoped to the feed's network filter,
+ * discoveryRecommendationsFor), and each other network with public trends gets a session filtered to itself, which
+ * carries Hide politics (`compass: 'hide'`) and no other choice. A feed filtered to one network, or with no other
+ * networks, is one session. `top`, `seen`, `seenClusters` and `bucket` reach every session, under one session token
+ * per open. Create a new feed when the viewer, category or filter changes.
+ */
+export function createProgressiveFeed(factory, feedOptions, { perSource = true, firstScreen = true, firstScreenMs = FIRST_SCREEN_MS, onLanded } = {}) {
+    // Discover's own feed follows its network filter; a feed that picks its own networks keeps the suggestions it was given.
+    const scoped = perSource ? discoveryRecommendationsFor(feedOptions.recommend, feedOptions.source) : feedOptions.recommend;
+    const recommend = warmRecommendations(scoped);
+    const opening = openingOptions(feedOptions);
+    const options = { ...feedOptions, ...(recommend === feedOptions.recommend ? {} : { recommend }), ...opening };
+    // The other networks this feed reads: the catalog it was opened with, and any it takes in later (setNetworks).
+    let remote = perSource ? discoveryRemoteSources(options.networks, options.source) : [];
+    const lane = (source, session) => ({ source, session, hasMore: true, failed: false, failedSources: [], retryingSources: [], partial: false, reading: null, opened: false });
+    // A network's session reads no Minds post: of the Politics choices it carries Hide politics alone.
+    const networkCompass = options.compass === 'hide' ? { compass: 'hide' } : {};
+    const networkFeed = (networks, protocol) => factory.createFeed({ networks, category: options.category, source: protocol,
+        ...(options.learning ? { learning: options.learning } : {}), ...opening, ...networkCompass });
+    // One source (a network filter, or no other networks): the session as it is. Every source: Minds carries the radar
+    // and the recommendations; each other network is a session filtered to itself.
+    const lanes = remote.length
+        ? [lane('minds', factory.createFeed({ ...options, networks: [] })), ...remote.map(protocol => lane(protocol, networkFeed(options.networks, protocol)))]
+        : [lane(options.source && options.source !== 'all' ? options.source : 'minds', factory.createFeed(options))];
+    /** Whether the first load is held and composed: only over every source, and only while there are other networks. */
+    const composing = () => firstScreen && remote.length > 0;
+    const seen = new Set();
+    /**
+     * Where a source's page goes as it lands. `opening`: the source's first page over every network, which leads with a
+     * post as the first screen does, unless the first load is holding it to hand on with the others.
+     */
+    let listener = () => { };
+    /** A source's first page handed on by itself (it landed after the first screen): it leads with a post, as that screen does. */
+    const opened = (part, opening) => (opening ? { ...part, modules: composeFirstScreen([part]), composed: true } : part);
+    let rotation = 0;
+    let rounds = 0;
+    /** The open round's callback, told each time any source's read lands (its own reads or a slow one from before). */
+    const landings = new Set();
+    /** Told of a landing when no round is open: a straggler from a round that already ended. */
+    const statusListeners = new Set();
+    const status = () => {
+        // Only the Minds feed carries a fall-through; each other network's lane is that network alone.
+        const fallover = lanes.find(item => item.source === 'minds')?.fallover;
+        const retryingSources = [...new Set(lanes.filter(item => !item.failed).flatMap(item => item.retryingSources))];
+        return {
+            hasMore: lanes.some(item => !!item.reading || (item.hasMore && !item.failed)),
+            failedSources: [...new Set(lanes.filter(item => item.failed).flatMap(item => item.failedSources.length ? item.failedSources : [item.source]))],
+            ...(retryingSources.length ? { retryingSources } : {}),
+            partialCategories: lanes.some(item => item.partial),
+            ...(fallover ? { fallover } : {}),
+        };
+    };
+    const summary = (modules) => ({ modules, ...status() });
+    const read = (item, round, onError) => {
+        item.reading = Promise.resolve().then(() => item.session.next()).then(page => {
+            // A network the catalog dropped while it read: nothing it brought is handed on, and it is not a failure.
+            if (item.retired)
+                return;
+            item.hasMore = page.hasMore;
+            item.failedSources = page.failedSources;
+            item.retryingSources = page.retryingSources ?? [];
+            item.failed = page.failedSources.length > 0;
+            onLanded?.(item.source, page.failedSources.includes(item.source));
+            item.partial = page.partialCategories;
+            item.fallover = readFalloverSteps(page.fallover) ?? item.fallover;
+            const modules = [];
+            for (const module of page.modules) {
+                const kept = withoutSeenItems(module, seen);
+                if (!kept)
+                    continue;
+                remember(kept, seen);
+                modules.push(kept);
+            }
+            if (!modules.length)
+                return;
+            // Over every network, a source's first page leads with a post, as the first screen does: the Minds page opens on
+            // its radar story, and one that landed after the first screen would go in story first. The page goes on as its
+            // source ranked it, marked `mixed` for a client to merge by engagement below what the reader has seen.
+            const opening = composing() && !item.opened;
+            item.opened = true;
+            listener({ source: item.source, round, modules, ...(remote.length > 0 ? { mixed: true } : {}) }, opening);
+        }, error => {
+            if (item.retired)
+                return;
+            item.failed = true;
+            item.failedSources = [item.source];
+            item.retryingSources = [];
+            onLanded?.(item.source, true);
+            onError(error);
+        }).finally(() => {
+            item.reading = null;
+            if (landings.size) {
+                for (const landed of [...landings])
+                    landed();
+                return;
+            }
+            const now = status();
+            for (const tell of [...statusListeners])
+                tell(now);
+        });
+    };
+    return {
+        onStatus(tell) {
+            statusListeners.add(tell);
+            return () => { statusListeners.delete(tell); };
+        },
+        setNetworks(networks) {
+            // A named feed reads its networks as one session, and a feed filtered to one network (or to Minds) reads no other.
+            if (!perSource || (options.source && options.source !== 'all'))
+                return false;
+            const wanted = discoveryRemoteSources(networks, options.source);
+            let rejoined = false;
+            for (const item of lanes) {
+                if (item.source === 'minds')
+                    continue;
+                const offered = wanted.includes(item.source);
+                if (!offered && !item.retired) {
+                    item.retired = true;
+                    item.hasMore = false;
+                    item.failed = false;
+                    item.failedSources = [];
+                    item.retryingSources = [];
+                }
+                else if (offered && item.retired) {
+                    item.retired = false;
+                    item.hasMore = true;
+                    rejoined = true;
+                }
+            }
+            remote = wanted;
+            // Under the same open as the rest: its token, so it shares the one top read, and what the reader already saw.
+            const added = wanted.filter(protocol => !lanes.some(item => item.source === protocol)).map(protocol => lane(protocol, networkFeed(networks, protocol)));
+            if (!added.length)
+                return rejoined;
+            lanes.push(...added);
+            // Before the first load, that load reads them with the rest, under the first screen's rules.
+            if (!rounds)
+                return true;
+            // After it, they are read now and land as a late source does, but only once the Minds read in flight has
+            // answered: a feed that began on Minds alone still opens on Minds. As many as a load reads; any more wait.
+            const begin = () => {
+                const ready = added.filter(item => !item.reading && !item.retired && item.hasMore && !item.failed).slice(0, REMOTE_PER_ROUND);
+                for (const item of ready)
+                    read(item, rounds - 1, () => undefined);
+            };
+            const minds = lanes[0]?.source === 'minds' ? lanes[0].reading : null;
+            if (minds)
+                void minds.then(begin, begin);
+            else
+                begin();
+            return true;
+        },
+        retryFailed() {
+            for (const item of lanes) {
+                if (!item.failed)
+                    continue;
+                item.failed = false;
+                item.failedSources = [];
+                item.hasMore = true;
+                item.session.retryFailed();
+            }
+        },
+        next(onPart) {
+            const round = rounds++;
+            const idle = lanes.filter(item => !item.reading && !item.retired && item.hasMore && !item.failed);
+            const multi = remote.length > 0;
+            const lead = multi && lanes[0] && idle.includes(lanes[0]) ? lanes[0] : undefined;
+            const others = multi ? idle.filter(item => item !== lanes[0]) : idle;
+            let picked = others;
+            if (multi && others.length > REMOTE_PER_ROUND) {
+                picked = Array.from({ length: REMOTE_PER_ROUND }, (_, index) => others[(rotation + index) % others.length]);
+                rotation += REMOTE_PER_ROUND;
+            }
+            const started = [...(lead ? [lead] : []), ...picked];
+            return new Promise((resolve, reject) => {
+                const arrived = [];
+                const errors = [];
+                let done = false;
+                let grace = null;
+                const deliver = (part) => { arrived.push(...part.modules); onPart(part); };
+                // The first load's parts wait here and go out as one screen.
+                const held = [];
+                let holding = round === 0 && composing();
+                let holdTimer = null;
+                const release = () => {
+                    if (!holding)
+                        return;
+                    holding = false;
+                    if (holdTimer)
+                        clearTimeout(holdTimer);
+                    const parts = held.splice(0);
+                    const modules = composeFirstScreen(parts);
+                    if (modules.length)
+                        deliver({ source: parts.some(part => part.source === 'minds') ? 'minds' : parts[0].source, round, modules, composed: true });
+                };
+                /** Minds has answered, and so has another network with posts (or every other network has). */
+                const firstScreenReady = () => !lead?.reading
+                    && (held.some(part => part.source !== 'minds') || !started.some(item => item !== lead && item.reading));
+                const collect = (part, opening) => { if (holding)
+                    held.push(part);
+                else
+                    deliver(opened(part, opening)); };
+                listener = collect;
+                const finish = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    release();
+                    if (grace)
+                        clearTimeout(grace);
+                    landings.delete(landed);
+                    // Later landings still reach the screen; they are simply not this round's.
+                    listener = (part, opening) => onPart(opened(part, opening));
+                    if (started.length && errors.length === started.length && !arrived.length)
+                        reject(errors[0]);
+                    else
+                        resolve(summary(arrived));
+                };
+                function landed() {
+                    if (done)
+                        return;
+                    if (holding)
+                        holdTimer ??= setTimeout(release, firstScreenMs);
+                    if (holding && firstScreenReady())
+                        release();
+                    if (!lanes.some(item => item.reading)) {
+                        finish();
+                        return;
+                    }
+                    grace ??= setTimeout(finish, DISCOVERY_STRAGGLER_MS);
+                }
+                landings.add(landed);
+                for (const item of started)
+                    read(item, round, error => { errors.push(error); });
+                if (!lanes.some(item => item.reading))
+                    finish();
+            });
+        },
+    };
+}

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

@@ -0,0 +1,32 @@
+/** A tag (a `Tag`, `{ slug }` or a bare name, with or without `#`) that marks a post sensitive: exact aliases only. */
+export declare function isSensitiveTag(tag: unknown): boolean;
+/**
+ * A link as written, to the end of its address; never from inside a word, an
+ * address or an email. A scheme is read to 63 characters: unbounded, a run of
+ * scheme characters with no ":" ("a+a+a+…//") was scanned to its end from
+ * every "+".
+ */
+export declare const DISCOVERY_LINK_TOKEN: RegExp;
+/**
+ * Each link DISCOVERY_LINK_TOKEN finds in a text, found without trying it at
+ * every character. A link runs to the end of its run of link characters, so
+ * a run holds one at most, and every one holds "//", "www." or a bare host's
+ * "label.label/": only a run holding one of those is read, from its start.
+ * The same tokens in the same order as text.matchAll(DISCOVERY_LINK_TOKEN).
+ */
+export declare function discoveryLinkTokens(text: string): string[];
+/**
+ * The text links a porn site, as stored or as a member sees it: a link in it
+ * (read through look-alike letters, hidden characters, IDNA dots and escapes),
+ * a link target in its markup or markdown as a browser opens it, or either
+ * once its character references are decoded or a legacy body's tags stripped.
+ */
+export declare function linksAdultSite(text: unknown): boolean;
+/**
+ * A Minds post to mask unless the member shows sensitive content: flagged NSFW
+ * (`is_nsfw` or `isNsfw`), tagged so, or linking a porn site in its content or
+ * title. Live on 2026-09-27 a visitor's Discover All showed "I think she likes
+ * it. https://xhamster.com/videos/…" with the video's explicit thumbnail as its
+ * picture: its author never flagged it.
+ */
+export declare function isSensitivePost(post: unknown): boolean;