@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/dist/types.d.ts

@@ -0,0 +1,534 @@
+import { ChannelKind } from "./about.js";
+import { Surface } from "./blocks.js";
+//#region src/types.d.ts
+/** The channel a conversation is on, as a list draws it. */
+export interface ChannelGlance {
+  id: string;
+  kind: ChannelKind;
+  /** The number, the @username. */
+  name: string;
+}
+/** The person a conversation on a channel is with, or a person who signed in to the host's app. */
+export interface ContactGlance {
+  id: string;
+  /** As they show it on the channel; null when it doesn't say. */
+  name: string | null;
+  /** Where they are on it: the number, the Instagram id; their account in the host's app. */
+  address: string;
+  /** The owner marked them: the agent doesn't answer them; left out by an API from before. */
+  muted?: boolean | undefined;
+}
+/**
+ * Who answers a conversation: its agent; a person of the business (the agent paused in it: it
+ * handed it over, or one of them wrote in it); or nobody (it is ignored: what comes is kept, never
+ * answered).
+ */
+export type Holder = "agent" | "person" | "nobody";
+/** A change of who answers a conversation: to whom, why, who changed it and when. */
+export interface Handover {
+  holder: Holder;
+  /** Why, in the words of whoever changed it; "" when they said nothing. */
+  reason: string;
+  /**
+   * `owner` (a person of the business), `agent` (its `escalate`), `platform`, or an automation by
+   * its file's name.
+   */
+  by: string;
+  /** The automation's title, when one changed it. */
+  title: string | null;
+  at: string;
+}
+/**
+ * What was decided of a person's message on a channel before the agent answered it: `deciding`
+ * while the automations that decide go; then the agent answers it (`answer`), lets it pass this
+ * time (`skip`), or the conversation goes to a person (`hold`) or to nobody (`ignore`).
+ */
+export interface Decision {
+  kind: "deciding" | "answer" | "skip" | "hold" | "ignore";
+  /** Why, in the owner's words; null when it says nothing. */
+  reason: string | null;
+  /** The automation that decided, by its file's name; null when the platform did (a filter, the hours). */
+  automation: string | null;
+  /** Its title. */
+  title: string | null;
+  /** Its run that decided. */
+  run_id: string | null;
+}
+/** A conversation between a person and one agent. */
+export interface Conversation {
+  id: string;
+  agent_id: string;
+  /** A turn stopped, waiting for the person to answer on a surface. */
+  pending: boolean;
+  /** Who answers it now: its agent, a person of the business, or nobody. */
+  handled_by: Holder;
+  /** Its last change of who answers it; null when it never changed, left out by an older API. */
+  handover?: Handover | null | undefined;
+  /** The owner trying the agent out: no customer sees it, and it is never the agent's activity. */
+  test: boolean;
+  created_at: string;
+  /** Its title in a list: what a person first said in it; null while they've said nothing. */
+  title: string | null;
+  /** On a channel: which, and the person; null (or left out by an older API) elsewhere. */
+  channel?: ChannelGlance | null | undefined;
+  contact?: ContactGlance | null | undefined;
+  /** On a channel: when the agent's reply is due, once the person has been quiet a moment. */
+  reply_due_at?: string | null | undefined;
+  /** On a channel: when the person last wrote (WhatsApp's 24 h window counts from it). */
+  last_inbound_at?: string | null | undefined;
+  /** The call it is, when it is one; null elsewhere, and left out by an API from before calls. */
+  call?: CallGlance | null | undefined;
+  /**
+   * Who it is with, when a person's token or a publishable key started it: a person of the
+   * host's app (`host_person`, its `contact` then) or the widget's visitor.
+   */
+  person?: ConversationPerson | null | undefined;
+}
+/** Who a person's token or a publishable key started a conversation for. */
+export interface ConversationPerson {
+  kind: "host_person" | "visitor" | "contact" | "owner";
+  /** The host's id for them, the visitor's id. */
+  external_id: string;
+  name: string | null;
+  email: string | null;
+}
+/**
+ * Why a call ended, as the API keeps it: the caller hung up, the agent said goodbye, it reached
+ * its longest time, it failed, its end never came, or it was never taken.
+ */
+export type CallReason = "caller" | "agent" | "max_duration" | "error" | "lost" | "missed";
+/**
+ * The call a conversation is (v3/VOICE.md): the owner's in the browser or a phone call, when the
+ * agent took it and when it ended, why and how long.
+ */
+export interface CallGlance {
+  id: string;
+  kind: "browser" | "phone";
+  /** Null while it is on. */
+  reason: CallReason | null;
+  /** From when the agent took it to when it ended; null while it is on. */
+  seconds: number | null;
+  started_at: string | null;
+  ended_at: string | null;
+  /** Whether it was recorded, to play from the conversation; left out by an older API. */
+  recording?: boolean | undefined;
+}
+/** Who said a message on a channel: the person, the agent, or a person of the business. */
+export type Author = "contact" | "agent" | "operator";
+/** Where a message that goes out on a channel got to: it only moves forward, and `failed` wins. */
+export type Delivery = "queued" | "sent" | "delivered" | "read" | "failed";
+/** How a channel's account stands, as its provider last said. */
+export type ChannelStatus = "pending" | "active" | "error" | "disconnected";
+/** A day of the week, as a channel's hours name it. */
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+/** A stretch of a day, from one time to a later one ("HH:MM"). */
+export interface HoursSpan {
+  start: string;
+  end: string;
+}
+/**
+ * A week of hours in the agent's time zone: each day's stretches, in order and apart, four at
+ * most; a day left out, or empty, is closed.
+ */
+export type WeekHours = Partial<Record<Weekday, HoursSpan[]>>;
+/**
+ * How the agent behaves on a channel, the same for every text channel (each shows only what its
+ * medium can do): when it answers, how what it says goes out, and what it is told there.
+ */
+export interface ChannelSettings {
+  /** It answers on this channel; off, everything goes to the inbox for a person. */
+  answers: boolean;
+  /** Who it answers, in the owner's words; null: everyone. */
+  filter: string | null;
+  /** Words that, said in a message, have it answer without weighing the filter. */
+  filter_keywords: string[];
+  /** The week it keeps; null: it answers at any hour. */
+  hours: WeekHours | null;
+  /** It answers inside the hours, or outside them (the business's people take the hours). */
+  answers_when: "in_hours" | "out_of_hours";
+  /** Sent once per conversation while the hours keep it from answering; null: nothing. */
+  away_message: string | null;
+  /** WhatsApp: it answers in group chats too. */
+  groups: boolean;
+  /**
+   * A conversation a person took over goes back to the agent after this long without them; null:
+   * it stays theirs until they give it back.
+   */
+  auto_release_after_h: number | null;
+  /** What it is told on this channel only, besides its own instructions. */
+  instructions: string | null;
+  /** The quiet period after the person's last message before the agent answers them all. */
+  reply_delay_s: number;
+  /** A long answer goes in up to three messages as a person writes them, its words as they are. */
+  split: boolean;
+  /** The channel shows the agent writing between the parts of an answer, where it can. */
+  typing: boolean;
+  /** WhatsApp, past 24 h since the person last wrote: the template that carries the answer. */
+  window_template: string | null;
+  /**
+   * WhatsApp: the answer as a voice note in the agent's voice, its words kept as what it said;
+   * never, when the person's last message was a voice note, or always.
+   */
+  voice_replies: "never" | "when_voice" | "always";
+}
+/**
+ * An account on a provider (a WhatsApp number, an Instagram account, an SMS number) and the agent
+ * that answers it (`GET /channels?agent=`).
+ */
+export interface Channel {
+  id: string;
+  agent_id: string;
+  kind: "whatsapp" | "instagram" | "sms" | "phone" | "web";
+  /** meta · twilio · livekit · signalcore (the widget) */
+  provider: string;
+  /** The number, the @username. */
+  name: string;
+  /** The provider's id for the account. */
+  external_id: string;
+  /** A phone number's: where its provider sends its calls (a SIP address); null for others. */
+  address: string | null;
+  /** A phone number's: whether the agent calls out from it (it has the number's SIP login). */
+  outbound: boolean;
+  status: ChannelStatus;
+  /** The provider's word on its status, or what went wrong; null when it said nothing. */
+  detail: string | null;
+  settings: ChannelSettings;
+  /** A web channel's: the widget's publishable key, its sites and its look; null for others. */
+  web: ChannelWeb | null;
+  created_at: string;
+}
+/** The widget a web channel is: the key its line carries, the sites it loads on, its look. */
+export interface ChannelWeb {
+  key: string;
+  origins: string[];
+  appearance: WidgetLook;
+}
+export type StepState = "running" | "waiting" | "done" | "failed";
+/**
+ * Who gives the yes an action waits for: the person on the screen (the turn stopped for it), or
+ * the business (the turn went on; its people allow or decline it from the app, the inbox).
+ */
+export type Decides = "person" | "business";
+/** An action the platform will not run until it is allowed: what, with what input, by whom. */
+export interface Request {
+  action: string;
+  input: Record<string, unknown>;
+  /** The person's when left out (an API from before it). */
+  decides?: Decides | undefined;
+}
+/** An action a reply called: what, how it went, and what it drew. */
+export interface Step {
+  id: string;
+  action: string;
+  state: StepState;
+  output: string | null;
+  surface: Surface | null;
+  /**
+   * The turn stopped on it: the person's answer on its surface carries it on. Never a host's tool
+   * the page runs, nor a yes the business gives.
+   */
+  awaits: boolean;
+  /** Set while it waits to be allowed: by the person (the turn stopped), or by the business. */
+  request: Request | null;
+}
+/**
+ * What a person did on a surface: `surface` is its id, `name` the block's action, `data` what it
+ * carries (a pick, a form's values), `label` the words the app shows for it.
+ */
+export interface Action {
+  surface: string;
+  name: string;
+  data: Record<string, unknown>;
+  label: string;
+}
+/** What is read of a message: who said it, its text, what it did on a surface, its steps. */
+export interface Message {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  /** When the message came from a surface; `text` is then its label. */
+  action: Action | null;
+  steps: Step[];
+  /** The files the person sent with it; an API from before files leaves it out. */
+  files?: Attachment[] | undefined;
+  /** On a channel, who said it; null elsewhere. A person of the business's is `assistant`. */
+  author?: Author | null | undefined;
+  /** On a channel, where what goes out got to, and why it failed when it did. */
+  delivery?: Delivery | null | undefined;
+  delivery_error?: string | null | undefined;
+  /** Gone out on a channel in several parts: the words of each, in order; null as one. */
+  pieces?: string[] | null | undefined;
+  /** Going out on a channel: how many of its parts went so far; null for what doesn't go out. */
+  sent_parts?: number | null | undefined;
+  /**
+   * On a channel, a voice note, the person's or the agent's: its file, played with `text` (what
+   * was said) under it; null otherwise, and left out by an API from before voice notes.
+   */
+  voice?: Attachment | null | undefined;
+  /**
+   * On a call, a person's message: what they heard of the agent's last words before saying it,
+   * when that isn't what was stored (a reply or the greeting they cut short; "" for nothing of
+   * it); null otherwise, and left out by an API from before calls.
+   */
+  heard?: string | null | undefined;
+  /** On a channel, a person's message: what was decided of it; null otherwise. */
+  decision?: Decision | null | undefined;
+  created_at: string;
+}
+/**
+ * A call with an agent from the browser (the owner's test, `POST /agents/{id}/voice/token`; anyone
+ * who may talk to it, a person's as theirs, `POST /agents/{id}/calls`): LiveKit's address, a token
+ * to join the call's room (for 10 minutes), and the call and its own conversation, made with it,
+ * whose live socket shows what is said.
+ */
+export interface CallToken {
+  url: string;
+  token: string;
+  room: string;
+  call_id: string;
+  conversation_id: string;
+}
+/** A file that arrived in a conversation, as a message carries it. */
+export interface Attachment {
+  id: string;
+  name: string;
+  media_type: string;
+  size: number;
+}
+/** A conversation's file, as the API stores it (`POST /conversations/{id}/files`). */
+export interface ConversationFile extends Attachment {
+  conversation_id: string;
+  created_at: string;
+}
+/** A conversation with its messages, in the order they were said. */
+export interface ConversationDetail extends Conversation {
+  messages: Message[];
+  /** Every change of who answers it, in order; left out by an API from before them. */
+  handovers?: Handover[] | undefined;
+}
+/**
+ * How far a searchable file's index is: its passages being made, made, or failed; what to know
+ * of it (why it failed, what of it can't be searched); its pages without text the model read.
+ */
+export interface FileIndex {
+  state: "indexing" | "ready" | "failed";
+  detail: string | null;
+  scanned: number;
+}
+/** A file kept under a name: the organization's, or an agent's own. */
+export interface StoredFile {
+  id: string;
+  path: string;
+  media_type: string;
+  size: number;
+  /** Text, Markdown, JSON, YAML or PDF, read by `search_files`; anything else is only kept. */
+  searchable: boolean;
+  /** Its index, while it is searchable; left out by an API from before it. */
+  index?: FileIndex | null | undefined;
+  created_at: string;
+}
+/**
+ * Where a file is, for what reads any of them: the organization's or an agent's own by its path,
+ * a conversation's by its id.
+ */
+export type FileAt = {
+  path: string;
+} | {
+  agentId: string;
+  path: string;
+} | {
+  conversationId: string;
+  fileId: string;
+};
+/** A PDF: the viewer draws the bytes it fetches. Null pages when they can't be counted. */
+export interface PdfPreview {
+  kind: "pdf";
+  pages: number | null;
+}
+/**
+ * One sheet: its first row with anything in it as its columns (null for an empty sheet), and the
+ * rows under it, the first 500 (an empty row between two as `[]`), each cell as Excel shows it;
+ * `total_rows`, every row under its columns.
+ */
+export interface PreviewSheet {
+  name: string;
+  columns: string[] | null;
+  rows: string[][];
+  total_rows: number;
+}
+/** A spreadsheet's sheets (20 at most), or a CSV as one, named as its file. */
+export interface SheetPreview {
+  kind: "sheet";
+  sheets: PreviewSheet[];
+  /** Rows, columns (50 at most), long cells or sheets were left out. */
+  truncated: boolean;
+}
+/**
+ * A Word file as simple HTML: headings, paragraphs, lists, tables, bold and italic, small
+ * pictures as data URLs. Cleaned by the API against an allow-list: nothing in it runs, styles
+ * or loads from another address.
+ */
+export interface DocumentPreview {
+  kind: "document";
+  html: string;
+  truncated: boolean;
+}
+/** A slide: its title (null without one), the words of its other shapes, its notes. */
+export interface PreviewSlide {
+  title: string | null;
+  text: string;
+  notes: string | null;
+}
+/** A deck's slides, in order. */
+export interface SlidesPreview {
+  kind: "slides";
+  slides: PreviewSlide[];
+  truncated: boolean;
+}
+/** Words as written: Markdown, plain text, JSON. */
+export interface TextPreview {
+  kind: "markdown" | "text" | "json";
+  text: string;
+  truncated: boolean;
+}
+/** A source as written, never run (HTML too), in the language highlighters name it by. */
+export interface CodePreview {
+  kind: "code";
+  text: string;
+  truncated: boolean;
+  language: string;
+}
+/** A picture, a video or a sound: the viewer plays the bytes, typed as `media_type`. */
+export interface MediaPreview {
+  kind: "image" | "video" | "audio";
+  media_type: string;
+}
+/** Nothing to draw: a kind no viewer shows, or a file that can't be read; it is saved. */
+export interface UnknownPreview {
+  kind: "unknown";
+}
+/**
+ * What a viewer draws of a file (`GET …/preview`), by its `kind`. What is too long answers what
+ * fits, with `truncated`.
+ */
+export type FilePreview = PdfPreview | SheetPreview | DocumentPreview | SlidesPreview | TextPreview | CodePreview | MediaPreview | UnknownPreview;
+/**
+ * A file the agent shows in a surface (`show`'s `file` block): it names one it may read (`path`:
+ * its own or the organization's by path, or the conversation's by id), and the API fills in
+ * `file`, the conversation's file it put there (`{conversationId, fileId}` to preview and fetch
+ * it); null while there is none (the reply's message before the show ran, or one it refused).
+ */
+export interface FileBlock {
+  type: "file";
+  path: string;
+  /** Over it; none: its name. */
+  title?: string;
+  file: Attachment | null;
+}
+/** Who holds the conversation's browser: the agent drives it, or the person does. */
+export type BrowserControl = "agent" | "person";
+/** Whose the browser is: a clean one in the cloud, or the owner's own Chrome. */
+export type BrowserWhere = "hosted" | "mine";
+/**
+ * The conversation's hosted browser, while it is open: where it is, who holds it, and, when the
+ * agent handed it over, why (`reason`) and the step the person's answer carries on (`wait`).
+ * `width` and `height` are the page's, the pixels its pointer events are in.
+ */
+export interface BrowserState {
+  where: BrowserWhere;
+  url: string;
+  title: string;
+  control: BrowserControl;
+  reason: string | null;
+  wait: string | null;
+  width: number;
+  height: number;
+}
+/** A picture of the browser's screen: a JPEG in base64, showing the page at this size. */
+export interface BrowserFrame {
+  jpeg: string;
+  width: number;
+  height: number;
+}
+/**
+ * What the person does on the browser's screen while they hold it, in the page's pixels: the
+ * pointer, the wheel, keys (the DOM's `key`, `code` and `keyCode`; `modifiers` is Alt 1, Ctrl 2,
+ * Meta 4, Shift 8) and text pasted.
+ */
+export type BrowserInput = {
+  kind: "mouse";
+  action: "move" | "down" | "up";
+  x: number;
+  y: number;
+  button?: "left" | "middle" | "right";
+  clicks?: number;
+} | {
+  kind: "wheel";
+  x: number;
+  y: number;
+  dx: number;
+  dy: number;
+} | {
+  kind: "key";
+  action: "down" | "up";
+  key: string;
+  code: string;
+  keyCode: number;
+  modifiers: number;
+} | {
+  kind: "paste";
+  text: string;
+};
+/**
+ * What a person may know of the agent they talk to (`GET /agents/{id}/face`): its name, its role
+ * in a line, the mark of its work (an `AgentIcon`; null until it picked one) and whether it takes
+ * calls.
+ */
+/**
+ * How a web channel's widget looks (`PUT /channels/{id}/appearance`): each unset field keeps the
+ * widget's own default (the page's type and ink, neutral greys). Colours are `#rrggbb`, sizes
+ * pixels; `css` is the widget's own stylesheet, drawn inside it after ours.
+ */
+export interface WidgetLook {
+  accent?: string | null;
+  accent_fg?: string | null;
+  font?: WidgetFont | null;
+  radius?: number | null;
+  theme?: "auto" | "light" | "dark";
+  position?: "right" | "left";
+  launcher_size?: number | null;
+  panel_width?: number | null;
+  panel_height?: number | null;
+  header?: boolean;
+  css?: string | null;
+}
+/** The faces a widget may wear besides the page's own: Google Fonts it loads by name. */
+export declare const WIDGET_FONTS: readonly ["Inter", "Manrope", "DM Sans", "Plus Jakarta Sans", "Poppins", "Nunito", "Lora", "Playfair Display"];
+export type WidgetFont = (typeof WIDGET_FONTS)[number];
+/** What the widget reads as it loads, by its publishable key: its agent, and how it looks. */
+export interface WidgetConfig {
+  agent_id: string;
+  agent_name: string;
+  appearance: WidgetLook;
+}
+export interface AgentFace {
+  id: string;
+  name: string;
+  /** "" when it has none. */
+  role: string;
+  icon: string | null;
+  voice: {
+    enabled: boolean;
+  };
+}
+/**
+ * One of the host's own tools the agent called, to run in the page (a tool declared `client` on
+ * the agent): the call's id, the tool's name, and what the agent gave it, as its JSON Schema says.
+ */
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+//#endregion
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,16 @@
+//#region src/types.ts
+/** The faces a widget may wear besides the page's own: Google Fonts it loads by name. */
+const WIDGET_FONTS = [
+	"Inter",
+	"Manrope",
+	"DM Sans",
+	"Plus Jakarta Sans",
+	"Poppins",
+	"Nunito",
+	"Lora",
+	"Playfair Display"
+];
+//#endregion
+export { WIDGET_FONTS };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/** The API's objects this package reads (v3/README.md). */\n\nimport type { ChannelKind } from \"./about\";\nimport type { Surface } from \"./blocks\";\n\n/** The channel a conversation is on, as a list draws it. */\nexport interface ChannelGlance {\n  id: string;\n  kind: ChannelKind;\n  /** The number, the @username. */\n  name: string;\n}\n\n/** The person a conversation on a channel is with, or a person who signed in to the host's app. */\nexport interface ContactGlance {\n  id: string;\n  /** As they show it on the channel; null when it doesn't say. */\n  name: string | null;\n  /** Where they are on it: the number, the Instagram id; their account in the host's app. */\n  address: string;\n  /** The owner marked them: the agent doesn't answer them; left out by an API from before. */\n  muted?: boolean | undefined;\n}\n\n/**\n * Who answers a conversation: its agent; a person of the business (the agent paused in it: it\n * handed it over, or one of them wrote in it); or nobody (it is ignored: what comes is kept, never\n * answered).\n */\nexport type Holder = \"agent\" | \"person\" | \"nobody\";\n\n/** A change of who answers a conversation: to whom, why, who changed it and when. */\nexport interface Handover {\n  holder: Holder;\n  /** Why, in the words of whoever changed it; \"\" when they said nothing. */\n  reason: string;\n  /**\n   * `owner` (a person of the business), `agent` (its `escalate`), `platform`, or an automation by\n   * its file's name.\n   */\n  by: string;\n  /** The automation's title, when one changed it. */\n  title: string | null;\n  at: string;\n}\n\n/**\n * What was decided of a person's message on a channel before the agent answered it: `deciding`\n * while the automations that decide go; then the agent answers it (`answer`), lets it pass this\n * time (`skip`), or the conversation goes to a person (`hold`) or to nobody (`ignore`).\n */\nexport interface Decision {\n  kind: \"deciding\" | \"answer\" | \"skip\" | \"hold\" | \"ignore\";\n  /** Why, in the owner's words; null when it says nothing. */\n  reason: string | null;\n  /** The automation that decided, by its file's name; null when the platform did (a filter, the hours). */\n  automation: string | null;\n  /** Its title. */\n  title: string | null;\n  /** Its run that decided. */\n  run_id: string | null;\n}\n\n/** A conversation between a person and one agent. */\nexport interface Conversation {\n  id: string;\n  agent_id: string;\n  /** A turn stopped, waiting for the person to answer on a surface. */\n  pending: boolean;\n  /** Who answers it now: its agent, a person of the business, or nobody. */\n  handled_by: Holder;\n  /** Its last change of who answers it; null when it never changed, left out by an older API. */\n  handover?: Handover | null | undefined;\n  /** The owner trying the agent out: no customer sees it, and it is never the agent's activity. */\n  test: boolean;\n  created_at: string;\n  /** Its title in a list: what a person first said in it; null while they've said nothing. */\n  title: string | null;\n  /** On a channel: which, and the person; null (or left out by an older API) elsewhere. */\n  channel?: ChannelGlance | null | undefined;\n  contact?: ContactGlance | null | undefined;\n  /** On a channel: when the agent's reply is due, once the person has been quiet a moment. */\n  reply_due_at?: string | null | undefined;\n  /** On a channel: when the person last wrote (WhatsApp's 24 h window counts from it). */\n  last_inbound_at?: string | null | undefined;\n  /** The call it is, when it is one; null elsewhere, and left out by an API from before calls. */\n  call?: CallGlance | null | undefined;\n  /**\n   * Who it is with, when a person's token or a publishable key started it: a person of the\n   * host's app (`host_person`, its `contact` then) or the widget's visitor.\n   */\n  person?: ConversationPerson | null | undefined;\n}\n\n/** Who a person's token or a publishable key started a conversation for. */\nexport interface ConversationPerson {\n  kind: \"host_person\" | \"visitor\" | \"contact\" | \"owner\";\n  /** The host's id for them, the visitor's id. */\n  external_id: string;\n  name: string | null;\n  email: string | null;\n}\n\n/**\n * Why a call ended, as the API keeps it: the caller hung up, the agent said goodbye, it reached\n * its longest time, it failed, its end never came, or it was never taken.\n */\nexport type CallReason = \"caller\" | \"agent\" | \"max_duration\" | \"error\" | \"lost\" | \"missed\";\n\n/**\n * The call a conversation is (v3/VOICE.md): the owner's in the browser or a phone call, when the\n * agent took it and when it ended, why and how long.\n */\nexport interface CallGlance {\n  id: string;\n  kind: \"browser\" | \"phone\";\n  /** Null while it is on. */\n  reason: CallReason | null;\n  /** From when the agent took it to when it ended; null while it is on. */\n  seconds: number | null;\n  started_at: string | null;\n  ended_at: string | null;\n  /** Whether it was recorded, to play from the conversation; left out by an older API. */\n  recording?: boolean | undefined;\n}\n\n/** Who said a message on a channel: the person, the agent, or a person of the business. */\nexport type Author = \"contact\" | \"agent\" | \"operator\";\n\n/** Where a message that goes out on a channel got to: it only moves forward, and `failed` wins. */\nexport type Delivery = \"queued\" | \"sent\" | \"delivered\" | \"read\" | \"failed\";\n\n/** How a channel's account stands, as its provider last said. */\nexport type ChannelStatus = \"pending\" | \"active\" | \"error\" | \"disconnected\";\n\n/** A day of the week, as a channel's hours name it. */\nexport type Weekday = \"mon\" | \"tue\" | \"wed\" | \"thu\" | \"fri\" | \"sat\" | \"sun\";\n\n/** A stretch of a day, from one time to a later one (\"HH:MM\"). */\nexport interface HoursSpan {\n  start: string;\n  end: string;\n}\n\n/**\n * A week of hours in the agent's time zone: each day's stretches, in order and apart, four at\n * most; a day left out, or empty, is closed.\n */\nexport type WeekHours = Partial<Record<Weekday, HoursSpan[]>>;\n\n/**\n * How the agent behaves on a channel, the same for every text channel (each shows only what its\n * medium can do): when it answers, how what it says goes out, and what it is told there.\n */\nexport interface ChannelSettings {\n  /** It answers on this channel; off, everything goes to the inbox for a person. */\n  answers: boolean;\n  /** Who it answers, in the owner's words; null: everyone. */\n  filter: string | null;\n  /** Words that, said in a message, have it answer without weighing the filter. */\n  filter_keywords: string[];\n  /** The week it keeps; null: it answers at any hour. */\n  hours: WeekHours | null;\n  /** It answers inside the hours, or outside them (the business's people take the hours). */\n  answers_when: \"in_hours\" | \"out_of_hours\";\n  /** Sent once per conversation while the hours keep it from answering; null: nothing. */\n  away_message: string | null;\n  /** WhatsApp: it answers in group chats too. */\n  groups: boolean;\n  /**\n   * A conversation a person took over goes back to the agent after this long without them; null:\n   * it stays theirs until they give it back.\n   */\n  auto_release_after_h: number | null;\n  /** What it is told on this channel only, besides its own instructions. */\n  instructions: string | null;\n  /** The quiet period after the person's last message before the agent answers them all. */\n  reply_delay_s: number;\n  /** A long answer goes in up to three messages as a person writes them, its words as they are. */\n  split: boolean;\n  /** The channel shows the agent writing between the parts of an answer, where it can. */\n  typing: boolean;\n  /** WhatsApp, past 24 h since the person last wrote: the template that carries the answer. */\n  window_template: string | null;\n  /**\n   * WhatsApp: the answer as a voice note in the agent's voice, its words kept as what it said;\n   * never, when the person's last message was a voice note, or always.\n   */\n  voice_replies: \"never\" | \"when_voice\" | \"always\";\n}\n\n/**\n * An account on a provider (a WhatsApp number, an Instagram account, an SMS number) and the agent\n * that answers it (`GET /channels?agent=`).\n */\nexport interface Channel {\n  id: string;\n  agent_id: string;\n  kind: \"whatsapp\" | \"instagram\" | \"sms\" | \"phone\" | \"web\";\n  /** meta · twilio · livekit · signalcore (the widget) */\n  provider: string;\n  /** The number, the @username. */\n  name: string;\n  /** The provider's id for the account. */\n  external_id: string;\n  /** A phone number's: where its provider sends its calls (a SIP address); null for others. */\n  address: string | null;\n  /** A phone number's: whether the agent calls out from it (it has the number's SIP login). */\n  outbound: boolean;\n  status: ChannelStatus;\n  /** The provider's word on its status, or what went wrong; null when it said nothing. */\n  detail: string | null;\n  settings: ChannelSettings;\n  /** A web channel's: the widget's publishable key, its sites and its look; null for others. */\n  web: ChannelWeb | null;\n  created_at: string;\n}\n\n/** The widget a web channel is: the key its line carries, the sites it loads on, its look. */\nexport interface ChannelWeb {\n  key: string;\n  origins: string[];\n  appearance: WidgetLook;\n}\n\nexport type StepState = \"running\" | \"waiting\" | \"done\" | \"failed\";\n\n/**\n * Who gives the yes an action waits for: the person on the screen (the turn stopped for it), or\n * the business (the turn went on; its people allow or decline it from the app, the inbox).\n */\nexport type Decides = \"person\" | \"business\";\n\n/** An action the platform will not run until it is allowed: what, with what input, by whom. */\nexport interface Request {\n  action: string;\n  input: Record<string, unknown>;\n  /** The person's when left out (an API from before it). */\n  decides?: Decides | undefined;\n}\n\n/** An action a reply called: what, how it went, and what it drew. */\nexport interface Step {\n  id: string;\n  action: string;\n  state: StepState;\n  output: string | null;\n  surface: Surface | null;\n  /**\n   * The turn stopped on it: the person's answer on its surface carries it on. Never a host's tool\n   * the page runs, nor a yes the business gives.\n   */\n  awaits: boolean;\n  /** Set while it waits to be allowed: by the person (the turn stopped), or by the business. */\n  request: Request | null;\n}\n\n/**\n * What a person did on a surface: `surface` is its id, `name` the block's action, `data` what it\n * carries (a pick, a form's values), `label` the words the app shows for it.\n */\nexport interface Action {\n  surface: string;\n  name: string;\n  data: Record<string, unknown>;\n  label: string;\n}\n\n/** What is read of a message: who said it, its text, what it did on a surface, its steps. */\nexport interface Message {\n  id: string;\n  role: \"user\" | \"assistant\";\n  text: string;\n  /** When the message came from a surface; `text` is then its label. */\n  action: Action | null;\n  steps: Step[];\n  /** The files the person sent with it; an API from before files leaves it out. */\n  files?: Attachment[] | undefined;\n  /** On a channel, who said it; null elsewhere. A person of the business's is `assistant`. */\n  author?: Author | null | undefined;\n  /** On a channel, where what goes out got to, and why it failed when it did. */\n  delivery?: Delivery | null | undefined;\n  delivery_error?: string | null | undefined;\n  /** Gone out on a channel in several parts: the words of each, in order; null as one. */\n  pieces?: string[] | null | undefined;\n  /** Going out on a channel: how many of its parts went so far; null for what doesn't go out. */\n  sent_parts?: number | null | undefined;\n  /**\n   * On a channel, a voice note, the person's or the agent's: its file, played with `text` (what\n   * was said) under it; null otherwise, and left out by an API from before voice notes.\n   */\n  voice?: Attachment | null | undefined;\n  /**\n   * On a call, a person's message: what they heard of the agent's last words before saying it,\n   * when that isn't what was stored (a reply or the greeting they cut short; \"\" for nothing of\n   * it); null otherwise, and left out by an API from before calls.\n   */\n  heard?: string | null | undefined;\n  /** On a channel, a person's message: what was decided of it; null otherwise. */\n  decision?: Decision | null | undefined;\n  created_at: string;\n}\n\n/**\n * A call with an agent from the browser (the owner's test, `POST /agents/{id}/voice/token`; anyone\n * who may talk to it, a person's as theirs, `POST /agents/{id}/calls`): LiveKit's address, a token\n * to join the call's room (for 10 minutes), and the call and its own conversation, made with it,\n * whose live socket shows what is said.\n */\nexport interface CallToken {\n  url: string;\n  token: string;\n  room: string;\n  call_id: string;\n  conversation_id: string;\n}\n\n/** A file that arrived in a conversation, as a message carries it. */\nexport interface Attachment {\n  id: string;\n  name: string;\n  media_type: string;\n  size: number;\n}\n\n/** Where a file of a conversation plays from, until `expires_at`: a path under the API's root. */\nexport interface FileLink {\n  path: string;\n  expires_at: string;\n}\n\n/** A conversation's file, as the API stores it (`POST /conversations/{id}/files`). */\nexport interface ConversationFile extends Attachment {\n  conversation_id: string;\n  created_at: string;\n}\n\n/** A conversation with its messages, in the order they were said. */\nexport interface ConversationDetail extends Conversation {\n  messages: Message[];\n  /** Every change of who answers it, in order; left out by an API from before them. */\n  handovers?: Handover[] | undefined;\n}\n\n/**\n * How far a searchable file's index is: its passages being made, made, or failed; what to know\n * of it (why it failed, what of it can't be searched); its pages without text the model read.\n */\nexport interface FileIndex {\n  state: \"indexing\" | \"ready\" | \"failed\";\n  detail: string | null;\n  scanned: number;\n}\n\n/** A file kept under a name: the organization's, or an agent's own. */\nexport interface StoredFile {\n  id: string;\n  path: string;\n  media_type: string;\n  size: number;\n  /** Text, Markdown, JSON, YAML or PDF, read by `search_files`; anything else is only kept. */\n  searchable: boolean;\n  /** Its index, while it is searchable; left out by an API from before it. */\n  index?: FileIndex | null | undefined;\n  created_at: string;\n}\n\n/**\n * Where a file is, for what reads any of them: the organization's or an agent's own by its path,\n * a conversation's by its id.\n */\nexport type FileAt =\n  { path: string } | { agentId: string; path: string } | { conversationId: string; fileId: string };\n\n/** A PDF: the viewer draws the bytes it fetches. Null pages when they can't be counted. */\nexport interface PdfPreview {\n  kind: \"pdf\";\n  pages: number | null;\n}\n\n/**\n * One sheet: its first row with anything in it as its columns (null for an empty sheet), and the\n * rows under it, the first 500 (an empty row between two as `[]`), each cell as Excel shows it;\n * `total_rows`, every row under its columns.\n */\nexport interface PreviewSheet {\n  name: string;\n  columns: string[] | null;\n  rows: string[][];\n  total_rows: number;\n}\n\n/** A spreadsheet's sheets (20 at most), or a CSV as one, named as its file. */\nexport interface SheetPreview {\n  kind: \"sheet\";\n  sheets: PreviewSheet[];\n  /** Rows, columns (50 at most), long cells or sheets were left out. */\n  truncated: boolean;\n}\n\n/**\n * A Word file as simple HTML: headings, paragraphs, lists, tables, bold and italic, small\n * pictures as data URLs. Cleaned by the API against an allow-list: nothing in it runs, styles\n * or loads from another address.\n */\nexport interface DocumentPreview {\n  kind: \"document\";\n  html: string;\n  truncated: boolean;\n}\n\n/** A slide: its title (null without one), the words of its other shapes, its notes. */\nexport interface PreviewSlide {\n  title: string | null;\n  text: string;\n  notes: string | null;\n}\n\n/** A deck's slides, in order. */\nexport interface SlidesPreview {\n  kind: \"slides\";\n  slides: PreviewSlide[];\n  truncated: boolean;\n}\n\n/** Words as written: Markdown, plain text, JSON. */\nexport interface TextPreview {\n  kind: \"markdown\" | \"text\" | \"json\";\n  text: string;\n  truncated: boolean;\n}\n\n/** A source as written, never run (HTML too), in the language highlighters name it by. */\nexport interface CodePreview {\n  kind: \"code\";\n  text: string;\n  truncated: boolean;\n  language: string;\n}\n\n/** A picture, a video or a sound: the viewer plays the bytes, typed as `media_type`. */\nexport interface MediaPreview {\n  kind: \"image\" | \"video\" | \"audio\";\n  media_type: string;\n}\n\n/** Nothing to draw: a kind no viewer shows, or a file that can't be read; it is saved. */\nexport interface UnknownPreview {\n  kind: \"unknown\";\n}\n\n/**\n * What a viewer draws of a file (`GET …/preview`), by its `kind`. What is too long answers what\n * fits, with `truncated`.\n */\nexport type FilePreview =\n  | PdfPreview\n  | SheetPreview\n  | DocumentPreview\n  | SlidesPreview\n  | TextPreview\n  | CodePreview\n  | MediaPreview\n  | UnknownPreview;\n\n/**\n * A file the agent shows in a surface (`show`'s `file` block): it names one it may read (`path`:\n * its own or the organization's by path, or the conversation's by id), and the API fills in\n * `file`, the conversation's file it put there (`{conversationId, fileId}` to preview and fetch\n * it); null while there is none (the reply's message before the show ran, or one it refused).\n */\nexport interface FileBlock {\n  type: \"file\";\n  path: string;\n  /** Over it; none: its name. */\n  title?: string;\n  file: Attachment | null;\n}\n\n/** Who holds the conversation's browser: the agent drives it, or the person does. */\nexport type BrowserControl = \"agent\" | \"person\";\n\n/** Whose the browser is: a clean one in the cloud, or the owner's own Chrome. */\nexport type BrowserWhere = \"hosted\" | \"mine\";\n\n/**\n * The conversation's hosted browser, while it is open: where it is, who holds it, and, when the\n * agent handed it over, why (`reason`) and the step the person's answer carries on (`wait`).\n * `width` and `height` are the page's, the pixels its pointer events are in.\n */\nexport interface BrowserState {\n  where: BrowserWhere;\n  url: string;\n  title: string;\n  control: BrowserControl;\n  reason: string | null;\n  wait: string | null;\n  width: number;\n  height: number;\n}\n\n/** A picture of the browser's screen: a JPEG in base64, showing the page at this size. */\nexport interface BrowserFrame {\n  jpeg: string;\n  width: number;\n  height: number;\n}\n\n/**\n * What the person does on the browser's screen while they hold it, in the page's pixels: the\n * pointer, the wheel, keys (the DOM's `key`, `code` and `keyCode`; `modifiers` is Alt 1, Ctrl 2,\n * Meta 4, Shift 8) and text pasted.\n */\nexport type BrowserInput =\n  | {\n      kind: \"mouse\";\n      action: \"move\" | \"down\" | \"up\";\n      x: number;\n      y: number;\n      button?: \"left\" | \"middle\" | \"right\";\n      clicks?: number;\n    }\n  | { kind: \"wheel\"; x: number; y: number; dx: number; dy: number }\n  | {\n      kind: \"key\";\n      action: \"down\" | \"up\";\n      key: string;\n      code: string;\n      keyCode: number;\n      modifiers: number;\n    }\n  | { kind: \"paste\"; text: string };\n\n/**\n * What a person may know of the agent they talk to (`GET /agents/{id}/face`): its name, its role\n * in a line, the mark of its work (an `AgentIcon`; null until it picked one) and whether it takes\n * calls.\n */\n/**\n * How a web channel's widget looks (`PUT /channels/{id}/appearance`): each unset field keeps the\n * widget's own default (the page's type and ink, neutral greys). Colours are `#rrggbb`, sizes\n * pixels; `css` is the widget's own stylesheet, drawn inside it after ours.\n */\nexport interface WidgetLook {\n  accent?: string | null;\n  accent_fg?: string | null;\n  font?: WidgetFont | null;\n  radius?: number | null;\n  theme?: \"auto\" | \"light\" | \"dark\";\n  position?: \"right\" | \"left\";\n  launcher_size?: number | null;\n  panel_width?: number | null;\n  panel_height?: number | null;\n  header?: boolean;\n  css?: string | null;\n}\n\n/** The faces a widget may wear besides the page's own: Google Fonts it loads by name. */\nexport const WIDGET_FONTS = [\n  \"Inter\",\n  \"Manrope\",\n  \"DM Sans\",\n  \"Plus Jakarta Sans\",\n  \"Poppins\",\n  \"Nunito\",\n  \"Lora\",\n  \"Playfair Display\",\n] as const;\n\nexport type WidgetFont = (typeof WIDGET_FONTS)[number];\n\n/** What the widget reads as it loads, by its publishable key: its agent, and how it looks. */\nexport interface WidgetConfig {\n  agent_id: string;\n  agent_name: string;\n  appearance: WidgetLook;\n}\n\nexport interface AgentFace {\n  id: string;\n  name: string;\n  /** \"\" when it has none. */\n  role: string;\n  icon: string | null;\n  voice: { enabled: boolean };\n}\n\n/**\n * One of the host's own tools the agent called, to run in the page (a tool declared `client` on\n * the agent): the call's id, the tool's name, and what the agent gave it, as its JSON Schema says.\n */\nexport interface ToolCall {\n  id: string;\n  name: string;\n  input: Record<string, unknown>;\n}\n"],"mappings":";;AA8iBA,MAAa,eAAe;CAC1B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF"}

package/dist/useAgentFace.d.ts

@@ -0,0 +1,18 @@
+import { AgentFace } from "./types.js";
+import { Client } from "./client.js";
+//#region src/useAgentFace.d.ts
+/** The agent's face as it is read: null until it lands, with what the read threw if it failed. */
+export interface FaceRead {
+  face: AgentFace | null;
+  loading: boolean;
+  error: unknown;
+}
+/**
+ * What a person may know of agent `agentId` (`GET /agents/{id}/face`): its name, its role, the
+ * mark of its work and whether it takes calls, read once for each agent. Until it lands (and
+ * while another agent's is read) there is none; one that lands for an agent no longer asked
+ * about is dropped.
+ */
+export declare function useAgentFace(client: Client, agentId: string): FaceRead;
+//#endregion
+//# sourceMappingURL=useAgentFace.d.ts.map

package/dist/useAgentFace.js

@@ -0,0 +1,45 @@
+import { useEffect, useState } from "react";
+//#region src/useAgentFace.ts
+/**
+* What a person may know of agent `agentId` (`GET /agents/{id}/face`): its name, its role, the
+* mark of its work and whether it takes calls, read once for each agent. Until it lands (and
+* while another agent's is read) there is none; one that lands for an agent no longer asked
+* about is dropped.
+*/
+function useAgentFace(client, agentId) {
+	const [landed, setLanded] = useState(null);
+	useEffect(() => {
+		let asked = true;
+		client.agents.face(agentId).then((face) => {
+			if (asked) setLanded({
+				client,
+				agentId,
+				face,
+				error: null
+			});
+		}, (error) => {
+			if (asked) setLanded({
+				client,
+				agentId,
+				face: null,
+				error
+			});
+		});
+		return () => {
+			asked = false;
+		};
+	}, [client, agentId]);
+	return landed !== null && landed.client === client && landed.agentId === agentId ? {
+		face: landed.face,
+		loading: false,
+		error: landed.error
+	} : {
+		face: null,
+		loading: true,
+		error: null
+	};
+}
+//#endregion
+export { useAgentFace };
+
+//# sourceMappingURL=useAgentFace.js.map

package/dist/useAgentFace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentFace.js","names":[],"sources":["../src/useAgentFace.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\n\nimport type { Client } from \"./client\";\nimport type { AgentFace } from \"./types\";\n\n/** The agent's face as it is read: null until it lands, with what the read threw if it failed. */\nexport interface FaceRead {\n  face: AgentFace | null;\n  loading: boolean;\n  error: unknown;\n}\n\n/** A read that landed, and for which agent: one for another is not this one's. */\ninterface Landed {\n  client: Client;\n  agentId: string;\n  face: AgentFace | null;\n  error: unknown;\n}\n\n/**\n * What a person may know of agent `agentId` (`GET /agents/{id}/face`): its name, its role, the\n * mark of its work and whether it takes calls, read once for each agent. Until it lands (and\n * while another agent's is read) there is none; one that lands for an agent no longer asked\n * about is dropped.\n */\nexport function useAgentFace(client: Client, agentId: string): FaceRead {\n  const [landed, setLanded] = useState<Landed | null>(null);\n  useEffect(() => {\n    let asked = true;\n    client.agents.face(agentId).then(\n      (face) => {\n        if (asked) setLanded({ client, agentId, face, error: null });\n      },\n      (error: unknown) => {\n        if (asked) setLanded({ client, agentId, face: null, error });\n      },\n    );\n    return () => {\n      asked = false;\n    };\n  }, [client, agentId]);\n  const current = landed !== null && landed.client === client && landed.agentId === agentId;\n  return current\n    ? { face: landed.face, loading: false, error: landed.error }\n    : { face: null, loading: true, error: null };\n}\n"],"mappings":";;;;;;;;AA0BA,SAAgB,aAAa,QAAgB,SAA2B;CACtE,MAAM,CAAC,QAAQ,aAAa,SAAwB,IAAI;CACxD,gBAAgB;EACd,IAAI,QAAQ;EACZ,OAAO,OAAO,KAAK,OAAO,CAAC,CAAC,MACzB,SAAS;GACR,IAAI,OAAO,UAAU;IAAE;IAAQ;IAAS;IAAM,OAAO;GAAK,CAAC;EAC7D,IACC,UAAmB;GAClB,IAAI,OAAO,UAAU;IAAE;IAAQ;IAAS,MAAM;IAAM;GAAM,CAAC;EAC7D,CACF;EACA,aAAa;GACX,QAAQ;EACV;CACF,GAAG,CAAC,QAAQ,OAAO,CAAC;CAEpB,OADgB,WAAW,QAAQ,OAAO,WAAW,UAAU,OAAO,YAAY,UAE9E;EAAE,MAAM,OAAO;EAAM,SAAS;EAAO,OAAO,OAAO;CAAM,IACzD;EAAE,MAAM;EAAM,SAAS;EAAM,OAAO;CAAK;AAC/C"}