@recursiv/sdk 0.7.81 → 0.7.83

package/dist/assistant/types.d.ts

@@ -0,0 +1,353 @@
+/**
+ * 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 and alt text 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: its alt text and the post's stored caption are left out. Server-side input,
+     * like the post's hold. Any value but `false`, `null` or absent counts as set.
+     */
+    held?: boolean | 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;
+}
+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;
+}
+/**
+ * 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. */
+    user: string;
+    /** `system` and `user` as one message, for a path that sends one. */
+    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.
+     */
+    references: BundleReferences;
+}
+/** 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';

package/dist/assistant/types.js

@@ -0,0 +1,11 @@
+/**
+ * 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'];

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;

package/dist/assistant-surfaces.js

@@ -0,0 +1,113 @@
+/**
+ * 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 const ASSISTANT_SURFACE_IDS = [
+    // The G glyph on a post (feed, post page, network or bridged post, clip, article, story), with its long-press item
+    // and screen-reader action. G3.
+    'post_button',
+    // The answer sheet: the answer streamed in place (bottom sheet on phones, right rail on desktop), its chips and
+    // follow-ups. G11 (G3's interim sheet rides it too).
+    'answer_sheet',
+    // "Ask about these results" on a question-shaped search, and the Cmd-K ask. G4; answers G23a.
+    'search_row',
+    // The glyph in the top bar that opens the assistant tab. G4.
+    'top_bar',
+    // The assistant's one row in the Chat inbox. G4.
+    'inbox_row',
+    // Mentioning the assistant in a reply (the `ai:george` chip), raw `@askgeorge` routing, and the push that an answer
+    // is ready. G22.
+    'mentions',
+    // Asking about picked messages in an ordinary (not encrypted) DM or group chat, and mentioning the assistant in a
+    // small closed group chat. G20.
+    'chats',
+    // Asking the Sealed assistant about one message in an encrypted chat, on the phone only. G21.
+    'e2ee_asks',
+    // "Catch me up" in a group's (community's) header. G24.
+    'groups_catch_up',
+    // "Translate" under a post in another language. G23a (on-device G25).
+    'translate',
+    // The compose chip: check tone, shorten, fix spelling, translate, draft a reply. G23a.
+    'compose',
+    // "About this account": the facts card on a profile, with no model call. G23a.
+    'profile_facts',
+    // "Why am I seeing this" on a feed post, and asking the assistant to explain it. G28.
+    'why_seeing',
+    // The opt-in daily brief and routines. G30.
+    'daily_brief',
+    // Context notes the assistant drafts and people rate. G31.
+    'notes',
+    // The assistant tab itself: thread list, new chat, the chat screen. G13.
+    'george_tab',
+    // Sealed chats inside the assistant tab, on the phone. G15b.
+    'sealed_in_tab',
+    // "Summarise replies" on a thread with 10 or more replies. G11.
+    'thread_summary',
+    // Ask and Quote on selected text (web selection popover G11; phone apps G32).
+    'selection',
+    // "What's going on" on a topic bar or Today story. G23a.
+    'topic_catch_up',
+    // "Describe" on a picture in the media viewer. G23b, only after the upload checks are live.
+    'describe_image',
+    // "Suggest alt text" for your own picture in compose. G23b, only after the upload checks are live.
+    'alt_text',
+    // "Tell the assistant what you want more or less of" in feed settings. G29.
+    'feed_steering',
+    // Sharing an answer as your own post. G27, not before 2026-11-04.
+    'share_answer',
+];
+const SURFACE_IDS = new Set(ASSISTANT_SURFACE_IDS);
+/** True for a surface id this SDK knows. */
+export function isAssistantSurfaceId(value) {
+    return typeof value === 'string' && SURFACE_IDS.has(value);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The surfaces map inside `settings`, which may be a response's `data` (carrying `assistant.surfaces`) or its
+ * `assistant` block (carrying `surfaces`). Null when there is none to read.
+ */
+function surfacesIn(settings) {
+    if (!isPlainObject(settings))
+        return null;
+    if (Object.hasOwn(settings, 'assistant')) {
+        const assistant = settings.assistant;
+        return isPlainObject(assistant) && isPlainObject(assistant.surfaces) ? assistant.surfaces : null;
+    }
+    return isPlainObject(settings.surfaces) ? settings.surfaces : null;
+}
+/**
+ * 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 function assistantSurfaceOn(settings, id) {
+    if (!isAssistantSurfaceId(id))
+        return false;
+    const surfaces = surfacesIn(settings);
+    return !!surfaces && Object.hasOwn(surfaces, id) && surfaces[id] === true;
+}
+/** Every known surface with its switch, read from `settings` by the same rule as {@link assistantSurfaceOn}. */
+export function assistantSurfaces(settings) {
+    const out = {};
+    for (const id of ASSISTANT_SURFACE_IDS)
+        out[id] = assistantSurfaceOn(settings, id);
+    return out;
+}

package/dist/index.d.ts

@@ -165,9 +165,10 @@ export { POSTS_BATCH_MAX, PostsResource } from './resources/posts.js';
 export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason, PostBatch, PostBatchItem } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
-export { ChatResource } from './resources/chat.js';
+export { ChatResource, CHAT_ATTACHMENT_REF_PREFIX, chatAttachmentKeysIn, chatAttachmentRefsIn } from './resources/chat.js';
+export type { ChatAttachmentRef, ChatAttachmentUploadInput, ChatAttachmentUploadUrl, ChatAttachmentUploadUrlInput, SignedChatAttachment, } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
-export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
+export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eePeerChange, E2eePeerErrorCode, E2eePeerNotJoinedDetails, E2eePeerRealtimeEvent, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS, AGENT_DIRECTORY_SORTS, AGENT_DIRECTORY_MAX_LIMIT } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';
@@ -207,7 +208,7 @@ export type { AppSubscriptionBoostCredit, AppSubscriptionCheckoutResult, AppSubs
 export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayParams, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, CuratorTodayDiscussion, CuratorStoryDiscussion, CuratorStoryLaneOutcome, CuratorStoryMindsPost, CuratorStoryPostItem, CuratorStoryPostPagesOptions, CuratorStoryPostsPage, CuratorStoryPostsParams, CuratorStoryReader, CuratorStorySocialPost, CuratorStoryVolumeLanes, CuratorStoryVolumeMeta, StoryPostNetwork, StoryPostPool, StoryPostSort, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
 export { STORY_POOL_MAX_POSTS, STORY_POST_NETWORKS, STORY_POSTS_PAGE_MAX } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
-export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
+export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, ReportedMessageAttachment, ReportedMessageAttachments, } from './resources/reports.js';
 export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgments.js';
 export type { JudgmentSubjectKind, JudgmentSource, JudgmentOverrideMethod, PostLabelsStatus, PostLabelsQuery, PostLabelsSubject, PostLabelsCategory, PostLabelsPolitics, PostJudgmentRecord, PostJudgment, PostSafetyAttribution, PostLabelsCategoryView, PostLabelsSummaryView, PostLabelsFullView, PostLabels, DisputeJudgmentInput, JudgmentDispute, ReviewJudgmentInput, JudgmentReviewUpheld, JudgmentReviewAwaitingReviewer, JudgmentReviewOverridden, JudgmentReview, JudgmentSharedWordsDetails, JudgmentSharedWordsError, } from './resources/judgments.js';
 export { ModerationResource } from './resources/moderation.js';
@@ -225,7 +226,7 @@ export type { SignalBatchResult, SignalEventInput, SignalEventType, SignalNotRec
 export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
 export type { SealedAllowance, SealedAttestationInput, SealedConfig, SealedModel, SealedSendInput, SealedTarget, SealedTargetKind, SealedTransportErrorCode, } from './resources/sealed.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';
-export type { LinkPreview, LinkPreviewResponse, } from './resources/link-preview.js';
+export type { LinkPreview, LinkPreviewResponse, LinkPreviewSource, } from './resources/link-preview.js';
 export type { AgentCapabilityConsentRequirement, AgentCapabilityDataSensitivity, AgentCapabilityDomain, AgentCapabilityExportBoundary, AgentCapabilityRetentionClass, AgentCapabilitySubdomain, AgentCapabilitySubject, AgentCapabilityTrustTier, AgentToolAudience, AgentToolScope, BrowserUseRunTaskInput, ProjectBrainSettings, ProjectToolBundleClassification, ProjectToolBundleKey, ProjectToolPermission, ProjectToolPermissionOverrides, UpdateProjectSettingsInput, } from './resources/project-brain.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';
@@ -269,3 +270,6 @@ export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';
 export type * from './types.js';
 export type { PrepareHostedServiceInput, HostedServiceScope, HostedServiceOperation, HostedServiceReservation, HostedServiceObservation } from './resources/deployments.js';
+export { ASSISTANT_SURFACE_IDS, assistantSurfaceOn, assistantSurfaces, isAssistantSurfaceId, } from './assistant-surfaces.js';
+export type { AssistantSettings, AssistantSettingsUpdate, AssistantSurfaceId, AssistantSurfaces, } from './assistant-surfaces.js';
+export type { CurrentUser } from './resources/users.js';

package/dist/index.js

@@ -236,7 +236,7 @@ export { AuthResource } from './resources/auth.js';
 export { POSTS_BATCH_MAX, PostsResource } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
-export { ChatResource } from './resources/chat.js';
+export { ChatResource, CHAT_ATTACHMENT_REF_PREFIX, chatAttachmentKeysIn, chatAttachmentRefsIn } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS, AGENT_DIRECTORY_SORTS, AGENT_DIRECTORY_MAX_LIMIT } from './resources/agents.js';
@@ -302,3 +302,4 @@ export { MediaResource } from './resources/media.js';
 export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, EmailNotSentError, } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';
+export { ASSISTANT_SURFACE_IDS, assistantSurfaceOn, assistantSurfaces, isAssistantSurfaceId, } from './assistant-surfaces.js';

package/dist/realtime.d.ts

@@ -1,6 +1,6 @@
 import type { Socket } from 'socket.io-client';
 import { HttpClient } from './client.js';
-import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
+import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eePeerRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
 import type { ChatConversationEvent, ChatMembersEvent } from './types.js';
 export interface ChatMessageEvent {
     id: string;
@@ -150,8 +150,8 @@ export declare class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
-     * `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link`,
+     * `e2ee:devices` and `e2ee:peer`.
      */
     on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
     /** Join a conversation room now, and again after every reconnect, until you leave it. */
@@ -199,4 +199,11 @@ export declare class RealtimeClient {
      * `{ deviceId, reason: 'revoked' }`.
      */
     onE2eeDevices(callback: (event: E2eeDevicesRealtimeEvent) => void): () => void;
+    /**
+     * Someone this account shares an encrypted conversation with reset encrypted
+     * chat: `{ userId, reason: 'root_changed', conversationId }`, once per shared
+     * conversation. Look at their devices again (`r.e2ee.devices({ user_id })`);
+     * catch up with `r.e2ee.peerChanges()` after time in the background.
+     */
+    onE2eePeer(callback: (event: E2eePeerRealtimeEvent) => void): () => void;
 }

package/dist/realtime.js

@@ -369,8 +369,8 @@ export class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
-     * `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link`,
+     * `e2ee:devices` and `e2ee:peer`.
      */
     on(event, listener) {
         // Every call is its own subscription, even for a function that is already
@@ -473,4 +473,13 @@ export class RealtimeClient {
     onE2eeDevices(callback) {
         return this.on('e2ee:devices', callback);
     }
+    /**
+     * Someone this account shares an encrypted conversation with reset encrypted
+     * chat: `{ userId, reason: 'root_changed', conversationId }`, once per shared
+     * conversation. Look at their devices again (`r.e2ee.devices({ user_id })`);
+     * catch up with `r.e2ee.peerChanges()` after time in the background.
+     */
+    onE2eePeer(callback) {
+        return this.on('e2ee:peer', callback);
+    }
 }

package/dist/resources/agents.d.ts

@@ -234,7 +234,10 @@ export declare class AgentsResource {
     }>;
     /** Delete an agent */
     delete(id: string): Promise<DeleteResponse>;
-    /** Send a message to an agent (async — agent responds asynchronously) */
+    /**
+     * Send a message to an agent (async — agent responds asynchronously).
+     * `turn: { safe: true }` makes it a safe turn in the caller's Asks thread (see `AgentChatTurn`).
+     */
     chat(id: string, input: AgentChatInput): Promise<SingleResponse<AgentChatResult>>;
     /** List an agent's conversations */
     conversations(id: string, params?: PaginationParams): Promise<PaginatedResponse<AgentConversation>>;
@@ -398,6 +401,8 @@ export declare class AgentsResource {
      *
      * Requires `ReadableStream` support (Node.js, modern browsers).
      * For React Native, use `chatStreamText()` instead.
+     * `turn: { safe: true }` streams a safe turn in the caller's Asks thread (see `AgentChatTurn`); a refusal throws a
+     * `RecursivError` whose code is a `SafeTurnRefusalCode`, before anything streams.
      */
     chatStream(id: string, input: AgentChatInput): AsyncGenerator<StreamChunk>;
     /**