@recursiv/sdk 0.7.82 → 0.7.89

package/dist/assistant/types.d.ts

@@ -0,0 +1,569 @@
+/**
+ * Types for `@recursiv/sdk/assistant`: the subject bundle (what an assistant may read about a post) and its rendering
+ * as model input. Plain data only, so the same values pass between the server, a phone and a stored snapshot.
+ *
+ * Some inputs are facts other members must never learn: whether an author is a known minor, whether a post is under a
+ * child-safety hold or suppressed, and who blocked the asker. They are marked "server-side input". The server reads
+ * them and never sends them to another member's client; a client that builds a bundle passes each post's
+ * `assist_readable` instead, the server's verdict for that viewer, which does not say why.
+ */
+/**
+ * What an author chose for asks about their posts (S22): asks in every mode, Sealed asks only, or none. A server from
+ * before the granular choice sends a boolean (`true` for 'all', `false` for 'off') or nothing.
+ */
+export type AiAskAllowed = 'all' | 'sealed_only' | 'off';
+/** Where an ask runs: 'standard' through the platform's server, 'sealed' from the phone to a checked model server. */
+export type AssistantMode = 'standard' | 'sealed';
+/** What the member asked for. Every intent is text only for now: pictures go as their alt text and stored caption. */
+export type AssistIntent = 'explain' | 'summarise' | 'fact_context' | 'translate' | 'describe';
+export declare const ASSIST_INTENTS: readonly AssistIntent[];
+export interface SubjectAuthorInput {
+    id: string;
+    /** The handle, with or without its leading @. A federated handle may carry its server (`alice@example.social`). */
+    username?: string | null;
+    /** The display name. Written by the author, so it is rendered as their text, never as a label. */
+    name?: string | null;
+    /**
+     * Server-side input: the platform knows this account belongs to someone under 18. Never send it to another member's
+     * client (it would make children findable); a client leaves it out and passes the post's `assist_readable`. Any
+     * value but `false`, `null` or absent counts as set.
+     */
+    known_minor?: boolean | null;
+}
+/**
+ * One picture, clip or sound on a post. Only its type, its alt text, `held`, and for pictures its plain id and
+ * `checked_at` are read: an address or the bytes, if the caller's object carries them, are never copied into the bundle.
+ */
+export interface SubjectMediaInput {
+    type?: string | null;
+    /** What the author wrote for it. */
+    alt_text?: string | null;
+    /**
+     * Under a child-safety hold or reported: the builder leaves out its alt text, and the post's stored caption, which may
+     * describe it. Any value but `false`, `null` or absent counts as set. `true` is server-side, like the post's hold:
+     * never send it to another member's client. A server leaves held media out of that payload, and leaves out the
+     * post's stored caption (`ai_caption`) whenever any of its media is held: a client builder cannot see media it was
+     * never sent, so it keeps whatever caption the payload carries. `false` is also the payload's "not held" mark
+     * (sealed-full-scope-v1 2.1): a picture goes to a model as a picture only when `held` is exactly `false`, so pass
+     * it through from the payload. Absent or null still goes as alt text, but never as a picture.
+     */
+    held?: boolean | null;
+    /**
+     * The media's id in the post payload (`media[].id`), so a caller that renders with pictures can find the picture in
+     * its own image cache. Kept for pictures only, and only when it is a plain id: never an address.
+     */
+    id?: string | null;
+    /**
+     * When Minds last matched this picture against the child-safety hash lists (the post payload's `media[].checked_at`,
+     * sealed-full-scope-v1 2.1, gate P1): an ISO time with its zone, written only by the server. Kept only when `held`
+     * is exactly `false`. A picture can go to a model as a picture only while this is under 24 hours old by the
+     * renderer's clock; absent, not an ISO time with its zone, or without `held: false`, means alt text and the stored
+     * caption only, as for every other picture.
+     */
+    checked_at?: string | null;
+}
+export interface SubjectLinkCardInput {
+    url?: string | null;
+    title?: string | null;
+    description?: string | null;
+}
+export interface SubjectCountsInput {
+    votes?: number | null;
+    upvotes?: number | null;
+    downvotes?: number | null;
+    replies?: number | null;
+    reposts?: number | null;
+}
+/** A post, reply, parent or quoted post as the caller holds it. */
+export interface SubjectPostInput {
+    id: string;
+    author: SubjectAuthorInput | null;
+    title?: string | null;
+    content?: string | null;
+    /** An ISO time with its zone ("2026-10-01T14:05:00Z"). A time without one is left out. */
+    created_at?: string | null;
+    media?: readonly SubjectMediaInput[] | null;
+    /** The description the platform stored for the post's picture. */
+    ai_caption?: string | null;
+    /** The card the caller already read for the post's link. Nothing is fetched. */
+    link_card?: SubjectLinkCardInput | null;
+    counts?: SubjectCountsInput | null;
+    /** The author's choice (S22). Absent means the default, 'all'; a value this SDK does not know means 'off'. */
+    ai_ask_allowed?: AiAskAllowed | boolean | null;
+    /**
+     * Server-side input: under a child-safety hold (CS-P0-5). Never send it to another member's client, the author's
+     * included (it would warn them); a client passes `assist_readable`. Any value but `false`, `null` or absent counts
+     * as set, so a hold record, a time, `1` or `'t'` all leave the post out.
+     */
+    child_safety_hold?: boolean | null;
+    /** Server-side input: a moderator turned the assistant off for this post. Read like `child_safety_hold`. */
+    assistant_suppressed?: boolean | null;
+    /**
+     * The server's verdict for this viewer (from `readPostForViewer`), for a builder on a client: it folds in the
+     * author's choice, a hold, suppression, a known-minor author and a block by the author, and does not say which.
+     * 'sealed_only' comes only from the author's choice. Absent means no verdict (the other fields decide); a value this
+     * SDK does not know means 'none'. It holds whoever asks, the author included.
+     */
+    assist_readable?: AssistReadable | null;
+}
+/** What the server says this viewer's assistant may read of a post: all of it, in Sealed only, or nothing. */
+export type AssistReadable = 'all' | 'sealed_only' | 'none';
+/** A list of account ids: an array or a set. A single id as a bare string is refused, never read letter by letter. */
+export type AccountIds = readonly string[] | ReadonlySet<string>;
+/**
+ * Who is asking. A list that is present but cannot be read (a string, a plain object, a Promise, a Map, an entry
+ * that is not an id) throws a TypeError rather than counting as empty. A number in a list is read as its decimal string.
+ */
+export interface SubjectAsker {
+    id: string;
+    /** Accounts the asker blocked. */
+    blocked_ids?: AccountIds | null;
+    /** Accounts the asker muted. */
+    muted_ids?: AccountIds | null;
+    /**
+     * Server-side input: accounts that blocked the asker. Never send this list to the asker's client; a client leaves
+     * it out (the server already hides those accounts' posts from the asker, and `assist_readable` folds it in).
+     */
+    blocked_by_ids?: AccountIds | null;
+}
+export interface SubjectBundleLimits {
+    /** Replies kept, in the order given (top first). */
+    max_replies: number;
+    /** Pictures, clips and sounds kept per item. */
+    max_media: number;
+    /** Characters of the asked-about post's words. */
+    post_chars: number;
+    /** Characters of the parent's or quoted post's words. */
+    context_chars: number;
+    /** Characters of one reply's words. */
+    reply_chars: number;
+    title_chars: number;
+    name_chars: number;
+    alt_text_chars: number;
+    caption_chars: number;
+    link_title_chars: number;
+    link_description_chars: number;
+    /**
+     * Characters across the bundle; `chars` never passes it. The asked-about post is always kept, its strings cut to fit
+     * (words first, then title, display name, alt text, stored caption and link card); a parent, quoted post or reply
+     * that would take the total past it is left out whole.
+     */
+    total_chars: number;
+}
+export interface BuildSubjectBundleInput {
+    mode: AssistantMode;
+    asker: SubjectAsker;
+    /** The post the member asked about. */
+    post: SubjectPostInput;
+    /** The post it replies to. */
+    parent?: SubjectPostInput | null;
+    /** The post it quotes or reposts. */
+    quoted?: SubjectPostInput | null;
+    /** Replies the asker can see, top first. */
+    replies?: readonly SubjectPostInput[] | null;
+    /** Lower limits. A value above the default is held at the default. */
+    limits?: Partial<SubjectBundleLimits> | null;
+}
+export type BundleItemRole = 'subject' | 'parent' | 'quoted' | 'reply';
+export interface BundleMedia {
+    type: 'image' | 'video' | 'audio' | 'other';
+    alt_text: string | null;
+    /** Pictures only: the media's id, when the input had a plain one. Never written into model input. */
+    id?: string;
+    /**
+     * Pictures only: Minds' last child-safety check of it (ISO time, UTC), when the input had a valid one and marked the
+     * picture not held (`held: false`).
+     */
+    checked_at?: string;
+}
+export interface BundleCounts {
+    votes?: number;
+    upvotes?: number;
+    downvotes?: number;
+    replies?: number;
+    reposts?: number;
+}
+export interface BundleLinkCard {
+    url: string | null;
+    title: string | null;
+    description: string | null;
+}
+export interface BundleItem {
+    role: BundleItemRole;
+    id: string;
+    author: {
+        id: string;
+        /** Without the @. Null when the handle was missing or not a plain handle. */
+        username: string | null;
+        name: string | null;
+    };
+    /** ISO time (UTC), or null. */
+    created_at: string | null;
+    title: string | null;
+    text: string;
+    media: BundleMedia[];
+    ai_caption: string | null;
+    link_card: BundleLinkCard | null;
+    counts: BundleCounts | null;
+    /** Some of this item's text was cut to fit a limit. */
+    truncated: boolean;
+}
+/**
+ * Every id, handle (without the @) and web address the content holds: all an answer may cite or link. No picture or
+ * media address is ever listed (by file type, or a known media host or path such as cdn.minds.com or /fs/v1/), and
+ * picture addresses in members' text are replaced by "[link to a picture]". An answer may write these addresses only
+ * as plain links: the output filter must never render an image the model wrote, whatever its address.
+ */
+export interface BundleReferences {
+    ids: string[];
+    handles: string[];
+    urls: string[];
+}
+export interface SubjectBundle {
+    version: 1;
+    mode: AssistantMode;
+    subject: BundleItem;
+    parent: BundleItem | null;
+    quoted: BundleItem | null;
+    replies: BundleItem[];
+    references: BundleReferences;
+    /** Characters (code points) of member-written text across the bundle: never more than `limits.total_chars`. */
+    chars: number;
+}
+/**
+ * Why something was left out, as the asker may be told it. 'unavailable' covers a block or mute in either direction,
+ * a known-minor author, a child-safety hold (on the post or one of its pictures), moderator suppression and a
+ * server's 'none' verdict alike, so neither `refused` nor a count says which. The asker knows whom they blocked or
+ * muted, so a reason of its own for blocks would name who blocked them; one for minors or holds would tell anyone
+ * whose account is a child's, or warn a poster that their post is held. The author's own choice is theirs to show.
+ */
+export type ExclusionReason = 'unavailable' | 'author_opted_out' | 'author_sealed_only' | 'unknown_author' | 'invalid' | 'duplicate' | 'empty' | 'reply_limit' | 'media_limit' | 'size_limit';
+/** The detail behind 'unavailable'. Server log only: never sent to the asker or to any member's client. */
+export type UnavailableReason = 'child_safety_hold' | 'moderator_suppressed' | 'blocked_or_muted' | 'known_minor_author' | 'media_held' | 'not_readable';
+export type DetailedExclusionReason = Exclude<ExclusionReason, 'unavailable'> | UnavailableReason;
+export type ExclusionRole = BundleItemRole | 'media' | 'caption';
+/** How many of one kind were left out, and why. Counts only: never an id or a handle. */
+export interface SubjectExclusion {
+    role: ExclusionRole;
+    reason: ExclusionReason;
+    count: number;
+}
+export interface DetailedExclusion {
+    role: ExclusionRole;
+    reason: DetailedExclusionReason;
+    count: number;
+}
+export interface SubjectBundleResult {
+    /** Null when the asked-about post itself may not be read: make no model call. */
+    bundle: SubjectBundle | null;
+    /**
+     * Why the asked-about post may not be read, as the asker may be told it. Show 'unavailable' the same way as an
+     * error ("this post can't be read right now"): to an author asking about their own post it can only mean a hold or
+     * suppression.
+     */
+    refused: ExclusionReason | null;
+    /**
+     * What was left out, as the asker may be told it. Show the asker a total at most: on a thread with one or two
+     * replies a count per reason can still point at one reply.
+     */
+    excluded: SubjectExclusion[];
+    /**
+     * The same with the detail behind 'unavailable', for the server's own log. Never send it to the asker or to any
+     * member's client, and never into a stored snapshot a client reads.
+     */
+    audit: {
+        refused: DetailedExclusionReason | null;
+        excluded: DetailedExclusion[];
+    };
+}
+export interface RenderBundleOptions {
+    /**
+     * A fresh random string for this call alone (16 to 128 letters, digits, '-' or '_'), from the caller's random
+     * source: 32 hex digits from `crypto.getRandomValues` will do. It marks where the untrusted content starts and ends.
+     */
+    boundary: string;
+    /** For 'translate': the language to translate into, as a BCP 47 tag ('es', 'pt-BR'). */
+    language?: string | null;
+    /**
+     * Attach post pictures as pictures (sealed-full-scope-v1 2.1 and 2.2). Without it, or when no picture qualifies,
+     * every picture goes as its alt text and the stored caption only, and the output is exactly as before.
+     */
+    pictures?: RenderPictureOptions | null;
+}
+/** A post picture in a bundle that may go to the model as a picture: see `bundlePictures`. */
+export interface BundlePicture {
+    /** The id of the item the picture is on. */
+    item_id: string;
+    /** Where that item sits: the asked-about post, its parent or its quote. A reply's pictures never go as pictures. */
+    role: Exclude<BundleItemRole, 'reply'>;
+    /** The picture's id in the post payload: find its bytes in your image cache by this. */
+    media_id: string;
+    /** Which picture of its item it is, from 1, as the content numbers them ("picture 2 alt text"). */
+    number: number;
+    /** Minds' last child-safety check of it (ISO time, UTC), from the bundle, for your own freshness check. */
+    checked_at: string;
+}
+export interface BundlePictureOptions {
+    /** Your clock, in milliseconds since 1970 UTC, or a Date. The renderer reads no clock of its own. */
+    now: number | Date;
+    /**
+     * How many post pictures this message still has room for: 3 (the per-message limit, sealed-full-scope-v1 2.2) minus
+     * the pictures from the phone it carries (`Math.max(0, 3 - phonePictures)`). A whole number; above 3 counts as 3;
+     * absent means 3; below 0 throws. Pass the same value to bundlePictures and renderBundleForModel.
+     */
+    max?: number | null;
+}
+export interface RenderPictureOptions extends BundlePictureOptions {
+    /**
+     * The pictures you approved: the list bundlePictures gave you, less any your own checks left out. The renderer
+     * attaches only a picture on this list that still qualifies at `now`, so a picture left out here, or one that went
+     * stale since, goes as alt text only, and no other picture takes its place. Read `now` again for this call
+     * (`Date.now()` after your checks): a later clock can only take pictures away.
+     */
+    allowed: readonly BundlePicture[];
+    /**
+     * The picture's bytes from your own image cache: the base64 of a JPEG already prepared on this device (shrunk,
+     * re-encoded, metadata stripped; sealed-full-scope-v1 2.2), or null when it has not loaded. Never fetch here: a
+     * picture that has not loaded is not sent. Anything but base64 JPEG bytes, or a throw, means that picture goes as alt
+     * text only. Asked only for pictures on `allowed`. Prepare first, then check: return exactly the prepared bytes your
+     * checks passed for this picture, never a second read of the cache (an entry replaced in between would send a picture
+     * nobody checked, and the raw cached file still carries its metadata). The renderer can tell only that the bytes look
+     * like a JPEG, not that they were prepared.
+     */
+    cached: (picture: BundlePicture) => string | null | undefined;
+}
+/** One part of the user message, in the chat-completions content-part shape. */
+export type RenderedUserPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+};
+/**
+ * A rendered bundle. Render only a bundle this process built from its own reads: the renderer re-checks every field
+ * it writes outside a member line and throws on one that does not fit, but a bundle a client sent has skipped every
+ * exclusion rule, so a server never renders one.
+ */
+export interface RenderedBundle {
+    /** Fixed instructions written by the renderer: trusted, for the system role. */
+    system: string;
+    /**
+     * The delimited content, then the task again: for the user role. Words only: when `pictures` is not empty it still
+     * says which pictures are attached but cannot carry them, so send `user_parts` instead.
+     */
+    user: string;
+    /**
+     * `system` and `user` as one message, for a path that sends one. Only when `pictures` is empty: it names the
+     * attached pictures but cannot carry them.
+     */
+    text: string;
+    /**
+     * What the rendered content holds: an answer may cite or link these and nothing else, and only as plain links (see
+     * BundleReferences): never render an image the model wrote. Never a picture's address or bytes, attached or not.
+     */
+    references: BundleReferences;
+    /** The pictures attached as image parts, in order: empty unless `pictures` was given and one qualified. */
+    pictures: BundlePicture[];
+    /**
+     * The user message as content parts, for a request that takes pictures: the content's opening line and its text,
+     * then each attached picture as an image part (a `data:image/jpeg;base64,` address, never a web address), then the
+     * content's closing line and the task again, so the pictures sit inside the delimited block. Its text parts, joined
+     * with a line break, are `user`. With no picture attached it is one text part holding `user`.
+     */
+    user_parts: RenderedUserPart[];
+}
+/** Which fixed card a message calls for. */
+export type FixedCardKind = 'election' | 'crisis';
+/** The languages the matcher reads and the cards are written in. */
+export type FixedCardLanguage = 'en' | 'es';
+export declare const FIXED_CARD_LANGUAGES: readonly FixedCardLanguage[];
+export interface FixedCardOptions {
+    /**
+     * The member's country, as an ISO 3166-1 alpha-2 code ('US', 'mx'), when the caller knows it: from the profile or
+     * the request's edge country header. Unknown or absent gives the generic card, which names no country's line but
+     * the US one, labelled as such.
+     */
+    country?: string | null;
+    /**
+     * The member's app language, as a BCP 47 tag ('es-MX'). The card is written in the language the message matched
+     * in; this decides only when it matched in both, or for `fixedCardFor`, which reads no message.
+     */
+    locale?: string | null;
+}
+/** A number to call or text, as the card shows it. */
+export interface FixedCardPhone {
+    /** Who answers, by the service's own name. */
+    name: string;
+    /** As the service writes it. */
+    number: string;
+    /** What a phone dials, for a `tel:` link: digits, with a leading `*` kept. */
+    dial: string;
+    /** The number to text, or null when the line takes calls only. */
+    text: string | null;
+    /** Emergency services rather than a helpline. */
+    emergency: boolean;
+    /** Where the number was checked. */
+    sources: string[];
+}
+/** An official site the card links to. */
+export interface FixedCardLink {
+    label: string;
+    url: string;
+    /** Where the address was checked. */
+    sources: string[];
+}
+/**
+ * A fixed card: short, plain, the same every time for the same country and language, and written by people, not a
+ * model. Every number and address in `lines` is also in `phones` or `links`, with its sources.
+ */
+export interface FixedCard {
+    kind: FixedCardKind;
+    /**
+     * Stable: 'crisis.US', 'crisis.generic', 'election.MX', 'election.generic'. A crisis card may add '.danger' (danger
+     * from someone else or a medical emergency: it leads with the emergency number, the police where that is a separate
+     * number) or '.other' (worry about someone else: its line speaks to the helper).
+     */
+    id: string;
+    /** The country the card is for, or null for the generic card. */
+    country: string | null;
+    language: FixedCardLanguage;
+    title: string;
+    /** What the card says, in order, one short sentence or two per line. */
+    lines: string[];
+    phones: FixedCardPhone[];
+    links: FixedCardLink[];
+    /** The day the numbers and addresses were last checked against their sources (YYYY-MM-DD). */
+    as_of: string;
+}
+/** What a message calls for. It names no phrase that matched: the words a member wrote stay with the caller. */
+export interface FixedCardMatch {
+    kind: FixedCardKind;
+    card: FixedCard;
+}
+/**
+ * What the turn does after the card: 'card_only' shows the card instead of a model answer (no model call);
+ * 'card_then_answer' shows the card first, then the turn may go on to a model answer.
+ */
+export type FixedCardAnswer = 'card_only' | 'card_then_answer';
+/**
+ * How a message is sent: Sealed alone, or 'both' (D3: the same prompt to Standard and to Sealed, side by side). 'both'
+ * with encrypted-chat messages throws: an encrypted-chat ask is Sealed only (G21).
+ */
+export type SealedTurnMode = 'sealed' | 'both';
+/**
+ * Someone else's content in a Sealed message, by where it came from:
+ * - 'public_post': a post its author made public, as the post in a George ask, an attached post, a quote or a chat's
+ *   subject (G13d);
+ * - 'members_only_post': a post in a group that is not public, in any of those places;
+ * - 'chat_messages': messages picked from a chat;
+ * - 'encrypted_chat': messages from an encrypted chat (G21). Sealed only: with mode 'both' it throws.
+ */
+export type SealedContentKind = 'public_post' | 'members_only_post' | 'chat_messages' | 'encrypted_chat';
+export declare const SEALED_CONTENT_KINDS: readonly SealedContentKind[];
+/**
+ * One Sealed message, as the app is about to send it. Choices that send something (search, memory, the chip, the tick,
+ * About you, Tinfoil's page-open limit) count only when `true`. The six facts the caps cannot see for themselves
+ * (`others_content`, `phone_pictures`, `temporary`, `searched_earlier`, `phone_pictures_earlier`, `earlier_messages`)
+ * are required: absent or null throws, and the four flags count as set for any value but `false`. A `mode`,
+ * `others_content` or `phone_pictures` this function cannot read throws a TypeError, and so does mode 'both' with
+ * 'encrypted_chat' content (G21: Sealed only).
+ */
+export interface SealedTurnInput {
+    mode: SealedTurnMode;
+    /** "Search the web" is on for this chat (the composer's switch). */
+    search?: boolean | null;
+    /**
+     * Someone else's content in this message or anywhere earlier in this chat; a chat's subject counts for every message
+     * in it. Required: pass `[]` for a message of the member's own words only.
+     */
+    others_content: readonly SealedContentKind[];
+    /**
+     * The chat has earlier messages or answers. Required: pass `false` for the first message. It decides the
+     * 'search.question_only' line: a message that searches never carries the chat so far, and the member is told so.
+     */
+    earlier_messages: boolean;
+    /**
+     * A message earlier in this chat searched the web, so George's earlier answers may echo a web page. Required: pass
+     * `false` when none did. It stops memory suggestions (4.2, gate M3); it does not stop search or memory.
+     */
+    searched_earlier: boolean;
+    /**
+     * A message earlier in this chat carried a picture from the phone to Sealed, so George's earlier answers about it,
+     * which stay in the history (2.2), may echo words written in it. Required: pass `false` when none did. It stops
+     * memory suggestions (4.2); it does not stop search or memory.
+     */
+    phone_pictures_earlier: boolean;
+    /** Sealed memory is on (Settings > George > What George remembers, "On this phone"). Off by default. */
+    memory?: boolean | null;
+    /**
+     * The header's Memory chip is on for this chat. Counts only when `others_content` is empty: memory is off in any
+     * ask or chat carrying someone else's content unless the member ticks `memory_tick` (George plan 4.7).
+     */
+    memory_in_chat?: boolean | null;
+    /**
+     * The member ticked "Use what George remembers" for this ask or chat (it starts off). The only thing that sends
+     * memory, or About you, with someone else's content; ignored when `others_content` is empty.
+     */
+    memory_tick?: boolean | null;
+    /** "Use these" is on for the About you fields ("How George talks to you"). */
+    about_you?: boolean | null;
+    /**
+     * How many pictures from the phone are attached: a whole number from 0 to 3 (a message carries at most 3 pictures in
+     * all, sealed-full-scope-v1 2.2, so the composer caps them). Required: pass `0` for none. Absent or null throws, so a
+     * caller that forgot it never searches beside a picture or drops one without its line; more than 3 throws.
+     */
+    phone_pictures: number;
+    /** A temporary Sealed chat. Required: pass `false` for a saved chat. */
+    temporary: boolean;
+    /**
+     * Tinfoil limits page opens for Minds' key to addresses from search results or the member's message
+     * (sealed-full-scope-v1 3.6, ask 3). Defaults to false. Set it only from a server switch, once Tinfoil confirms.
+     */
+    page_opens_limited?: boolean | null;
+}
+/**
+ * Why something the member turned on is off for this message, as the copy id the app shows (sealed-full-scope-v1
+ * 5.1 and 5.2):
+ * - 'search.off_mix': it carries memory, About you or a picture from the phone, so it doesn't search;
+ * - 'search.off_subject': it carries someone else's public post, and Tinfoil doesn't limit page opens yet (ask 3);
+ * - 'search.off_members': it carries a members-only post or picked chat messages, which never search;
+ * - 'search.e2ee': it carries encrypted-chat messages, which never search;
+ * - 'search.question_only': it searches, so it carries only the question, not the chat so far;
+ * - 'both.no_search': a Both message doesn't search;
+ * - 'both.no_photo': a Both message doesn't carry a picture from the phone.
+ */
+export type SealedTurnReason = 'search.off_mix' | 'search.off_subject' | 'search.off_members' | 'search.e2ee' | 'search.question_only' | 'both.no_search' | 'both.no_photo';
+export declare const SEALED_TURN_REASONS: readonly SealedTurnReason[];
+/**
+ * What one Sealed message may carry. Someone else's content in the message itself (the post asked about) always goes.
+ * In a Both message it goes to the Standard half too, an ordinary Minds turn (2.6), whose bundle is built with mode
+ * 'standard' (that leaves out posts whose authors chose Sealed only). So these caps do not keep a public post, a
+ * members-only post or picked chat messages from Standard. Only encrypted-chat content is Sealed only: a Both message
+ * with it throws instead of returning caps.
+ */
+export interface SealedTurnCaps {
+    /** Put `web_search_options`, with both of Tinfoil's filters, in the sealed body, and mark the request as one that may search. */
+    search: boolean;
+    /** Send the chat's earlier messages and George's earlier answers. Never with a message that searches. */
+    history: boolean;
+    /** Send the saved facts, in the sealed body (4.3). */
+    memory: boolean;
+    /** Send the About you fields, in the same system message as the facts. */
+    about_you: boolean;
+    /**
+     * The attached pictures from the phone may go. The picture checks (2.4) still decide each one. Never in Both, and
+     * never with encrypted-chat messages (G21 is one message of words; that surface has no Photo item, so no line).
+     */
+    phone_pictures: boolean;
+    /**
+     * A suggestion tagged in the answer may be offered for saving (4.2, gate M3). Never from a message that may hold
+     * someone else's words: a post, chat messages, this message's search results, a picture from the phone (it may be a
+     * screenshot), or an earlier answer built from a search or about a phone picture.
+     */
+    suggest_memory: boolean;
+    /** Copy ids for what the member turned on that this message leaves off, each once, in a fixed order. */
+    reasons: SealedTurnReason[];
+}

package/dist/assistant/types.js

@@ -0,0 +1,26 @@
+/**
+ * Types for `@recursiv/sdk/assistant`: the subject bundle (what an assistant may read about a post) and its rendering
+ * as model input. Plain data only, so the same values pass between the server, a phone and a stored snapshot.
+ *
+ * Some inputs are facts other members must never learn: whether an author is a known minor, whether a post is under a
+ * child-safety hold or suppressed, and who blocked the asker. They are marked "server-side input". The server reads
+ * them and never sends them to another member's client; a client that builds a bundle passes each post's
+ * `assist_readable` instead, the server's verdict for that viewer, which does not say why.
+ */
+export const ASSIST_INTENTS = ['explain', 'summarise', 'fact_context', 'translate', 'describe'];
+export const FIXED_CARD_LANGUAGES = ['en', 'es'];
+export const SEALED_CONTENT_KINDS = [
+    'public_post',
+    'members_only_post',
+    'chat_messages',
+    'encrypted_chat',
+];
+export const SEALED_TURN_REASONS = [
+    'search.off_mix',
+    'search.off_subject',
+    'search.off_members',
+    'search.e2ee',
+    'search.question_only',
+    'both.no_search',
+    'both.no_photo',
+];

package/dist/assistant-surfaces.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-driven kill switches for the assistant's surfaces (George plan step G7a).
+ *
+ * A flag compiled into a phone app cannot be switched off once that build ships, so every place an app shows the
+ * assistant asks the server first. The switches are the app's project setting `assistant.surfaces`, and they arrive
+ * inside responses the app already fetches: `users.me()` (the boot read) and `network.getConfig()` both carry
+ * `data.assistant.surfaces`. An app's owner or admin changes them with
+ * `projectBrain.updateSettings(projectId, { assistant: { surfaces: { post_button: true } } })`.
+ *
+ * Fail closed: show a surface only when {@link assistantSurfaceOn} says so, which is only for an explicit `true`. A
+ * response from an older server (no `assistant`), a read that failed, a malformed value and an id this SDK does not
+ * know are all off.
+ *
+ * The server keeps the same list (packages/server/src/features/assistant/surfaces.ts); a contract test holds them equal.
+ */
+/**
+ * Every assistant surface an app may show, one switch each. All default off. Step numbers are the George plan's §8.
+ * New ids are appended; an id is never renamed.
+ */
+export declare const ASSISTANT_SURFACE_IDS: readonly ["post_button", "answer_sheet", "search_row", "top_bar", "inbox_row", "mentions", "chats", "e2ee_asks", "groups_catch_up", "translate", "compose", "profile_facts", "why_seeing", "daily_brief", "notes", "george_tab", "sealed_in_tab", "thread_summary", "selection", "topic_catch_up", "describe_image", "alt_text", "feed_steering", "share_answer"];
+export type AssistantSurfaceId = (typeof ASSISTANT_SURFACE_IDS)[number];
+/** Every surface id with its switch, as the API sends it under `assistant.surfaces`. */
+export type AssistantSurfaces = Record<AssistantSurfaceId, boolean>;
+/** The `assistant` block of `users.me()` and `network.getConfig()` (absent on servers from before G7a). */
+export interface AssistantSettings {
+    surfaces: AssistantSurfaces;
+}
+/** A write to the switches: any subset of surface ids, each an explicit boolean. */
+export interface AssistantSettingsUpdate {
+    surfaces: Partial<Record<AssistantSurfaceId, boolean>>;
+}
+/** True for a surface id this SDK knows. */
+export declare function isAssistantSurfaceId(value: unknown): value is AssistantSurfaceId;
+/**
+ * Whether the app may show surface `id`: true only when `settings` holds an explicit `true` for it. `settings` is a
+ * response's `data` (`(await sdk.users.me()).data`, `(await sdk.network.getConfig()).data`) or its `assistant` block.
+ * Anything else is off: no settings (a read that failed, an older server), a malformed value, a non-boolean, an id
+ * this SDK does not know.
+ */
+export declare function assistantSurfaceOn(settings: unknown, id: AssistantSurfaceId | string): boolean;
+/** Every known surface with its switch, read from `settings` by the same rule as {@link assistantSurfaceOn}. */
+export declare function assistantSurfaces(settings: unknown): AssistantSurfaces;