@recursiv/sdk 0.7.121 → 0.7.122

package/dist/sealed-frame/protocol.d.ts

@@ -0,0 +1,493 @@
+/**
+ * The Sealed frame's protocol, version 1: the messages between a host page (minds.com/ai, build.minds.com) and the
+ * Sealed frame it embeds (https://sealed.minds.com), and between a host and the frame's sign-out page (/wipe.html).
+ * Both sides use these types, builders and validators, so there is one definition of what may cross.
+ *
+ * How the two talk (the Sealed frame design of 2026-10-13, section 5):
+ * 1. On every load event of the frame's iframe, the host posts `sealed/hello` with a transferred MessagePort to the
+ *    frame origin only (`targetOrigin`). The frame must add its window message listener as soon as its module runs, and
+ *    accepts the first hello whose `event.origin` is one of its compiled hosts and whose `event.source` is
+ *    `window.parent`. After that both sides use the port only.
+ * 2. The frame answers `ready` on the port, naming the protocol it speaks; a host that speaks another shows "Reload
+ *    the page". Nothing else counts before `ready`.
+ * 3. Host to frame, on the port: `token`, `theme`, `layout`, `account`, `signed-out`, `new-chat`.
+ *    Frame to host, on the port: `need-token`, `state`, `navigate`, `wiped`.
+ *
+ * Every field is an enum, a boolean, an id, a time or the opaque token. Never sent, either way: typed words, answers,
+ * chat ids, titles or counts, failure details, or when sends happen. There are no size messages: the host sizes the
+ * frame with CSS, since a height would say how long the transcript is.
+ *
+ * Every message is checked before it is read. A validator returns a fresh copy holding only the message's own fields,
+ * or null for anything else: a type it does not know, a missing, extra or wrongly typed field, a string outside its
+ * enum or pattern, a getter or symbol key, or a message over 4 KB of JSON. The receiver ignores null. Builders check
+ * their own output the same way and throw a TypeError rather than send a message the other side would drop.
+ */
+/** The protocol this SDK speaks, which `ready` names. */
+export declare const SEALED_FRAME_PROTOCOL = 1;
+/** Every message's format version (`v`). */
+export declare const SEALED_FRAME_MESSAGE_VERSION = 1;
+/** The most a message may be, as UTF-8 JSON. Anything larger is dropped unread. */
+export declare const SEALED_FRAME_MESSAGE_MAX_BYTES = 4096;
+/**
+ * The frame's iframe sandbox. It protects the host, not the frame: the frame's protection is the same-origin policy and
+ * its own CSP. `allow-same-origin` keeps the frame's own storage; popups let crisis and help links open in a new tab.
+ * There is no `allow-forms`, in line with the frame CSP's `form-action 'none'`: embedded, the browser stops a form
+ * submission before its `submit` event fires, so the frame must not use `<form>` submission (handle Enter and the send
+ * button with key and click handlers). Standalone at its own origin a form would work, which is why tests miss it.
+ */
+export declare const SEALED_FRAME_SANDBOX = "allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox";
+/** The sign-out page's sandbox: it runs a script against the frame origin's storage and opens nothing. */
+export declare const SEALED_WIPE_SANDBOX = "allow-scripts allow-same-origin";
+/** The frame's permissions policy: only writing to the clipboard (copy an answer). */
+export declare const SEALED_FRAME_ALLOW = "clipboard-write";
+/** No referrer leaves the host for the frame. */
+export declare const SEALED_FRAME_REFERRER_POLICY = "no-referrer";
+/** The frame's sign-out page, on the frame origin. */
+export declare const SEALED_WIPE_PATH = "/wipe.html";
+/** Which host embeds the frame. */
+export declare const SEALED_FRAME_HOST_KINDS: readonly ["minds", "build"];
+export type SealedFrameHostKind = (typeof SEALED_FRAME_HOST_KINDS)[number];
+export declare const SEALED_FRAME_SCHEMES: readonly ["light", "dark"];
+export type SealedFrameScheme = (typeof SEALED_FRAME_SCHEMES)[number];
+/** `column`: a phone-width column. `workspace`: the desktop thread area, where the frame lists its own Sealed chats. */
+export declare const SEALED_FRAME_LAYOUTS: readonly ["column", "workspace"];
+export type SealedFrameLayout = (typeof SEALED_FRAME_LAYOUTS)[number];
+/** Why the frame cannot run Sealed now (`state`, `unavailable`). */
+export declare const SEALED_FRAME_UNAVAILABLE_REASONS: readonly ["unsupported", "tab_busy", "off", "words", "signed_out", "update", "no_account"];
+export type SealedFrameUnavailableReason = (typeof SEALED_FRAME_UNAVAILABLE_REASONS)[number];
+/** Where the frame asks the host to take the member (`navigate`). */
+export declare const SEALED_FRAME_NAVIGATE_TARGETS: readonly ["plans", "settings_ai", "sign_in", "get_app"];
+export type SealedFrameNavigateTarget = (typeof SEALED_FRAME_NAVIGATE_TARGETS)[number];
+/**
+ * Host to frame, by window.postMessage to the frame origin with one transferred MessagePort, on every load of the
+ * frame. `account` is the signed-in member's user id, and null exactly when `signedIn` is false: a hello signed out
+ * wipes every account's Sealed data in that browser (the shared-computer rule).
+ */
+export interface SealedFrameHello {
+    t: 'sealed/hello';
+    v: 1;
+    host: SealedFrameHostKind;
+    scheme: SealedFrameScheme;
+    layout: SealedFrameLayout;
+    signedIn: boolean;
+    account: string | null;
+}
+/** Host to frame, on the port. */
+export type SealedHostMessage = 
+/** In answer to `need-token`: the frame token (memory only), when it expires (ms since the epoch), whose it is. */
+{
+    t: 'token';
+    v: 1;
+    token: string;
+    expiresAt: number;
+    account: string;
+} | {
+    t: 'theme';
+    v: 1;
+    scheme: SealedFrameScheme;
+} | {
+    t: 'layout';
+    v: 1;
+    layout: SealedFrameLayout;
+}
+/** The member switched accounts: the frame drops its session and token. */
+ | {
+    t: 'account';
+    v: 1;
+    account: string;
+}
+/** The member signed out: the frame wipes that account's Sealed data and answers `wiped`. */
+ | {
+    t: 'signed-out';
+    v: 1;
+} | {
+    t: 'new-chat';
+    v: 1;
+};
+/** The frame's state, as the host shows it. */
+export type SealedFrameState = {
+    state: 'ready';
+} | {
+    state: 'unavailable';
+    reason: SealedFrameUnavailableReason;
+};
+/** Frame to host, on the port. */
+export type SealedFrameMessage = 
+/** The first answer: the protocol the frame speaks and its release id. */
+{
+    t: 'ready';
+    v: 1;
+    protocol: number;
+    release: string;
+}
+/** On start, 60 s before the token expires, and after the API refused the token. */
+ | {
+    t: 'need-token';
+    v: 1;
+} | ({
+    t: 'state';
+    v: 1;
+} & SealedFrameState) | {
+    t: 'navigate';
+    v: 1;
+    to: SealedFrameNavigateTarget;
+}
+/** The account's Sealed data is gone (after `signed-out`, or the sign-out page's `sealed/wipe`). */
+ | {
+    t: 'wiped';
+    v: 1;
+};
+/**
+ * Host to the sign-out page (/wipe.html), by window.postMessage to the frame origin with one transferred MessagePort.
+ * `account` null wipes every account's Sealed data in that browser. The page answers `wiped` on the port.
+ */
+export interface SealedWipeRequest {
+    t: 'sealed/wipe';
+    v: 1;
+    account: string | null;
+}
+/** Whether a value is a frame token in the API's format. */
+export declare function isSealedFrameToken(value: unknown): value is string;
+/** A `sealed/hello`, as the frame reads it; null for anything else. */
+export declare function parseSealedFrameHello(data: unknown): SealedFrameHello | null;
+/** A host-to-frame port message, as the frame reads it; null for anything else. */
+export declare function parseSealedHostMessage(data: unknown): SealedHostMessage | null;
+/** A frame-to-host port message, as the host reads it; null for anything else. */
+export declare function parseSealedFrameMessage(data: unknown): SealedFrameMessage | null;
+/** A `sealed/wipe`, as the sign-out page reads it; null for anything else. */
+export declare function parseSealedWipeRequest(data: unknown): SealedWipeRequest | null;
+/** The host's `sealed/hello`. `account` is the signed-in member's user id, or null when no one is signed in. */
+export declare function sealedFrameHello(input: {
+    host: SealedFrameHostKind;
+    scheme: SealedFrameScheme;
+    layout: SealedFrameLayout;
+    account: string | null;
+}): SealedFrameHello;
+/** The host's port messages. */
+export declare const sealedHostMessage: {
+    token: (token: string, expiresAt: number, account: string) => {
+        t: "token";
+        v: 1;
+        token: string;
+        expiresAt: number;
+        account: string;
+    } | {
+        t: "theme";
+        v: 1;
+        scheme: SealedFrameScheme;
+    } | {
+        t: "layout";
+        v: 1;
+        layout: SealedFrameLayout;
+    } | {
+        t: "account";
+        v: 1;
+        account: string;
+    } | {
+        t: "signed-out";
+        v: 1;
+    } | {
+        t: "new-chat";
+        v: 1;
+    };
+    theme: (scheme: SealedFrameScheme) => {
+        t: "token";
+        v: 1;
+        token: string;
+        expiresAt: number;
+        account: string;
+    } | {
+        t: "theme";
+        v: 1;
+        scheme: SealedFrameScheme;
+    } | {
+        t: "layout";
+        v: 1;
+        layout: SealedFrameLayout;
+    } | {
+        t: "account";
+        v: 1;
+        account: string;
+    } | {
+        t: "signed-out";
+        v: 1;
+    } | {
+        t: "new-chat";
+        v: 1;
+    };
+    layout: (layout: SealedFrameLayout) => {
+        t: "token";
+        v: 1;
+        token: string;
+        expiresAt: number;
+        account: string;
+    } | {
+        t: "theme";
+        v: 1;
+        scheme: SealedFrameScheme;
+    } | {
+        t: "layout";
+        v: 1;
+        layout: SealedFrameLayout;
+    } | {
+        t: "account";
+        v: 1;
+        account: string;
+    } | {
+        t: "signed-out";
+        v: 1;
+    } | {
+        t: "new-chat";
+        v: 1;
+    };
+    account: (account: string) => {
+        t: "token";
+        v: 1;
+        token: string;
+        expiresAt: number;
+        account: string;
+    } | {
+        t: "theme";
+        v: 1;
+        scheme: SealedFrameScheme;
+    } | {
+        t: "layout";
+        v: 1;
+        layout: SealedFrameLayout;
+    } | {
+        t: "account";
+        v: 1;
+        account: string;
+    } | {
+        t: "signed-out";
+        v: 1;
+    } | {
+        t: "new-chat";
+        v: 1;
+    };
+    signedOut: () => {
+        t: "token";
+        v: 1;
+        token: string;
+        expiresAt: number;
+        account: string;
+    } | {
+        t: "theme";
+        v: 1;
+        scheme: SealedFrameScheme;
+    } | {
+        t: "layout";
+        v: 1;
+        layout: SealedFrameLayout;
+    } | {
+        t: "account";
+        v: 1;
+        account: string;
+    } | {
+        t: "signed-out";
+        v: 1;
+    } | {
+        t: "new-chat";
+        v: 1;
+    };
+    newChat: () => {
+        t: "token";
+        v: 1;
+        token: string;
+        expiresAt: number;
+        account: string;
+    } | {
+        t: "theme";
+        v: 1;
+        scheme: SealedFrameScheme;
+    } | {
+        t: "layout";
+        v: 1;
+        layout: SealedFrameLayout;
+    } | {
+        t: "account";
+        v: 1;
+        account: string;
+    } | {
+        t: "signed-out";
+        v: 1;
+    } | {
+        t: "new-chat";
+        v: 1;
+    };
+};
+/**
+ * The frame's port messages. Each takes only enums, numbers and the frame's compiled release id, so nothing the member
+ * typed or read can be put in one.
+ */
+export declare const sealedFrameMessage: {
+    ready: (release: string) => {
+        t: "ready";
+        v: 1;
+        protocol: number;
+        release: string;
+    } | {
+        t: "need-token";
+        v: 1;
+    } | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "ready";
+    }) | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "unavailable";
+        reason: SealedFrameUnavailableReason;
+    }) | {
+        t: "navigate";
+        v: 1;
+        to: SealedFrameNavigateTarget;
+    } | {
+        t: "wiped";
+        v: 1;
+    };
+    needToken: () => {
+        t: "ready";
+        v: 1;
+        protocol: number;
+        release: string;
+    } | {
+        t: "need-token";
+        v: 1;
+    } | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "ready";
+    }) | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "unavailable";
+        reason: SealedFrameUnavailableReason;
+    }) | {
+        t: "navigate";
+        v: 1;
+        to: SealedFrameNavigateTarget;
+    } | {
+        t: "wiped";
+        v: 1;
+    };
+    stateReady: () => {
+        t: "ready";
+        v: 1;
+        protocol: number;
+        release: string;
+    } | {
+        t: "need-token";
+        v: 1;
+    } | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "ready";
+    }) | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "unavailable";
+        reason: SealedFrameUnavailableReason;
+    }) | {
+        t: "navigate";
+        v: 1;
+        to: SealedFrameNavigateTarget;
+    } | {
+        t: "wiped";
+        v: 1;
+    };
+    unavailable: (reason: SealedFrameUnavailableReason) => {
+        t: "ready";
+        v: 1;
+        protocol: number;
+        release: string;
+    } | {
+        t: "need-token";
+        v: 1;
+    } | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "ready";
+    }) | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "unavailable";
+        reason: SealedFrameUnavailableReason;
+    }) | {
+        t: "navigate";
+        v: 1;
+        to: SealedFrameNavigateTarget;
+    } | {
+        t: "wiped";
+        v: 1;
+    };
+    navigate: (to: SealedFrameNavigateTarget) => {
+        t: "ready";
+        v: 1;
+        protocol: number;
+        release: string;
+    } | {
+        t: "need-token";
+        v: 1;
+    } | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "ready";
+    }) | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "unavailable";
+        reason: SealedFrameUnavailableReason;
+    }) | {
+        t: "navigate";
+        v: 1;
+        to: SealedFrameNavigateTarget;
+    } | {
+        t: "wiped";
+        v: 1;
+    };
+    wiped: () => {
+        t: "ready";
+        v: 1;
+        protocol: number;
+        release: string;
+    } | {
+        t: "need-token";
+        v: 1;
+    } | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "ready";
+    }) | ({
+        t: "state";
+        v: 1;
+    } & {
+        state: "unavailable";
+        reason: SealedFrameUnavailableReason;
+    }) | {
+        t: "navigate";
+        v: 1;
+        to: SealedFrameNavigateTarget;
+    } | {
+        t: "wiped";
+        v: 1;
+    };
+};
+/** The host's `sealed/wipe` for the sign-out page. `account` null wipes every account's Sealed data in the browser. */
+export declare function sealedWipeRequest(account: string | null): SealedWipeRequest;
+/**
+ * The frame origin as an exact origin (`https://sealed.minds.com`), or a TypeError. Only https, or http on localhost
+ * for development; no path, query, fragment or credentials.
+ */
+export declare function sealedFrameOrigin(value: string): string;