@joe-broadhead/messaging 0.0.0-stage → 0.7.0

package/dist/types/core/schema/ipc/jelly.d.ts

@@ -0,0 +1,501 @@
+/**
+ * The IPC methods a Jelly host needs (spec §8.2, §8.11; design §13.6, §13.10-§13.12), served in every deployment:
+ *
+ * - Agent tier: `daemon.health`, a cheap status with no secrets and no counts.
+ * - Human tier: `agents.list` and `agents.read` (the person's view of their own agents' traffic on this device),
+ *   `notice.subscribe`, `notice.list` and `notice.ack` (notices in fixed categories), and the read-only preview
+ *   `device.remove.preview`.
+ *
+ * Spread into `IPC_METHODS`; `HOST_SCOPE_METHODS` (in `ipc.ts`) is what a host-scope action grant allows.
+ */
+import { z } from "zod";
+/**
+ * A notice's id, stable per source: `m_<line id>` (a line), `r_<request id>` (a held request), `a_<id>` (an alert).
+ * A replay repeats the same ids, so a host rings once.
+ */
+export declare const NoticeId: z.ZodString;
+export type NoticeId = z.infer<typeof NoticeId>;
+/** Most characters of a notice's `line`. */
+export declare const NOTICE_LINE_CHARS = 120;
+/**
+ * An alert about another device of this person (design §2.8): the change, as `DeviceChangeView` gives it, with
+ * `device` the device the person may want to remove (for `replaced`, the successor; `replaces` is the device it
+ * replaced). `current`: whether that device is current now. `remove`: how this device removes it: `token` with a
+ * fresh Jelly token from its host (`device.remove {device, token}`), `sign-in` with a fresh sign-in through the
+ * browser (`device.login {remove: {device}}`), `team` as the roster's admin (`team.remove`); absent when it cannot
+ * (it is not current, or this device was approved by link and removes no device).
+ */
+export declare const NoticeDevice: z.ZodObject<{
+    change: z.ZodEnum<{
+        removed: "removed";
+        replaced: "replaced";
+        added: "added";
+        vouched: "vouched";
+    }>;
+    device: z.ZodString;
+    label: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        "jelly-host": "jelly-host";
+        laptop: "laptop";
+        server: "server";
+        other: "other";
+    }>>;
+    vouch: z.ZodEnum<{
+        admin: "admin";
+        device: "device";
+        jelly: "jelly";
+    }>;
+    via: z.ZodOptional<z.ZodEnum<{
+        host: "host";
+        browser: "browser";
+    }>>;
+    approver: z.ZodOptional<z.ZodString>;
+    at: z.ZodNumber;
+    replaces: z.ZodOptional<z.ZodObject<{
+        device: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    current: z.ZodBoolean;
+    remove: z.ZodOptional<z.ZodEnum<{
+        token: "token";
+        "sign-in": "sign-in";
+        team: "team";
+    }>>;
+}, z.core.$strip>;
+export type NoticeDevice = z.infer<typeof NoticeDevice>;
+/**
+ * One notice (design §13.11). `message`: a line in a DM or a channel from another person or their agent, or an
+ * agent's line to its own person; `request`: a request held for the person; `alert`: an alarm of this device, a
+ * change of the person's other devices (with `device`), or trust the person gave that ends within 7 days (with `from`).
+ * `line` is the first line of a message, through `cleanPeerText`, only when the caller asked for lines; alerts carry
+ * fixed text. `from.name` and `from.email` are untrusted text in a hosted realm.
+ */
+export declare const Notice: z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodEnum<{
+        message: "message";
+        request: "request";
+        alert: "alert";
+    }>;
+    conversation: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        org: z.ZodEnum<{
+            other: "other";
+            none: "none";
+            same: "same";
+        }>;
+    }, z.core.$strip>>;
+    line: z.ZodOptional<z.ZodString>;
+    device: z.ZodOptional<z.ZodObject<{
+        change: z.ZodEnum<{
+            removed: "removed";
+            replaced: "replaced";
+            added: "added";
+            vouched: "vouched";
+        }>;
+        device: z.ZodString;
+        label: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            "jelly-host": "jelly-host";
+            laptop: "laptop";
+            server: "server";
+            other: "other";
+        }>>;
+        vouch: z.ZodEnum<{
+            admin: "admin";
+            device: "device";
+            jelly: "jelly";
+        }>;
+        via: z.ZodOptional<z.ZodEnum<{
+            host: "host";
+            browser: "browser";
+        }>>;
+        approver: z.ZodOptional<z.ZodString>;
+        at: z.ZodNumber;
+        replaces: z.ZodOptional<z.ZodObject<{
+            device: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+        current: z.ZodBoolean;
+        remove: z.ZodOptional<z.ZodEnum<{
+            token: "token";
+            "sign-in": "sign-in";
+            team: "team";
+        }>>;
+    }, z.core.$strip>>;
+    at: z.ZodNumber;
+}, z.core.$strip>;
+export type Notice = z.infer<typeof Notice>;
+/** What the person's badges count: unread lines in their conversations, and requests held for them. */
+export declare const NoticeCounts: z.ZodObject<{
+    unread: z.ZodNumber;
+    requests: z.ZodNumber;
+}, z.core.$strip>;
+/** `daemon.health` (spec §8.2): the daemon's state, with no secrets and no counts. */
+export declare const DaemonHealth: z.ZodObject<{
+    state: z.ZodEnum<{
+        starting: "starting";
+        running: "running";
+        stopping: "stopping";
+    }>;
+    relay: z.ZodEnum<{
+        offline: "offline";
+        connected: "connected";
+        connecting: "connecting";
+    }>;
+    directory: z.ZodEnum<{
+        alarm: "alarm";
+        ok: "ok";
+        unavailable: "unavailable";
+    }>;
+    alarm: z.ZodNullable<z.ZodEnum<{
+        directory: "directory";
+        restored: "restored";
+        keys_missing: "keys_missing";
+    }>>;
+    busy: z.ZodBoolean;
+    version: z.ZodString;
+    storeSchema: z.ZodNumber;
+}, z.core.$strip>;
+export type DaemonHealth = z.infer<typeof DaemonHealth>;
+/** One local agent (a registered or kept session) and its traffic on this device. */
+export declare const AgentSummary: z.ZodObject<{
+    agent: z.ZodString;
+    conversations: z.ZodNumber;
+    unread: z.ZodNumber;
+    lastAt: z.ZodOptional<z.ZodNumber>;
+    state: z.ZodEnum<{
+        idle: "idle";
+        busy: "busy";
+        kept: "kept";
+    }>;
+}, z.core.$strip>;
+export declare const JELLY_METHODS: {
+    /**
+     * Agent tier. A cheap status for a host that polls: the daemon's state, the relay, the directory, an alarm, and
+     * whether it is busy. No counts: they are the person's (`notice.list`).
+     */
+    readonly "daemon.health": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            state: z.ZodEnum<{
+                starting: "starting";
+                running: "running";
+                stopping: "stopping";
+            }>;
+            relay: z.ZodEnum<{
+                offline: "offline";
+                connected: "connected";
+                connecting: "connecting";
+            }>;
+            directory: z.ZodEnum<{
+                alarm: "alarm";
+                ok: "ok";
+                unavailable: "unavailable";
+            }>;
+            alarm: z.ZodNullable<z.ZodEnum<{
+                directory: "directory";
+                restored: "restored";
+                keys_missing: "keys_missing";
+            }>>;
+            busy: z.ZodBoolean;
+            version: z.ZodString;
+            storeSchema: z.ZodNumber;
+        }, z.core.$strip>;
+    };
+    /** Human tier. This person's local agents on this device, most recent first. Read-only. */
+    readonly "agents.list": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            agents: z.ZodArray<z.ZodObject<{
+                agent: z.ZodString;
+                conversations: z.ZodNumber;
+                unread: z.ZodNumber;
+                lastAt: z.ZodOptional<z.ZodNumber>;
+                state: z.ZodEnum<{
+                    idle: "idle";
+                    busy: "busy";
+                    kept: "kept";
+                }>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
+    /**
+     * Human tier. One local agent's traffic: without `conversation`, the other agents it has mail or tasks with, most
+     * recent first; with `conversation` (`agent:<person>/<agent>`), a page of its entries, as `conv.read` gives them to
+     * the agent, latest first unless `before` names an entry. Changes no stage and sends no receipt. Peer text is
+     * untrusted: a client cleans it for display.
+     */
+    readonly "agents.read": {
+        readonly params: z.ZodObject<{
+            agent: z.ZodString;
+            conversation: z.ZodOptional<z.ZodString>;
+            before: z.ZodOptional<z.ZodObject<{
+                at: z.ZodNumber;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"conversations">;
+            conversations: z.ZodArray<z.ZodObject<{
+                conversation: z.ZodString;
+                unread: z.ZodNumber;
+                lastAt: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"entries">;
+            conversation: z.ZodString;
+            entries: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    task: "task";
+                    mail: "mail";
+                }>;
+                direction: z.ZodEnum<{
+                    out: "out";
+                    in: "in";
+                }>;
+                peer: z.ZodString;
+                at: z.ZodNumber;
+                text: z.ZodOptional<z.ZodString>;
+                taskId: z.ZodOptional<z.ZodString>;
+                stage: z.ZodOptional<z.ZodEnum<{
+                    accepted: "accepted";
+                    relayed: "relayed";
+                    delivered: "delivered";
+                    held: "held";
+                    handed_to_agent: "handed_to_agent";
+                    read: "read";
+                    replied: "replied";
+                    rejected: "rejected";
+                    expired: "expired";
+                }>>;
+                role: z.ZodOptional<z.ZodEnum<{
+                    requester: "requester";
+                    executor: "executor";
+                }>>;
+                state: z.ZodOptional<z.ZodEnum<{
+                    TASK_STATE_SUBMITTED: "TASK_STATE_SUBMITTED";
+                    TASK_STATE_WORKING: "TASK_STATE_WORKING";
+                    TASK_STATE_COMPLETED: "TASK_STATE_COMPLETED";
+                    TASK_STATE_FAILED: "TASK_STATE_FAILED";
+                    TASK_STATE_CANCELED: "TASK_STATE_CANCELED";
+                    TASK_STATE_INPUT_REQUIRED: "TASK_STATE_INPUT_REQUIRED";
+                    TASK_STATE_REJECTED: "TASK_STATE_REJECTED";
+                    TASK_STATE_AUTH_REQUIRED: "TASK_STATE_AUTH_REQUIRED";
+                }>>;
+            }, z.core.$strip>>;
+            more: z.ZodBoolean;
+        }, z.core.$strip>], "kind">;
+    };
+    /**
+     * Human tier; host scope in `deployment: "jelly"`. Replays the unacknowledged notices after `after` (all of them
+     * without it), oldest first, as `notice` events on this connection, then sends each new one. With `lines`, a
+     * message carries its first line. A subscription under a host-scope grant ends when the grant expires.
+     */
+    readonly "notice.subscribe": {
+        readonly params: z.ZodObject<{
+            after: z.ZodOptional<z.ZodString>;
+            lines: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            replayed: z.ZodNumber;
+        }, z.core.$strip>;
+    };
+    /** Human tier; host scope in `deployment: "jelly"`. The unacknowledged notices, newest first, and the badge counts. */
+    readonly "notice.list": {
+        readonly params: z.ZodObject<{
+            lines: z.ZodOptional<z.ZodBoolean>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            notices: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                category: z.ZodEnum<{
+                    message: "message";
+                    request: "request";
+                    alert: "alert";
+                }>;
+                conversation: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodString;
+                    email: z.ZodOptional<z.ZodString>;
+                    org: z.ZodEnum<{
+                        other: "other";
+                        none: "none";
+                        same: "same";
+                    }>;
+                }, z.core.$strip>>;
+                line: z.ZodOptional<z.ZodString>;
+                device: z.ZodOptional<z.ZodObject<{
+                    change: z.ZodEnum<{
+                        removed: "removed";
+                        replaced: "replaced";
+                        added: "added";
+                        vouched: "vouched";
+                    }>;
+                    device: z.ZodString;
+                    label: z.ZodString;
+                    kind: z.ZodOptional<z.ZodEnum<{
+                        "jelly-host": "jelly-host";
+                        laptop: "laptop";
+                        server: "server";
+                        other: "other";
+                    }>>;
+                    vouch: z.ZodEnum<{
+                        admin: "admin";
+                        device: "device";
+                        jelly: "jelly";
+                    }>;
+                    via: z.ZodOptional<z.ZodEnum<{
+                        host: "host";
+                        browser: "browser";
+                    }>>;
+                    approver: z.ZodOptional<z.ZodString>;
+                    at: z.ZodNumber;
+                    replaces: z.ZodOptional<z.ZodObject<{
+                        device: z.ZodString;
+                        label: z.ZodString;
+                    }, z.core.$strip>>;
+                    current: z.ZodBoolean;
+                    remove: z.ZodOptional<z.ZodEnum<{
+                        token: "token";
+                        "sign-in": "sign-in";
+                        team: "team";
+                    }>>;
+                }, z.core.$strip>>;
+                at: z.ZodNumber;
+            }, z.core.$strip>>;
+            counts: z.ZodObject<{
+                unread: z.ZodNumber;
+                requests: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    };
+    /** Human tier. Marks notices seen; unknown ids are ignored. */
+    readonly "notice.ack": {
+        readonly params: z.ZodObject<{
+            ids: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's M-3). The host sends it after the machine wakes from sleep:
+     * the daemon retries its relay link at once instead of at its backoff, runs its sweep, sends presence, and disarms a
+     * wake ticket it armed (`wake.disarm`), which this wake spent or no longer needs.
+     */
+    readonly "daemon.woke": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's M-4). Whether a window of the person is visible on this
+     * host. While it is not, under a Jelly host, this device's presence says `away` (spec §6.5), and the person's
+     * contacts see that device as away. Before the first call a Jelly host's device is away; elsewhere never.
+     */
+    readonly "person.attached": {
+        readonly params: z.ZodObject<{
+            attached: z.ZodBoolean;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's A5). Before the host sleeps: the daemon hands its relay the
+     * host's wake ticket (`jelly-wake+jwt`, for `url`, Jelly ID's wake endpoint of this host), the sessions in `agents`
+     * whose own person's mail may wake the host, and the tasks those sessions await (their unfinished requests). The relay
+     * presents the ticket once, for such traffic only, while this device is offline (spec §7, "Wake tickets"). `relay`:
+     * `armed` once the relay holds it, `pending` while it is not connected (it is sent at the next connection);
+     * `awaiting`: how many task requests the relay may wake for. A directory realm only.
+     */
+    readonly "wake.arm": {
+        readonly params: z.ZodObject<{
+            url: z.ZodString;
+            ticket: z.ZodString;
+            agents: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            relay: z.ZodEnum<{
+                pending: "pending";
+                armed: "armed";
+            }>;
+            awaiting: z.ZodNumber;
+        }, z.core.$strip>;
+    };
+    /** Admin tier; host scope in `deployment: "jelly"`. The relay forgets this device's wake ticket (`pending` until connected). */
+    readonly "wake.disarm": {
+        readonly params: z.ZodObject<{}, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            relay: z.ZodEnum<{
+                pending: "pending";
+                disarmed: "disarmed";
+            }>;
+        }, z.core.$strip>;
+    };
+    /**
+     * Admin tier; host scope in `deployment: "jelly"` (Jelly's backup proposal, design §13.9). `{}` writes a consistent
+     * copy of the home while the daemon runs into `folder`, `<run>/snapshot` (the socket folder), and holds it there:
+     * the store (`messaging.db`, by SQLite `VACUUM INTO`), `config.json` and `manifest.json`. Never a private key:
+     * `identity.json` is not copied. `{done: true}` releases it (deletes the folder); a held snapshot is also released
+     * after an hour and when the daemon starts. `invalid_state` while one is held.
+     */
+    readonly "daemon.snapshot": {
+        readonly params: z.ZodObject<{
+            done: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strict>;
+        readonly result: z.ZodUnion<readonly [z.ZodObject<{
+            folder: z.ZodString;
+            files: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                bytes: z.ZodNumber;
+                sha256: z.ZodString;
+            }, z.core.$strip>>;
+            storeSchema: z.ZodNumber;
+            at: z.ZodNumber;
+            until: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            released: z.ZodBoolean;
+        }, z.core.$strip>]>;
+    };
+    /**
+     * Human tier, read-only. What removing `device` would remove, for a confirmation: its label, kind and vouch, and
+     * whether it is current. `not_found` for a device that is not this person's.
+     */
+    /** `device.remove`'s input (spec §8.2, "Previews"); `reason` and `token` are not used, and `token` is never logged. */
+    readonly "device.remove.preview": {
+        readonly params: z.ZodObject<{
+            device: z.ZodString;
+            reason: z.ZodOptional<z.ZodEnum<{
+                self: "self";
+                removed: "removed";
+                lost: "lost";
+            }>>;
+            token: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            label: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                "jelly-host": "jelly-host";
+                laptop: "laptop";
+                server: "server";
+                other: "other";
+            }>>;
+            vouch: z.ZodEnum<{
+                admin: "admin";
+                device: "device";
+                jelly: "jelly";
+            }>;
+            current: z.ZodBoolean;
+            self: z.ZodBoolean;
+            since: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    };
+};