@recursiv/sdk 0.7.81 → 0.7.83

package/dist/assistant/subjectBundle.js

@@ -0,0 +1,518 @@
+/**
+ * `buildSubjectBundle`: what an assistant may read about a post, built from data the caller already holds. The
+ * server, a Sealed phone (no request at all) and an app's own ask all build it the same way, so the rules below hold
+ * wherever the ask starts:
+ *
+ * - posts and replies whose authors turned asks off are left out, and 'sealed_only' authors are read only in Sealed;
+ * - authors the asker blocked or muted, and authors who blocked the asker, are left out;
+ * - known-minor authors are left out unless the asker is that author;
+ * - posts under a child-safety hold, and posts a moderator turned the assistant off for, are left out, whoever asks;
+ * - a post the server's per-viewer verdict (`assist_readable`) says is not readable is left out, whoever asks;
+ * - pictures go as alt text and the stored caption only: never bytes, never an address (held media not even that);
+ * - every string loses what a reader cannot see (stripHiddenText) and is cut to its limit, and the bundle has a total
+ *   that the asked-about post is cut to fit as well.
+ *
+ * Every safety flag fails closed: any value but `false`, `null` or absent counts as set, and an id list that cannot be
+ * read throws. When the asked-about post itself is left out the result has no bundle: make no model call. The
+ * exclusions are counts by reason, never ids or handles, and the reasons the asker may see fold blocks, minors, holds
+ * and suppression into one ('unavailable'); the detail is in `audit`, for the server's log only. Pure: no clock, no
+ * randomness, no network.
+ */
+import { findHandles, findUrls, mapUrls, stripHiddenText } from './hiddenText.js';
+/** The default (and highest) limits. A caller may lower them, never raise them. */
+export const SUBJECT_BUNDLE_LIMITS = Object.freeze({
+    max_replies: 20,
+    max_media: 8,
+    post_chars: 2000,
+    context_chars: 1000,
+    reply_chars: 500,
+    title_chars: 200,
+    name_chars: 64,
+    alt_text_chars: 300,
+    caption_chars: 600,
+    link_title_chars: 200,
+    link_description_chars: 300,
+    total_chars: 12_000,
+});
+/** Ids are opaque, but plain: nothing that could close a label or start a line. */
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/** A plain handle, or a federated one with its server. Anything else is rendered as no handle, never mangled. */
+const HANDLE_PATTERN = /^[A-Za-z0-9_](?:[A-Za-z0-9_.-]{0,62}[A-Za-z0-9_])?(?:@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)?$/;
+const ISO_TIME = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}(?::\d{2})?)(\.\d+)?(Z|[+-]\d{2}:?\d{2})$/i;
+const WEB_ADDRESS = /^https?:\/\/[^\s<>"'`]+$/i;
+const MAX_URL_LENGTH = 2048;
+/** The host and path of a web address, without the URL global (not every phone runtime has a whole one). */
+const URL_PARTS = /^https?:\/\/(?:[^/?#@]*@)?(\[[^\]]*\]|[^/?#:]*)(?::\d*)?([^?#]*)/i;
+const PICTURE_FILE = /\.(?:png|jpe?g|jfif|gif|webp|avif|heic|heif|bmp|svg|ico|tiff?)$/i;
+/** Hosts that serve members' pictures and clips: Minds' CDN, R2 and Bunny. */
+const MEDIA_HOST = /(?:^|\.)(?:cdn\.minds\.com|r2\.dev|r2\.cloudflarestorage\.com|b-cdn\.net|bunnycdn\.com|cdn\.recursiv\.io)$/i;
+/** Paths that serve them on any host: Minds' /fs/v1/thumbnail and kin, and /api/v2/media/proxy and kin. */
+const MEDIA_PATH = /^\/(?:fs\/v\d+\/|api\/v\d+\/media\/)/i;
+/** What a picture or clip address in a member's text becomes. */
+export const PICTURE_LINK_LABEL = '[link to a picture or clip]';
+const ELLIPSIS = '\u2026';
+/** Characters as code points: what every limit counts, so an emoji is one character and a cut never splits one. */
+export function textLength(text) {
+    let n = 0;
+    for (const _point of text)
+        n += 1;
+    return n;
+}
+function cut(text, limit) {
+    if (!text)
+        return { value: null, truncated: false };
+    if (text.length <= limit)
+        return { value: text, truncated: false };
+    // Count code points, so a cut never splits a surrogate pair.
+    const points = Array.from(text);
+    if (points.length <= limit)
+        return { value: text, truncated: false };
+    if (limit <= 0)
+        return { value: null, truncated: true };
+    return { value: `${points.slice(0, Math.max(0, limit - 1)).join('').trimEnd()}${ELLIPSIS}`, truncated: true };
+}
+/**
+ * A picture's or clip's address, which a model must never be handed: one ending in a picture file type, or on a host
+ * or path that serves members' media (Minds' own picture addresses have no file type).
+ */
+export function isPictureAddress(url) {
+    const parts = URL_PARTS.exec(url);
+    if (!parts)
+        return false;
+    const host = parts[1].toLowerCase().replace(/\.$/, '');
+    let path = parts[2];
+    try {
+        path = decodeURIComponent(path);
+    }
+    catch {
+        // A path that does not decode is read as written.
+    }
+    return MEDIA_HOST.test(host) || MEDIA_PATH.test(path) || PICTURE_FILE.test(path.replace(/\/+$/, ''));
+}
+/** Text a member wrote as a reader sees it, with each picture address replaced by a label. */
+function visible(value) {
+    return mapUrls(stripHiddenText(value), (url) => (isPictureAddress(url) ? PICTURE_LINK_LABEL : url));
+}
+/** One line of visible text: hidden text gone, spacing collapsed, cut to `limit`. */
+function line(value, limit) {
+    if (typeof value !== 'string')
+        return { value: null, truncated: false };
+    return cut(visible(value).replace(/\s+/g, ' ').trim(), limit);
+}
+/** Visible text that keeps its paragraphs. */
+function paragraphs(value, limit) {
+    if (typeof value !== 'string')
+        return { value: null, truncated: false };
+    const text = visible(value)
+        .replace(/[^\S\n]+/g, ' ')
+        .replace(/ ?\n ?/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return cut(text, limit);
+}
+export function plainId(value) {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+        return String(value);
+    return typeof value === 'string' && ID_PATTERN.test(value) ? value : null;
+}
+export function plainHandle(value) {
+    if (typeof value !== 'string')
+        return null;
+    const handle = value.trim().replace(/^@/, '');
+    return HANDLE_PATTERN.test(handle) ? handle : null;
+}
+export function isoTime(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = ISO_TIME.exec(value.trim());
+    if (!match)
+        return null;
+    const fraction = match[3] ? match[3].slice(0, 4) : '';
+    const zone = match[4].length === 5 ? `${match[4].slice(0, 3)}:${match[4].slice(3)}` : match[4];
+    const time = Date.parse(`${match[1]}T${match[2]}${fraction}${zone.toUpperCase()}`);
+    return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+export function webAddress(value) {
+    if (typeof value !== 'string')
+        return null;
+    const url = stripHiddenText(value).trim();
+    if (!url || url.length > MAX_URL_LENGTH || !WEB_ADDRESS.test(url))
+        return null;
+    // A link card that points at a picture would hand the model a picture's address.
+    return isPictureAddress(url) ? null : url;
+}
+export function count(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+}
+function counts(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const out = {};
+    for (const key of ['votes', 'upvotes', 'downvotes', 'replies', 'reposts']) {
+        const n = count(value[key]);
+        if (n === undefined)
+            continue;
+        if (key !== 'votes' && n < 0)
+            continue;
+        out[key] = n;
+    }
+    return Object.keys(out).length ? out : null;
+}
+function mediaType(value) {
+    const type = typeof value === 'string' ? value.toLowerCase() : '';
+    if (type === 'image' || type === 'photo' || type === 'gif' || type.startsWith('image/'))
+        return 'image';
+    if (type === 'video' || type === 'clip' || type.startsWith('video/'))
+        return 'video';
+    if (type === 'audio' || type === 'sound' || type.startsWith('audio/'))
+        return 'audio';
+    return 'other';
+}
+/** The author's choice as one of the three, failing closed on a value this SDK does not know. */
+export function resolveAskChoice(value) {
+    if (value === undefined || value === null || value === true || value === 'all')
+        return 'all';
+    if (value === 'sealed_only')
+        return 'sealed_only';
+    return 'off';
+}
+/** The server's verdict, or null when it gave none; a value this SDK does not know means 'none'. */
+function resolveReadable(value) {
+    if (value === undefined || value === null)
+        return null;
+    return value === 'all' || value === 'sealed_only' ? value : 'none';
+}
+/** A safety flag, failing closed: anything but false, null or absent (a record, a time, 1, 't') counts as set. */
+function isSet(value) {
+    return value !== undefined && value !== null && value !== false;
+}
+/** An id list. One that is present but cannot be read throws: a block list must never count as empty by mistake. */
+function toSet(values, name) {
+    const out = new Set();
+    if (values === undefined || values === null)
+        return out;
+    if (typeof values !== 'object' || typeof values[Symbol.iterator] !== 'function') {
+        throw new TypeError(`buildSubjectBundle: asker.${name} must be an array or a set of ids`);
+    }
+    for (const value of values) {
+        if (typeof value === 'string') {
+            if (value)
+                out.add(value);
+        }
+        else if (typeof value === 'number' && Number.isFinite(value)) {
+            out.add(String(value));
+        }
+        else {
+            throw new TypeError(`buildSubjectBundle: asker.${name} holds an entry that is not an id`);
+        }
+    }
+    return out;
+}
+function resolveLimits(overrides) {
+    const limits = { ...SUBJECT_BUNDLE_LIMITS };
+    if (!overrides)
+        return limits;
+    for (const key of Object.keys(limits)) {
+        const value = overrides[key];
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            limits[key] = Math.max(0, Math.min(SUBJECT_BUNDLE_LIMITS[key], Math.floor(value)));
+        }
+    }
+    return limits;
+}
+/** Why `post` may not be read by this asker, or null when it may. Order matters only for which reason is counted. */
+function ruleOut(post, rules) {
+    if (!post || typeof post !== 'object' || plainId(post.id) === null)
+        return 'invalid';
+    if (isSet(post.child_safety_hold))
+        return 'child_safety_hold';
+    if (isSet(post.assistant_suppressed))
+        return 'moderator_suppressed';
+    // The server's verdict is for this viewer already, the author included.
+    const verdict = resolveReadable(post.assist_readable);
+    if (verdict === 'none')
+        return 'not_readable';
+    if (verdict === 'sealed_only' && rules.mode !== 'sealed')
+        return 'author_sealed_only';
+    const authorId = post.author && typeof post.author.id === 'string' ? post.author.id : '';
+    if (!authorId)
+        return 'unknown_author';
+    // The asker's own posts: their blocks, age and ask choice are theirs to waive.
+    if (authorId === rules.askerId)
+        return null;
+    if (rules.walls.has(authorId))
+        return 'blocked_or_muted';
+    if (isSet(post.author?.known_minor))
+        return 'known_minor_author';
+    const choice = resolveAskChoice(post.ai_ask_allowed);
+    if (choice === 'off')
+        return 'author_opted_out';
+    if (choice === 'sealed_only' && rules.mode !== 'sealed')
+        return 'author_sealed_only';
+    return null;
+}
+const UNAVAILABLE = new Set([
+    'child_safety_hold', 'moderator_suppressed', 'blocked_or_muted', 'known_minor_author', 'media_held', 'not_readable',
+]);
+/** A reason as the asker may be told it: blocks, minors, holds, suppression and a 'none' verdict all read the same. */
+function askerReason(reason) {
+    return UNAVAILABLE.has(reason) ? 'unavailable' : reason;
+}
+class Exclusions {
+    counts = new Map();
+    add(role, reason, n = 1) {
+        if (n <= 0)
+            return;
+        const key = `${role}:${reason}`;
+        const entry = this.counts.get(key);
+        if (entry)
+            entry.count += n;
+        else
+            this.counts.set(key, { role, reason, count: n });
+    }
+    /** The detail, for the server's log. */
+    detailed() {
+        return [...this.counts.values()].map((entry) => ({ ...entry }));
+    }
+    /** What the asker may be told: the same counts, with the reasons behind 'unavailable' merged. */
+    forAsker() {
+        const merged = new Map();
+        for (const entry of this.counts.values()) {
+            const reason = askerReason(entry.reason);
+            const key = `${entry.role}:${reason}`;
+            const found = merged.get(key);
+            if (found)
+                found.count += entry.count;
+            else
+                merged.set(key, { role: entry.role, reason, count: entry.count });
+        }
+        return [...merged.values()];
+    }
+}
+function result(bundle, refused, excluded) {
+    return {
+        bundle,
+        refused: refused ? askerReason(refused) : null,
+        excluded: excluded.forAsker(),
+        audit: { refused, excluded: excluded.detailed() },
+    };
+}
+const TEXT_LIMIT = {
+    subject: 'post_chars',
+    parent: 'context_chars',
+    quoted: 'context_chars',
+    reply: 'reply_chars',
+};
+/**
+ * The item for `post`. Each string is cut to its field limit and, for the asked-about post, to what is left of
+ * `budget` (the total limit), in this order: words, title, display name, alt text, stored caption, link card. Other
+ * items pass no budget: one that does not fit the total is left out whole.
+ */
+function buildItem(post, role, limits, excluded, budget = Number.POSITIVE_INFINITY) {
+    let truncated = false;
+    let left = budget;
+    /** A field limit, lowered to what is left of the budget. */
+    const room = (limit) => Math.min(limit, Math.max(0, left));
+    const take = (clean) => {
+        truncated ||= clean.truncated;
+        if (clean.value)
+            left -= textLength(clean.value);
+        return clean.value;
+    };
+    const text = take(paragraphs(post.content, room(limits[TEXT_LIMIT[role]]))) ?? '';
+    const title = take(line(post.title, room(limits.title_chars)));
+    const name = take(line(post.author?.name, room(limits.name_chars)));
+    const media = [];
+    let held = 0;
+    let overLimit = 0;
+    for (const item of Array.isArray(post.media) ? post.media : []) {
+        if (!item || typeof item !== 'object')
+            continue;
+        if (isSet(item.held)) {
+            held += 1;
+            continue;
+        }
+        if (media.length >= limits.max_media) {
+            overLimit += 1;
+            continue;
+        }
+        media.push({ type: mediaType(item.type), alt_text: take(line(item.alt_text, room(limits.alt_text_chars))) });
+    }
+    excluded.add('media', 'media_held', held);
+    excluded.add('media', 'media_limit', overLimit);
+    // The stored caption describes the post's picture: when any of its media is held, it may describe that one.
+    let aiCaption = null;
+    if (held > 0) {
+        if (typeof post.ai_caption === 'string' && post.ai_caption.trim())
+            excluded.add('caption', 'media_held');
+    }
+    else {
+        aiCaption = take(line(post.ai_caption, room(limits.caption_chars)));
+    }
+    let linkCard = null;
+    if (post.link_card && typeof post.link_card === 'object') {
+        const linkTitle = take(line(post.link_card.title, room(limits.link_title_chars)));
+        const description = take(line(post.link_card.description, room(limits.link_description_chars)));
+        // An address is never cut: one that does not fit what is left is left out.
+        let url = webAddress(post.link_card.url);
+        if (url && textLength(url) > left) {
+            url = null;
+            truncated = true;
+        }
+        if (url)
+            left -= textLength(url);
+        if (url || linkTitle || description)
+            linkCard = { url, title: linkTitle, description };
+    }
+    return {
+        role,
+        id: plainId(post.id),
+        author: {
+            id: post.author.id,
+            username: plainHandle(post.author?.username),
+            name,
+        },
+        created_at: isoTime(post.created_at),
+        title,
+        text,
+        media,
+        ai_caption: aiCaption,
+        link_card: linkCard,
+        counts: counts(post.counts),
+        truncated,
+    };
+}
+/** Characters of member-written text in an item: what the total limit counts. */
+export function itemChars(item) {
+    const strings = [item.text, item.title, item.author.name, item.ai_caption, ...item.media.map((media) => media.alt_text)];
+    if (item.link_card)
+        strings.push(item.link_card.url, item.link_card.title, item.link_card.description);
+    return strings.reduce((n, text) => n + (text ? textLength(text) : 0), 0);
+}
+function hasWords(item) {
+    return Boolean(item.text || item.title || item.ai_caption || item.link_card || item.media.some((media) => media.alt_text));
+}
+/** The member-written strings of an item, where an address or a handle may appear. */
+export function itemTexts(item) {
+    const texts = [item.text, item.title, item.author.name, item.ai_caption];
+    for (const media of item.media)
+        texts.push(media.alt_text);
+    if (item.link_card)
+        texts.push(item.link_card.title, item.link_card.description);
+    return texts.filter((text) => typeof text === 'string' && text.length > 0);
+}
+/** Every id, handle and web address the items hold, in order, each once. Never a picture or media address. */
+export function referencesOf(items) {
+    const ids = new Set();
+    const handles = new Set();
+    const urls = new Set();
+    const addUrl = (url) => {
+        if (!isPictureAddress(url))
+            urls.add(url);
+    };
+    for (const item of items) {
+        ids.add(item.id);
+        if (item.author.username)
+            handles.add(item.author.username);
+        if (item.link_card?.url)
+            addUrl(item.link_card.url);
+        for (const text of itemTexts(item)) {
+            for (const handle of findHandles(text))
+                handles.add(handle);
+            for (const url of findUrls(text))
+                addUrl(url);
+        }
+    }
+    return { ids: [...ids], handles: [...handles], urls: [...urls] };
+}
+/**
+ * What an assistant may read about `input.post`, with its parent, quoted post and replies, for this asker in this
+ * mode. See the module comment for the rules.
+ */
+export function buildSubjectBundle(input) {
+    if (!input || typeof input !== 'object')
+        throw new TypeError('buildSubjectBundle needs an input object');
+    const asker = input.asker;
+    if (!asker || typeof asker.id !== 'string' || !asker.id)
+        throw new TypeError('buildSubjectBundle needs asker.id');
+    if (!input.post || typeof input.post !== 'object')
+        throw new TypeError('buildSubjectBundle needs the post');
+    const mode = input.mode === 'sealed' ? 'sealed' : 'standard';
+    const rules = {
+        mode,
+        askerId: asker.id,
+        walls: new Set([
+            ...toSet(asker.blocked_ids, 'blocked_ids'),
+            ...toSet(asker.muted_ids, 'muted_ids'),
+            ...toSet(asker.blocked_by_ids, 'blocked_by_ids'),
+        ]),
+    };
+    const limits = resolveLimits(input.limits);
+    const excluded = new Exclusions();
+    const refused = ruleOut(input.post, rules);
+    if (refused) {
+        excluded.add('subject', refused);
+        return result(null, refused, excluded);
+    }
+    const seen = new Set();
+    // The asked-about post is always kept, cut to fit the total; what follows it is added only while it fits.
+    const subject = buildItem(input.post, 'subject', limits, excluded, limits.total_chars);
+    seen.add(subject.id);
+    let chars = itemChars(subject);
+    /** The item for `post` in `role`, or null with the reason counted. */
+    const admit = (post, role) => {
+        const reason = ruleOut(post, rules);
+        if (reason) {
+            excluded.add(role, reason);
+            return null;
+        }
+        const id = plainId(post.id);
+        if (seen.has(id)) {
+            excluded.add(role, 'duplicate');
+            return null;
+        }
+        const item = buildItem(post, role, limits, excluded);
+        if (!hasWords(item)) {
+            excluded.add(role, 'empty');
+            return null;
+        }
+        const size = itemChars(item);
+        if (chars + size > limits.total_chars) {
+            excluded.add(role, 'size_limit');
+            return null;
+        }
+        seen.add(id);
+        chars += size;
+        return item;
+    };
+    const parent = input.parent ? admit(input.parent, 'parent') : null;
+    const quoted = input.quoted ? admit(input.quoted, 'quoted') : null;
+    const replies = [];
+    for (const reply of Array.isArray(input.replies) ? input.replies : []) {
+        // Rules first, so a left-out reply never takes one of the kept places.
+        const reason = ruleOut(reply, rules);
+        if (reason) {
+            excluded.add('reply', reason);
+            continue;
+        }
+        if (replies.length >= limits.max_replies) {
+            excluded.add('reply', 'reply_limit');
+            continue;
+        }
+        const item = admit(reply, 'reply');
+        if (item)
+            replies.push(item);
+    }
+    const items = [subject, ...(parent ? [parent] : []), ...(quoted ? [quoted] : []), ...replies];
+    const bundle = {
+        version: 1,
+        mode,
+        subject,
+        parent,
+        quoted,
+        replies,
+        references: referencesOf(items),
+        chars,
+    };
+    return result(bundle, null, excluded);
+}