fauna-api 1.0.783 → 1.0.786

package/dist/src/chats.d.ts

@@ -1,5 +1,7 @@
-import { ApiKey, Credentials, Profile } from "./authentification.js";
-import { LastMessage } from "./parrot/chat.js";
+import { Fauna } from "../index.js";
+import { ApiKey, Credentials } from "./authentification.js";
+import { ChatSummary } from "./parrot/chat.js";
+import { Author } from "./parrot/generative.js";
 /** Whose chat it is: one of your groups, a friendship, or a partnership of one of your groups. */
 export type OwnerKind = 'group' | 'friend' | 'partnership';
 /** Who a chat belongs to, and how much you trust it. */
@@ -17,27 +19,19 @@ export type Owner = {
         name: string;
     };
 };
-/** A chat you share with others. */
-export type Chat = {
-    id: string;
-    name: string;
-    /** People only: sends never start a model reply. */
-    human: boolean;
+/** A chat you share with others: the Parrot chat, and whose it is. Signed in with an API key, its `unread` is the key's own place. */
+export type Chat = ChatSummary & {
     owner: Owner;
-    /** Messages you haven't read. Signed in with an API key, the key keeps its own place. */
-    unread: number;
-    /** Milliseconds since the epoch. */
-    updated: number;
-    last: LastMessage | null;
+};
+export declare const Chat: {
+    fromJSON(json: any): Chat;
 };
 /** A message as plain text: mentions as names, files as `[file: name]`. */
 export type Message = {
     position: number;
     role: string;
     text: string;
-    author?: Profile;
-    /** The name of the API key an agent posted it with. */
-    via?: string;
+    author?: Author;
     /** Milliseconds since the epoch. */
     created: number;
 };
@@ -107,7 +101,7 @@ export declare function search(authorization: Credentials | ApiKey, query: strin
 /**
  * Post `text` in a chat, as you. Everyone in it sees it live, its webhooks fire
  * and it counts toward memories, like any message. Signed in with an API key,
- * the message records the key's name (`via`) and never moves trust. In a chat
+ * the message is authored by the key, by its name, and never moves trust. In a chat
  * that isn't people only, it starts a model reply as any message does.
  */
 export declare function post(authorization: Credentials | ApiKey, chat: string, text: string): Promise<void>;

package/dist/src/chats.js

@@ -1,5 +1,11 @@
 import { Fauna } from "../index.js";
 import { Parrot } from "./parrot/index.js";
+import { ChatSummary } from "./parrot/chat.js";
+export const Chat = {
+    fromJSON(json) {
+        return { ...ChatSummary.fromJSON(json), owner: json.owner };
+    },
+};
 /**
  * Every chat you share with others, newest first: your groups', your friends'
  * and your groups' partnerships', each with its owner, your trust in it and what
@@ -14,7 +20,7 @@ export async function list(authorization) {
     });
     if (!response.ok)
         throw new Error(await response.text());
-    return await response.json();
+    return (await response.json()).map(Chat.fromJSON);
 }
 /**
  * What you haven't read in chats you trust at least `minTrust` (default 0.1).
@@ -30,7 +36,8 @@ export async function unread(authorization, options = {}) {
     });
     if (!response.ok)
         throw new Error(await response.text());
-    return await response.json();
+    const json = await response.json();
+    return { total: json.total, chats: (json.chats ?? []).map(Chat.fromJSON) };
 }
 /**
  * Everything you haven't read in chats you trust at least `minTrust` (default
@@ -72,7 +79,7 @@ export async function search(authorization, query, options = {}) {
 /**
  * Post `text` in a chat, as you. Everyone in it sees it live, its webhooks fire
  * and it counts toward memories, like any message. Signed in with an API key,
- * the message records the key's name (`via`) and never moves trust. In a chat
+ * the message is authored by the key, by its name, and never moves trust. In a chat
  * that isn't people only, it starts a model reply as any message does.
  */
 export async function post(authorization, chat, text) {

package/dist/src/cicada/chats.d.ts

@@ -0,0 +1,98 @@
+import { Cicada } from "./index.js";
+import { Contact, Owner } from "./contacts.js";
+import { Platform } from "../integrations.js";
+import { Credentials, ApiKey } from "../authentification.js";
+import { ChatSummary } from "../parrot/chat.js";
+/** A line under one of a chat's messages, by its position: why it never arrived, or that it waits for an owner's approval. */
+export type Note = {
+    position: number;
+    text: string;
+};
+/**
+ * One of an inbox's chats: the Parrot chat the inbox owns, with who it's with and how they're
+ * reached. Its messages are the chat's: open its room with `Parrot.Chat.openRoom` and
+ * `{ chatId: id }`. What the inbox's members and its agent write there goes out to its people.
+ */
+export type Chat = ChatSummary & {
+    inboxId: string;
+    participants: (Contact | Owner | string)[];
+    /** The Discord or Slack channel it is, when it's one. */
+    channel?: {
+        platform?: Platform;
+        name?: string;
+        guildName?: string;
+    };
+    /** The platform it's reached on. */
+    platform?: Platform;
+    archived: boolean;
+    remindAt?: Date;
+    notes: Note[];
+};
+export declare const Chat: {
+    fromJSON(json: any): Chat;
+};
+/** A chat paired with the time its reminder is due. */
+export type Reminder = {
+    chat: Chat;
+    remindAt: Date;
+};
+/**
+ * A queued outbound message the server sends at `sendAt`: a reply in a chat, or a fresh
+ * compose to a set of recipients (hydrated to contacts so the client can render them).
+ */
+export type ScheduledSend = {
+    id: string;
+    sendAt: Date;
+    createdAt: Date;
+    message: string;
+    context: {
+        chatId: string;
+        platform?: Platform;
+    } | {
+        recipients: (Contact | Owner | string)[];
+        mode: 'broadcast' | 'group';
+        platform: Platform;
+    };
+};
+/** The inbox working set: everything except archived chats and chats parked for a future reminder. */
+export declare function listInbox(authorization: Credentials | ApiKey, inboxId?: string): Promise<Chat[]>;
+/** The archive. */
+export declare function listArchived(authorization: Credentials | ApiKey, inboxId?: string): Promise<Chat[]>;
+/** Chats with a future reminder, each with its due time. */
+export declare function listReminders(authorization: Credentials | ApiKey, inboxId?: string): Promise<Reminder[]>;
+/** One chat, or null once it's gone. */
+export declare function get(authorization: Credentials | ApiKey, chatId: string): Promise<Chat | null>;
+/** Deletes a chat and its messages. A history pull never brings them back. */
+export declare function remove(authorization: Credentials | ApiKey, chatId: string): Promise<void>;
+/**
+ * Starts (or appends to) chats with picked contacts on a platform. `recipients` are contact
+ * keys (email, handle or phone). `broadcast` sends a separate one to each; `group` sends one
+ * shared thread (one each on platforms without a real group). Resolves to the chats it wrote in.
+ */
+export declare function compose(authorization: Credentials | ApiKey, options: {
+    recipients: string[];
+    platform: Platform;
+    text: string;
+    mode: 'broadcast' | 'group';
+    inboxId?: string;
+    accountId?: string;
+}): Promise<string[]>;
+/** Moves a chat in or out of the archive. */
+export declare function archive(authorization: Credentials | ApiKey, chatId: string, archived: boolean): Promise<void>;
+/** Sets (or clears, with null) a reminder; when it's due the chat comes back to the top of the inbox. */
+export declare function remind(authorization: Credentials | ApiKey, chatId: string, at: Date | null): Promise<void>;
+/** Queues an outbound message: a reply in `chatId`, or `compose` for fresh chats. Resolves to its id. */
+export declare function schedule(authorization: Credentials | ApiKey, options: {
+    sendAt: Date;
+    text: string;
+    platform?: Platform;
+    chatId?: string;
+    compose?: {
+        recipients: string[];
+        mode: 'broadcast' | 'group';
+    };
+    inboxId?: string;
+    accountId?: string;
+}): Promise<string>;
+export declare function listScheduled(authorization: Credentials | ApiKey, inboxId?: string): Promise<ScheduledSend[]>;
+export declare function cancelScheduled(authorization: Credentials | ApiKey, scheduled: string): Promise<void>;

package/dist/src/cicada/chats.js

@@ -0,0 +1,92 @@
+import { Cicada } from "./index.js";
+import { ChatSummary } from "../parrot/chat.js";
+export const Chat = {
+    fromJSON(json) {
+        return {
+            ...ChatSummary.fromJSON(json),
+            inboxId: String(json.inboxId),
+            participants: json.participants ?? [],
+            ...(json.channel ? { channel: json.channel } : {}),
+            ...(json.platform ? { platform: json.platform } : {}),
+            archived: json.archived === true,
+            ...(json.remindAt ? { remindAt: new Date(json.remindAt) } : {}),
+            notes: Array.isArray(json.notes) ? json.notes : [],
+        };
+    },
+};
+async function post(authorization, path, body) {
+    const response = await fetch(`${Cicada.getURL()}${path}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        },
+        body: JSON.stringify(body)
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return response;
+}
+/** The inbox working set: everything except archived chats and chats parked for a future reminder. */
+export async function listInbox(authorization, inboxId) {
+    const response = await post(authorization, '/cicada/inbox', inboxId ? { inboxId } : {});
+    return (await response.json()).map(Chat.fromJSON);
+}
+/** The archive. */
+export async function listArchived(authorization, inboxId) {
+    const response = await post(authorization, '/cicada/archived', inboxId ? { inboxId } : {});
+    return (await response.json()).map(Chat.fromJSON);
+}
+/** Chats with a future reminder, each with its due time. */
+export async function listReminders(authorization, inboxId) {
+    const response = await post(authorization, '/cicada/reminders', inboxId ? { inboxId } : {});
+    return (await response.json()).map((raw) => ({
+        chat: Chat.fromJSON(raw.chat),
+        remindAt: new Date(raw.remindAt)
+    }));
+}
+/** One chat, or null once it's gone. */
+export async function get(authorization, chatId) {
+    const response = await post(authorization, '/cicada/chats/get', { chatId });
+    const json = await response.json();
+    return json ? Chat.fromJSON(json) : null;
+}
+/** Deletes a chat and its messages. A history pull never brings them back. */
+export async function remove(authorization, chatId) {
+    await post(authorization, '/cicada/chats/delete', { chatId });
+}
+/**
+ * Starts (or appends to) chats with picked contacts on a platform. `recipients` are contact
+ * keys (email, handle or phone). `broadcast` sends a separate one to each; `group` sends one
+ * shared thread (one each on platforms without a real group). Resolves to the chats it wrote in.
+ */
+export async function compose(authorization, options) {
+    const response = await post(authorization, '/cicada/compose', options);
+    const json = await response.json();
+    return json.chatIds;
+}
+/** Moves a chat in or out of the archive. */
+export async function archive(authorization, chatId, archived) {
+    await post(authorization, '/cicada/chats/archive', { chatId, archived });
+}
+/** Sets (or clears, with null) a reminder; when it's due the chat comes back to the top of the inbox. */
+export async function remind(authorization, chatId, at) {
+    await post(authorization, '/cicada/chats/remind', { chatId, at: at ? at.toISOString() : null });
+}
+/** Queues an outbound message: a reply in `chatId`, or `compose` for fresh chats. Resolves to its id. */
+export async function schedule(authorization, options) {
+    const response = await post(authorization, '/cicada/schedule', { ...options, sendAt: options.sendAt.toISOString() });
+    const json = await response.json();
+    return json.id;
+}
+export async function listScheduled(authorization, inboxId) {
+    const response = await post(authorization, '/cicada/scheduled/list', inboxId ? { inboxId } : {});
+    return (await response.json()).map((raw) => ({
+        ...raw,
+        sendAt: new Date(raw.sendAt),
+        createdAt: new Date(raw.createdAt)
+    }));
+}
+export async function cancelScheduled(authorization, scheduled) {
+    await post(authorization, '/cicada/scheduled/cancel', { scheduled });
+}

package/dist/src/cicada/inboxes.d.ts

@@ -1,4 +1,5 @@
 import { Cicada } from "./index.js";
+import type { Repository } from "../termite/versioning.js";
 import { Platform } from "../integrations.js";
 import { Credentials, ApiKey } from "../authentification.js";
 import type { Text, Voice } from "../parrot/generative.js";
@@ -14,6 +15,8 @@ export type Inbox = {
     group?: InboxGroup;
     /** An agent is on for this inbox. */
     agent?: boolean;
+    /** The Termite repository its agent's desktop works in. */
+    repository?: string;
 };
 export type InboxAccount = {
     platform: Platform;
@@ -23,6 +26,8 @@ export declare function list(authorization: Credentials | ApiKey): Promise<Inbox
 export declare function create(authorization: Credentials | ApiKey, name: string): Promise<Inbox>;
 export declare function rename(authorization: Credentials | ApiKey, inboxId: string, name: string): Promise<Inbox>;
 export declare function remove(authorization: Credentials | ApiKey, inboxId: string): Promise<void>;
+/** Attaches a Termite repository, where the inbox's agent's desktop works, or detaches it with null. It must be the inbox owner's. */
+export declare function setRepository(authorization: Credentials | ApiKey, inboxId: string, repository: Repository | null): Promise<Inbox>;
 export declare function moveToGroup(authorization: Credentials | ApiKey, inboxId: string, groupId: string): Promise<Inbox>;
 export declare function assign(authorization: Credentials | ApiKey, inboxId: string, account: {
     platform: Platform;

package/dist/src/cicada/inboxes.js

@@ -26,6 +26,7 @@ function wrapInbox(raw) {
         createdAt: new Date(raw.createdAt),
         ...(group ? { group } : {}),
         ...(raw.agent ? { agent: true } : {}),
+        ...(raw.repository ? { repository: String(raw.repository) } : {}),
     };
 }
 export async function list(authorization) {
@@ -43,6 +44,11 @@ export async function rename(authorization, inboxId, name) {
 export async function remove(authorization, inboxId) {
     await post(authorization, '/cicada/inboxes/delete', { inbox: inboxId });
 }
+/** Attaches a Termite repository, where the inbox's agent's desktop works, or detaches it with null. It must be the inbox owner's. */
+export async function setRepository(authorization, inboxId, repository) {
+    const response = await post(authorization, '/cicada/inboxes/repository', { inbox: inboxId, repository: repository ? repository.id : null });
+    return wrapInbox(await response.json());
+}
 export async function moveToGroup(authorization, inboxId, groupId) {
     const response = await post(authorization, '/cicada/inboxes/move', { inbox: inboxId, group: groupId });
     return wrapInbox(await response.json());

package/dist/src/cicada/index.d.ts

@@ -1,5 +1,5 @@
+import * as ChatsAPI from "./chats.js";
 import * as ContactsAPI from "./contacts.js";
-import * as ConversationsAPI from "./conversations.js";
 import * as InboxesAPI from "./inboxes.js";
 import * as PhoneAPI from "./phone.js";
 export declare namespace Cicada {
@@ -9,8 +9,8 @@ export declare namespace Cicada {
     function getRoute(): string;
     function getURL(): string;
     function ping(): Promise<number>;
+    export import Chats = ChatsAPI;
     export import Contacts = ContactsAPI;
-    export import Conversations = ConversationsAPI;
     export import Inboxes = InboxesAPI;
     export import Phone = PhoneAPI;
 }

package/dist/src/cicada/index.js

@@ -1,5 +1,5 @@
+import * as ChatsAPI from "./chats.js";
 import * as ContactsAPI from "./contacts.js";
-import * as ConversationsAPI from "./conversations.js";
 import * as InboxesAPI from "./inboxes.js";
 import * as PhoneAPI from "./phone.js";
 export var Cicada;
@@ -54,8 +54,8 @@ export var Cicada;
         return Date.now() - start;
     }
     Cicada.ping = ping;
+    Cicada.Chats = ChatsAPI;
     Cicada.Contacts = ContactsAPI;
-    Cicada.Conversations = ConversationsAPI;
     Cicada.Inboxes = InboxesAPI;
     Cicada.Phone = PhoneAPI;
 })(Cicada || (Cicada = {}));

package/dist/src/friends.js

@@ -1,10 +1,7 @@
 import { Fauna } from "../index.js";
-import { LastMessage } from "./parrot/chat.js";
-function hydrateChats(raw) {
-    return (raw ?? []).map((row) => ({ ...row, human: row.human === true, locked: row.locked === true, last: LastMessage.fromJSON(row.last), unread: typeof row.unread === 'number' ? row.unread : 0 }));
-}
+import { ChatSummary } from "./parrot/chat.js";
 function hydrate(raw) {
-    return { ...raw, chats: hydrateChats(raw.chats), created: new Date(raw.created) };
+    return { ...raw, chats: (raw.chats ?? []).map(ChatSummary.fromJSON), created: new Date(raw.created) };
 }
 /** Your friends, each with your chats together and what you haven't read. An API key reads them too. */
 export async function list(authorization) {

package/dist/src/groups.js

@@ -1,5 +1,5 @@
 import { Fauna } from "../index.js";
-import { LastMessage } from "./parrot/chat.js";
+import { ChatSummary } from "./parrot/chat.js";
 export const GroupRef = {
     fromJSON(json) {
         return {
@@ -501,7 +501,7 @@ export async function unnest(credentials, id, child) {
 function hydratePartnership(raw) {
     return {
         ...raw,
-        chats: (raw.chats ?? []).map((row) => ({ ...row, human: row.human === true, locked: row.locked === true, last: LastMessage.fromJSON(row.last), unread: typeof row.unread === 'number' ? row.unread : 0 })),
+        chats: (raw.chats ?? []).map(ChatSummary.fromJSON),
         created: new Date(raw.created),
     };
 }

package/dist/src/parrot/chat.d.ts

@@ -1,6 +1,6 @@
 import { Parrot } from "./index.js";
 import { Content } from "./generative.js";
-import { Credentials, ApiKey, Profile } from "../authentification.js";
+import { Credentials, ApiKey } from "../authentification.js";
 import { Group } from "../groups.js";
 import { ChatRoom, RoomHooks } from "./room.js";
 import { Presence } from "../shared/server.js";
@@ -40,17 +40,6 @@ export declare function createChat(authorization: Credentials | ApiKey, name?: s
     repository?: Repository;
 }): Promise<string>;
 export declare function deleteChat(authorization: Credentials | ApiKey, id: string, group?: Group): Promise<void>;
-export type LastMessage = {
-    parts: unknown[];
-    role: string;
-    createdAt: Date;
-    position: number;
-    author?: Profile;
-    model?: string;
-};
-export declare const LastMessage: {
-    fromJSON(json: unknown): LastMessage | null;
-};
 export type ChatSummary = {
     id: string;
     name: string;
@@ -63,11 +52,14 @@ export type ChatSummary = {
     repository: number | null;
     created: number;
     updated: number;
-    last: LastMessage | null;
+    last: Content | null;
     /** Messages the caller hasn't read. A person and each of their API keys keep
      *  their own place; one that never marked the chat sees only its newest 20. */
     unread: number;
 };
+export declare const ChatSummary: {
+    fromJSON(json: any): ChatSummary;
+};
 export declare function listChats(authorization: Credentials | ApiKey, group?: Group): Promise<ChatSummary[]>;
 export declare function renameChat(authorization: Credentials | ApiKey, id: string, name: string, group?: Group): Promise<void>;
 /**
@@ -76,6 +68,11 @@ export declare function renameChat(authorization: Credentials | ApiKey, id: stri
  * person. Sending a message reads the chat for its sender. Returns what's left unread.
  */
 export declare function markRead(authorization: Credentials | ApiKey, id: string, position?: number, group?: Group): Promise<number>;
+/**
+ * The rest of a draft reply in a chat, from its newest messages and how you write to the
+ * same people in its owner's other chats. Empty when the draft needs nothing more.
+ */
+export declare function autocomplete(authorization: Credentials | ApiKey, id: string, text: string, group?: Group): Promise<string>;
 /** One page of a chat, newest first. */
 export declare function readChat(authorization: Credentials | ApiKey, id: string, group: Group | undefined, query: {
     cursor: number;

package/dist/src/parrot/chat.js

@@ -1,5 +1,5 @@
 import { Parrot } from "./index.js";
-import { Profile } from "../authentification.js";
+import { Content } from "./generative.js";
 import * as Drive from "../drive.js";
 import { openRoom } from "./share.js";
 import { connectRoom } from "./room.js";
@@ -64,21 +64,19 @@ export async function deleteChat(authorization, id, group) {
     if (!response.ok)
         throw new Error(await response.text());
 }
-export const LastMessage = {
+export const ChatSummary = {
     fromJSON(json) {
-        if (!json || typeof json !== "object")
-            return null;
-        const row = json;
-        const createdAt = row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt);
-        if (Number.isNaN(createdAt.getTime()) || typeof row.position !== "number")
-            return null;
         return {
-            parts: Array.isArray(row.parts) ? row.parts : [],
-            role: String(row.role ?? ""),
-            createdAt,
-            position: row.position,
-            author: Profile.fromJSON(row.author),
-            model: row.model ? String(row.model) : undefined,
+            id: String(json.id),
+            name: typeof json.name === 'string' ? json.name : '',
+            principalId: typeof json.principalId === 'string' ? json.principalId : '',
+            human: json.human === true,
+            locked: json.locked === true,
+            repository: typeof json.repository === 'number' && json.repository > 0 ? json.repository : null,
+            created: Number(json.created ?? 0),
+            updated: Number(json.updated ?? 0),
+            last: json.last ? Content.fromJSON(json.last) : null,
+            unread: typeof json.unread === 'number' ? json.unread : 0,
         };
     },
 };
@@ -94,14 +92,7 @@ export async function listChats(authorization, group) {
     if (!response.ok)
         throw new Error(await response.text());
     const rows = await response.json();
-    return (Array.isArray(rows) ? rows : []).map((row) => ({
-        ...row,
-        human: row.human === true,
-        locked: row.locked === true,
-        repository: typeof row.repository === 'number' && row.repository > 0 ? row.repository : null,
-        last: LastMessage.fromJSON(row.last),
-        unread: typeof row.unread === 'number' ? row.unread : 0,
-    }));
+    return (Array.isArray(rows) ? rows : []).map(ChatSummary.fromJSON);
 }
 export async function renameChat(authorization, id, name, group) {
     const response = await fetch(`${Parrot.getURL()}/chat/rename`, {
@@ -136,6 +127,24 @@ export async function markRead(authorization, id, position, group) {
     const json = await response.json();
     return typeof json.unread === 'number' ? json.unread : 0;
 }
+/**
+ * The rest of a draft reply in a chat, from its newest messages and how you write to the
+ * same people in its owner's other chats. Empty when the draft needs nothing more.
+ */
+export async function autocomplete(authorization, id, text, group) {
+    const response = await fetch(`${Parrot.getURL()}/chat/autocomplete`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ id, text })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.text();
+}
 function fileRef(file) {
     const authorization = file.authorization;
     if ('accessCode' in authorization) {
@@ -174,27 +183,7 @@ export async function readChat(authorization, id, group, query) {
     if (!response.ok)
         throw new Error(await response.text());
     const json = await response.json();
-    const messages = [];
-    for (const message of Array.isArray(json) ? json : []) {
-        const parts = [];
-        for (const part of message.parts ?? []) {
-            if (part.type === 'FILE') {
-                parts.push(hydrateFilePart(authorization, part, group));
-            }
-            else {
-                parts.push(part);
-            }
-        }
-        messages.push({
-            parts,
-            role: message.role,
-            author: message.author,
-            model: message.model,
-            createdAt: new Date(message.createdAt),
-            ...(message.via ? { via: String(message.via) } : {}),
-        });
-    }
-    return messages;
+    return (Array.isArray(json) ? json : []).map((message) => Content.fromJSON(message, (part) => hydrateFilePart(authorization, part, group)));
 }
 export async function writeChat(authorization, id, messages, group) {
     const serializedMessages = [];

package/dist/src/parrot/generative.d.ts

@@ -1,3 +1,4 @@
+import { Parrot } from "./index.js";
 import { Credentials, ApiKey, Profile } from "../authentification.js";
 import type { File as FaunaFile } from "../drive.js";
 import type { Demographic } from "../ant/persona.js";
@@ -89,6 +90,11 @@ export type TextPart = {
     type: 'TEXT';
     text: string;
 };
+/** A body written in HTML, such as an email's. Chat UIs draw it as it is; models read its text. */
+export type HtmlPart = {
+    type: 'HTML';
+    html: string;
+};
 export type File = {
     type: 'FILE';
     file: FaunaFile;
@@ -118,7 +124,7 @@ export type Reaction = {
     position: number;
     on: boolean;
 };
-export type Part = TextPart | File | Invocation | Result | Reaction;
+export type Part = TextPart | HtmlPart | File | Invocation | Result | Reaction;
 export type Function = {
     name: string;
     parameters: Schema;
@@ -132,15 +138,28 @@ export type Tool = {
     evaluate: (params: any) => Promise<string>;
     instruction?: (params: any) => string;
 };
+/**
+ * Who wrote a message: a person, an agent posting with an API key (only its `name`, never
+ * its id), an app's own agent (`'MODEL'`, such as an inbox agent), or an outside address
+ * such as a phone number or an email. Parrot's own model replies have none; their `model`
+ * says which model wrote them.
+ */
+export type Author = Profile | Partial<ApiKey> | 'MODEL' | string;
+export declare const Author: {
+    fromJSON(json: unknown): Author | undefined;
+};
 export type Content = {
     parts: Part[];
     role: Role;
     createdAt: Date;
-    author?: Profile;
-    /** Text model id that produced a MODEL turn (for UI avatar / rehydrate). */
-    model?: string;
-    /** The name of the API key an agent posted this with, for its author. */
-    via?: string;
+    author?: Author;
+    /** The model that wrote a MODEL turn. */
+    model?: Text;
+};
+export declare const Content: {
+    /** A message off the wire. `file` turns each FILE part into a `FaunaFile`; without it
+     *  parts pass through as sent. */
+    fromJSON(json: any, file?: (part: any) => Part): Content;
 };
 export type TextResponse = {
     content: Content;

package/dist/src/parrot/generative.js

@@ -1,4 +1,5 @@
 import { Parrot } from "./index.js";
+import { Profile } from "../authentification.js";
 import { collectText, collectVoice, generateMedia, prepareMessages, streamText, streamVoice } from "./socket.js";
 // Text Clients
 export var Text;
@@ -111,6 +112,32 @@ export var Role;
     Role["SYSTEM"] = "SYSTEM";
     Role["TOOL"] = "TOOL";
 })(Role || (Role = {}));
+export const Author = {
+    fromJSON(json) {
+        if (typeof json === 'string')
+            return json || undefined;
+        if (!json || typeof json !== 'object')
+            return undefined;
+        const profile = Profile.fromJSON(json);
+        if (profile)
+            return profile;
+        const name = json.name;
+        return typeof name === 'string' ? { name } : undefined;
+    },
+};
+export const Content = {
+    /** A message off the wire. `file` turns each FILE part into a `FaunaFile`; without it
+     *  parts pass through as sent. */
+    fromJSON(json, file) {
+        return {
+            parts: (Array.isArray(json?.parts) ? json.parts : []).map((part) => part?.type === 'FILE' && file ? file(part) : part),
+            role: json?.role,
+            createdAt: new Date(json?.createdAt),
+            author: Author.fromJSON(json?.author),
+            model: json?.model ? json.model : undefined,
+        };
+    },
+};
 // Streaming Text Generation. A singular Tool forces it; an array lets the model choose.
 export async function* generateText(authorization, model, options = {}) {
     yield* streamText(authorization, '/generative/text', model, options);