@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/types.ts

@@ -0,0 +1,596 @@
+/** The API's objects this package reads (v3/README.md). */
+
+import type { ChannelKind } from "./about";
+import type { Surface } from "./blocks";
+
+/** 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;
+}
+
+/** Where a file of a conversation plays from, until `expires_at`: a path under the API's root. */
+export interface FileLink {
+  path: string;
+  expires_at: string;
+}
+
+/** 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 const WIDGET_FONTS = [
+  "Inter",
+  "Manrope",
+  "DM Sans",
+  "Plus Jakarta Sans",
+  "Poppins",
+  "Nunito",
+  "Lora",
+  "Playfair Display",
+] as const;
+
+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>;
+}

package/src/useAgentFace.ts

@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react";
+
+import type { Client } from "./client";
+import type { AgentFace } from "./types";
+
+/** 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;
+}
+
+/** A read that landed, and for which agent: one for another is not this one's. */
+interface Landed {
+  client: Client;
+  agentId: string;
+  face: AgentFace | null;
+  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 function useAgentFace(client: Client, agentId: string): FaceRead {
+  const [landed, setLanded] = useState<Landed | null>(null);
+  useEffect(() => {
+    let asked = true;
+    client.agents.face(agentId).then(
+      (face) => {
+        if (asked) setLanded({ client, agentId, face, error: null });
+      },
+      (error: unknown) => {
+        if (asked) setLanded({ client, agentId, face: null, error });
+      },
+    );
+    return () => {
+      asked = false;
+    };
+  }, [client, agentId]);
+  const current = landed !== null && landed.client === client && landed.agentId === agentId;
+  return current
+    ? { face: landed.face, loading: false, error: landed.error }
+    : { face: null, loading: true, error: null };
+}